You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
|<imgsrc="https://raw.githubusercontent.com/euroargodev/VirtualFleet_recovery/master/docs/img/logo-virtual-fleet-recovery.png"alt="VirtualFleet-Recovery logo"width="400"><br>``Virtual Fleet - Recovery`` is a CLI and webAPI to make predictions of Argo float positions|
|<imgsrc="https://raw.githubusercontent.com/euroargodev/VirtualFleet_recovery/master/docs/img/logo-virtual-fleet-recovery.png"alt="VirtualFleet-Recovery logo"width="400"><br>``Virtual Fleet - Recovery`` is a CLI to make predictions of Argo float positions|
New version compatible with [VirtualFleet 0.4.0](https://virtualfleet.readthedocs.io/en/latest/whats-new.html#v0-4-0-2-feb-2024) and using the [Copernicus Marine Toolbox](https://help.marine.copernicus.eu/en/collections/5821001-python-library-api) to retrieve GLORYS or ARMOR3D velocity fields.
10
+
11
+
# Documentation (preliminary)
12
+
13
+
## Overall prediction procedure
24
14
1. Given a specific float cycle to predict ``C``, we extract:
25
15
- space/time position of the previous cycle ``C-1``,
26
16
- configuration parameters of the previous cycle ``C-1``, such as parking depth, profiling depth and cycling period using the EA API (but these can be overwritten if necessary).
27
17
28
-
2. We download the hourly CMEMS velocity fields for a large region around the previous cycle ``C-1`` coordinates
18
+
2. We download the daily CMEMS velocity fields for a region around the previous cycle ``C-1`` coordinates
29
19
30
20
3. We run a VirtualFleet simulation:
31
21
- where we use a large number of virtual floats located with a random perturbations around the float cycle ``C-1`` position in space/time
32
22
- for the cycle ``C-1`` duration
33
23
34
24
4. We compute the most probable position of the float cycle ``C`` and prediction metrics and figures.
35
25
36
-
The reason why we make random perturbations of the float cycle ``C-1`` position is not because the float position is uncertain (with GPS it is fairly accurate most of the time), but because it is a cheap way to account for errors in the velocity field. Indeed, we assume that the _phase_ of the velocity field used to advect floats is the primary source of uncertainties to predict the final position. We do not account for strain errors at this point.
26
+
The reason why we make random perturbations of the float cycle ``C-1`` position is not because the float position is uncertain (with GPS it is fairly accurate most of the time), but because it is a cheap way to account for errors in the velocity field. Indeed, we assume that the _phase_ of the velocity field used to advect floats is the primary source of uncertainties to predict the final position. We do not account for velocity shear/strain errors at this point.
37
27
38
28
## Installation
39
-
- Get this repository:
29
+
30
+
Our goal is to distribute VFrecovery as a standalone pipy package. In the meantime, one need to work with this repo only.
Virtual floats cycle duration in [hours], default: use previous cycle value
97
92
98
93
This script can be used to make prediction of a specific float cycle position.
99
-
This script is for testing the prediction system.
100
-
Note that in order to download online velocity field from 'https://nrt.cmems-du.eu', you need to set the environment variables: MOTU_USERNAME and MOTU_PASSWORD.
94
+
This script can be used on past or unknown float cycles.
95
+
Note that in order to download online velocity fields from the Copernicus Marine Data Store, you need to have the
96
+
appropriate credentials file setup.
101
97
102
-
(c) Argo-France/Ifremer/LOPS, 2022
98
+
(c) Argo-France/Ifremer/LOPS, 2022-2024
103
99
```
104
100
105
101
So, don't forget to:
106
-
- set the environment variables ``MOTU_USERNAME`` and ``MOTU_PASSWORD``to be able to download the velocity field
102
+
- set up your environment to be able to download velocity fields from the Copernicus Marine Toolbox
107
103
- use the option ``vf`` to specify where the VirtualFleet software has been cloned (this is temporary and will change once VirtualFleet will be available on Pypi).
108
104
109
105
### Example
@@ -115,63 +111,3 @@ Below is an example of this prediction for the 99th cycle of the 6902919 float.
115
111
The really observed 99th cycle is shown at the tip of the arrow (red point) starting from the previous 98th cycle.
116
112
The VirtualFleet Recovery prediction is in the probabilistic red shading: the most probable position predicted is in the redder region.
In order to easily use prediction results with other (web)applications, we set-up a small web API based on [Flask](https://flask.palletsprojects.com/).
122
-
123
-
### Server set up
124
-
125
-
If you used the environment provided with this repo you already have Flask installed.
126
-
In order to set up the (dev) server to access the VirtualFleet Recovery web API, open a terminal, navigate to the ``webapi`` folder and type:
127
-
```bash
128
-
export FLASK_DEBUG=True
129
-
export FLASK_APP=myapp
130
-
flask -A myapp run
131
-
```
132
-
133
-
### Usage
134
-
135
-
You should know the <IP> address of the server where the Flask app is running.
136
-
137
-
#### Make a prediction
138
-
139
-
**Method 1**
140
-
141
-
Simply visit the prediction triggering form at:
142
-
143
-
```
144
-
http://<IP>:5000/trigger
145
-
```
146
-
147
-
**Method 2**
148
-
149
-
Go the full webAPI way: to make a prediction for the position of the ``CYC`` cycle from float ``WMO``, send a POST, request to:
150
-
```
151
-
http://<IP>:5000/predict/<WMO>/<CYC>
152
-
```
153
-
This will return a json file with the prediction results. Predictions are saved in cache, so that if you send a request for a prediction already computed, you will have the json results right away.
154
-
155
-
Options available :
156
-
-``velocity``: to select the velocity field to use, it can be ``ARMOR3D`` (default) or ``GLORYS``
157
-
-``nfloats``: to set the number of virtual floats to use in the probabilistic prediction. The default value is 2000.
158
-
-``cfg_parking_depth``: to set the parking depth, in db, of virtual floats. The default values is that of the previous cycle.
159
-
-``cfg_cycle_duration``: to set the cycle duration, in hours, of virtual floats. The default values is that of the previous cycle.
|<imgsrc="https://raw.githubusercontent.com/euroargodev/VirtualFleet_recovery/master/docs/img/logo-virtual-fleet-recovery.png"alt="VirtualFleet-Recovery logo"width="400"><br>``Virtual Fleet - Recovery`` is a CLI and webAPI to make predictions of Argo float positions|
1. Given a specific float cycle to predict ``C``, we extract:
25
+
- space/time position of the previous cycle ``C-1``,
26
+
- configuration parameters of the previous cycle ``C-1``, such as parking depth, profiling depth and cycling period using the EA API (but these can be overwritten if necessary).
27
+
28
+
2. We download the hourly CMEMS velocity fields for a large region around the previous cycle ``C-1`` coordinates
29
+
30
+
3. We run a VirtualFleet simulation:
31
+
- where we use a large number of virtual floats located with a random perturbations around the float cycle ``C-1`` position in space/time
32
+
- for the cycle ``C-1`` duration
33
+
34
+
4. We compute the most probable position of the float cycle ``C`` and prediction metrics and figures.
35
+
36
+
The reason why we make random perturbations of the float cycle ``C-1`` position is not because the float position is uncertain (with GPS it is fairly accurate most of the time), but because it is a cheap way to account for errors in the velocity field. Indeed, we assume that the _phase_ of the velocity field used to advect floats is the primary source of uncertainties to predict the final position. We do not account for strain errors at this point.
--velocity VELOCITY Velocity field to use. Possible values are: 'ARMOR3D' (default), 'GLORYS'
88
+
--save_figure SAVE_FIGURE
89
+
Should we save figure on file or not ? Default: True
90
+
--save_sim SAVE_SIM Should we save the simulation on file or not ? Default: False
91
+
--vf VF Parent folder to the VirtualFleet repository clone
92
+
--json Use to only return a json file and stay quiet
93
+
--cfg_parking_depth CFG_PARKING_DEPTH
94
+
Virtual floats parking depth in [db], default: use previous cycle value
95
+
--cfg_cycle_duration CFG_CYCLE_DURATION
96
+
Virtual floats cycle duration in [hours], default: use previous cycle value
97
+
98
+
This script can be used to make prediction of a specific float cycle position.
99
+
This script is for testing the prediction system.
100
+
Note that in order to download online velocity fields from 'https://nrt.cmems-du.eu', you need to set the environment variables: MOTU_USERNAME and MOTU_PASSWORD.
101
+
102
+
(c) Argo-France/Ifremer/LOPS, 2022
103
+
```
104
+
105
+
So, don't forget to:
106
+
- set the environment variables ``MOTU_USERNAME`` and ``MOTU_PASSWORD`` to be able to download the velocity field
107
+
- use the option ``vf`` to specify where the VirtualFleet software has been cloned (this is temporary and will change once VirtualFleet will be available on Pypi).
108
+
109
+
### Example
110
+
111
+
```
112
+
recovery_prediction.py 6902915 116
113
+
```
114
+
Below is an example of this prediction for the 99th cycle of the 6902919 float.
115
+
The really observed 99th cycle is shown at the tip of the arrow (red point) starting from the previous 98th cycle.
116
+
The VirtualFleet Recovery prediction is in the probabilistic red shading: the most probable position predicted is in the redder region.
In order to easily use prediction results with other (web)applications, we set-up a small web API based on [Flask](https://flask.palletsprojects.com/).
122
+
123
+
### Server set up
124
+
125
+
If you used the environment provided with this repo you already have Flask installed.
126
+
In order to set up the (dev) server to access the VirtualFleet Recovery web API, open a terminal, navigate to the ``webapi`` folder and type:
127
+
```bash
128
+
export FLASK_DEBUG=True
129
+
export FLASK_APP=myapp
130
+
flask -A myapp run
131
+
```
132
+
133
+
### Usage
134
+
135
+
You should know the <IP> address of the server where the Flask app is running.
136
+
137
+
#### Make a prediction
138
+
139
+
**Method 1**
140
+
141
+
Simply visit the prediction triggering form at:
142
+
143
+
```
144
+
http://<IP>:5000/trigger
145
+
```
146
+
147
+
**Method 2**
148
+
149
+
Go the full webAPI way: to make a prediction for the position of the ``CYC`` cycle from float ``WMO``, send a POST, request to:
150
+
```
151
+
http://<IP>:5000/predict/<WMO>/<CYC>
152
+
```
153
+
This will return a json file with the prediction results. Predictions are saved in cache, so that if you send a request for a prediction already computed, you will have the json results right away.
154
+
155
+
Options available :
156
+
-``velocity``: to select the velocity field to use, it can be ``ARMOR3D`` (default) or ``GLORYS``
157
+
-``nfloats``: to set the number of virtual floats to use in the probabilistic prediction. The default value is 2000.
158
+
-``cfg_parking_depth``: to set the parking depth, in db, of virtual floats. The default values is that of the previous cycle.
159
+
-``cfg_cycle_duration``: to set the cycle duration, in hours, of virtual floats. The default values is that of the previous cycle.
0 commit comments