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
viresclient_ is a Python package which connects to a VirES server, of which there are two: *VirES for Swarm* (https://vires.services) and *VirES for Aeolus* (https://aeolus.services), through the WPS_ interface. This package handles product requests and downloads, enabling easy access to data and models from ESA's Earth Explorer missions, Swarm_ and Aeolus_. This service is provided for ESA by EOX_. For enquiries about the service and problems with accessing your account, please email info@vires.services. For help with usage, please email ashley.smith@ed.ac.uk (for Swarm data) or `raise an issue on GitHub`_.
20
+
``viresclient`` is a Python package which provides access to products (including on-demand processing) from two of ESA's Earth Explorer missions: `Swarm`_ and `Aeolus`_. This service is provided for ESA by EOX_. For enquiries about the service and problems with accessing your account, please email info@vires.services. For help with usage, please email ashley.smith@ed.ac.uk or `raise an issue on GitHub`_.
.. _`raise an issue on GitHub`: https://github.com/ESA-VirES/VirES-Python-Client/issues
33
27
34
-
For code recipes and more, see `Swarm Notebooks`_ & `Aeolus Notebooks`_. To start experimenting right away, *viresclient* is installed on the "Virtual Research Environment" (VRE), which is a managed Jupyter-based system provided for ESA by EOX. The service is free and open to all, accessible through your VirES account - check the notebooks to read more and get started.
28
+
There are two VirES services (Virtual environments for Earth Scientists) which *viresclient* can communicate with:
- JupyterHub: `Swarm VRE (Virtual Research Environment) <https://vre.vires.services>`_
35
+
- Swarm data documentation: `Swarm handbook <https://swarmhandbook.earth.esa.int>`_
36
+
- *Note that this service is not only for Swarm*:
37
+
38
+
- Multi-mission products including magnetometry from CHAMP, CryoSat-2, and more
39
+
- INTERMAGNET ground magnetometers via the ``AUX_OBS`` collection
40
+
- Custom geomagnetic model evaluation
41
+
42
+
- Read more about the ecosystem: `Python tools for ESA's Swarm mission: VirES for Swarm and surrounding ecosystem <https://doi.org/10.3389/fspas.2022.1002697>`_
43
+
44
+
- *VirES for Aeolus:*
45
+
46
+
- Interact with the `VirES for Aeolus graphical interface (web client) <https://aeolus.services>`_
- `Aeolus data documentation <https://earth.esa.int/eogateway/missions/aeolus/data>`_
38
50
39
51
Data and models are processed on demand on the VirES server - a combination of measurements from any time interval can be accessed. These are the same data that can be accessed by the VirES GUI. *viresclient* handles the returned data to allow direct loading as a single pandas.DataFrame_, or xarray.Dataset_.
40
52
@@ -109,3 +121,7 @@ You can reference *viresclient* directly using the DOI of our zenodo_ record. Vi
109
121
|"We use the Python package, viresclient [1], to access [...] from ESA's VirES for Swarm service [2]"
110
122
|[1] https://doi.org/10.5281/zenodo.2554162
111
123
|[2] https://vires.services
124
+
125
+
You can also cite this paper:
126
+
127
+
|Smith A.R.A., Pačes M. and Swarm DISC (2022) Python tools for ESA’s Swarm mission: VirES for Swarm and surrounding ecosystem. Front. Astron. Space Sci. 9:1002697. doi: 10.3389/fspas.2022.1002697
|e.g. geomagnetic coordinates (``QDLat``), orbit ascending/descending (``OrbitDirection``), geomagnetic activity (``Kp, Dst, dDst``), solar position (``SunZenithAngle``), ...
27
+
|See :ref:`Swarm auxiliaries<Swarm auxiliaries>`
25
28
**Geomagnetic model evaluation**
26
-
|Forwards evaluation of magnetic field models when a magnetic dataset is selected (e.g. ``MAGx_LR``). For more detail, see :ref:`Geomagnetic model handling`.
|`models` option in :py:meth:`viresclient.SwarmRequest.set_products`
29
+
30
+
- Forward evaluation of magnetic field models when a magnetic dataset is selected (e.g. ``MAGx_LR``) and using the `models` option in :py:meth:`viresclient.SwarmRequest.set_products`
31
+
- Model evaluation at user-provided coordinates. See:
Copy file name to clipboardExpand all lines: docs/geomagnetic_models.rst
+6-3Lines changed: 6 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,9 +8,11 @@ The geomagnetic models provided by VirES are all based on spherical harmonics, t
8
8
9
9
In VirES, we provide model evaluations calculated at the same sample points as the data products. This means that the spherical harmonic expansion is made at the time and location of each datapoint (e.g. in the case of ``MAGx_LR``, at every second). The main purpose is to provide the data-model residuals, or magnetic perturbations, useful for studying the external magnetic field, typically ionospheric in origin.
10
10
11
-
*Pending:* In a future VirES release, some interpolation will be used to provide the magnetic model predictions along the 50Hz ``MAGx_HR`` products (to improve speed). The predictions at the 1Hz (``MAGx_LR``) locations will be used and a cubic interpolation performed to provide the predictions at the 50Hz locations.
11
+
The magnetic data products provide the magnetic field vector as the parameter ``B_NEC`` in the geocentric NEC (North, East, Centre) frame, as well as the magnetic field intensity/magnitude (scalar), ``F``. When requesting models from VirES (by supplying the ``models`` kwarg to :py:meth:`viresclient.SwarmRequest.set_products`), the corresponding model predictions will be returned in parameters named ``B_NEC_<model-name>`` or ``F_<model-name>``. Alternatively, the data-model residual alone, named ``B_NEC_res_<model-name>`` or ``F_res_<model-name>`` can be returned directly by also supplying the kwarg ``residuals=True``. Models should be provided as a list, like ``models=["CHAOS", "IGRF"]``.
12
12
13
-
The magnetic data products provide the magnetic field vector as the parameter ``B_NEC`` in the NEC (North, East, Centre) frame, as well as the magnetic field intensity/magnitude (scalar), ``F``. When also requesting models from VirES (by supplying the ``models`` kwarg to :py:meth:`viresclient.SwarmRequest.set_products`), the corresponding model predictions will be returned in parameters named ``B_NEC_<model-name>`` or ``F_<model-name>``. Alternatively, the data-model residual alone, named ``B_NEC_res_<model-name>`` or ``F_res_<model-name>`` can be returned directly by also supplying the kwarg ``residuals=True``. Models should be provided as a list, like ``models=["CHAOS", "IGRF"]``.
13
+
When using high rate 50Hz ``MAGx_HR`` products, interpolatation is used to improve speed. The predictions at the 1Hz (``MAGx_LR``) locations are used and a cubic interpolation performed to provide the predictions at the 50Hz locations. This should be accurate enough for applications that we are aware of. To disable this interpolation, use ``do_not_interpolate_models=True`` in :py:meth:`viresclient.SwarmRequest.set_products`.
14
+
15
+
To evaluate models at arbitrary times and locations, see: :py:meth:`viresclient.SwarmRequest.eval_model` and :py:meth:`viresclient.SwarmRequest.eval_model_for_cdf_file`.
14
16
15
17
Available models
16
18
----------------
@@ -88,7 +90,8 @@ The predictions for these models are cached only at the positions and times defi
88
90
89
91
The logic describing when the cache is used is as follows:
.. note:: For VRE users (it's free! read more: `Swarm <https://notebooks.vires.services>`_, `Aeolus <https://notebooks.aeolus.services>`_), viresclient is already installed and configured so skip these steps
5
5
6
-
1. Installation
7
-
---------------
6
+
1. Installation and updating
7
+
----------------------------
8
8
9
-
Python ≥ 3.6 is required. Testing is primarily on Linux, but macOS and Windows should also work. Available through both pip and conda (conda-forge).
9
+
The package is available through both pip (PyPI) and conda (conda-forge). To add viresclient to an existing environment, use your preferred tool:
10
10
11
11
.. tabs::
12
12
13
13
.. group-tab:: pip
14
14
15
+
To install:
16
+
17
+
.. code-block:: sh
18
+
19
+
python -m pip install viresclient
20
+
21
+
To update:
22
+
23
+
.. code-block:: sh
24
+
25
+
python -m pip install --upgrade viresclient
26
+
27
+
.. tip::
28
+
29
+
If you are using an online notebook (e.g. Jupyter, Google Colab), you can run (in a notebook cell):
30
+
31
+
.. code-block:: sh
32
+
33
+
%pip install --upgrade viresclient
34
+
35
+
.. group-tab:: uv
36
+
37
+
To install:
38
+
39
+
(Assuming you use a `uv project <https://docs.astral.sh/uv/guides/projects/>`_)
40
+
15
41
.. code-block:: sh
16
42
17
-
pip install viresclient
43
+
uv add viresclient
44
+
45
+
To update:
46
+
47
+
.. code-block:: sh
48
+
49
+
uv sync --upgrade-package viresclient
18
50
19
51
.. group-tab:: conda
20
52
53
+
To install:
54
+
21
55
.. code-block:: sh
22
56
23
57
conda install --channel conda-forge viresclient
24
58
59
+
To update:
60
+
61
+
.. code-block:: sh
62
+
63
+
conda update --channel conda-forge viresclient
64
+
25
65
.. group-tab:: mamba
26
66
67
+
To install:
68
+
27
69
.. code-block:: sh
28
70
29
71
mamba install --channel conda-forge viresclient
30
72
73
+
To update:
74
+
75
+
.. code-block:: sh
76
+
77
+
mamba update --channel conda-forge viresclient
78
+
79
+
31
80
Recommended setup if starting without Python already
There are many ways to work with Python. We recommend using conda/mamba to manage your programming environment because of the availability of many data science packages through conda.
83
+
There are many ways to work with Python. Depending on your computing environment, we recommend using either:
84
+
85
+
- `uv <https://docs.astral.sh/uv/>`_: if your project relies specifically on Python packages (available via `PyPI <https://pypi.org/>`_) and you can use a system package manager (e.g. apt) to manage non-Python dependencies
86
+
- `Mamba <https://mamba.readthedocs.io/>`_ or `conda <https://docs.conda.io/projects/conda/>`_: which also manage non-Python dependencies (from `conda-forge <https://conda-forge.org/>`_)
87
+
88
+
- Use mamba preferably. It is a drop-in replacement for conda and is separate from Anaconda Inc.
89
+
- Use conda if you have an existing Anaconda or Miniconda installation
90
+
- `Pixi <https://pixi.sh/>`_: a newer tool that provides reproducible environments with lock files; works with both conda and pip packages (integrates with uv)
91
+
92
+
This guidance is appropriate for unix-like platforms (macOS & Linux & WSL). If you are using Windows, we recommend using `Windows Subsystem for Linux (WSL) <https://learn.microsoft.com/en-us/windows/wsl/>`_. While viresclient is compatible with Windows, you will get a more consistent experience with the scientific Python ecosystem by using WSL.
2. Create a new `project <https://docs.astral.sh/uv/guides/projects/>`_::
100
+
101
+
uv init --python 3.12 my-science-project
102
+
103
+
3. Enter the project and add some packages (including viresclient)::
104
+
105
+
cd my-science-project
106
+
uv add viresclient scipy matplotlib cartopy
107
+
108
+
4. Run code within the uv-managed environment. Either:
109
+
110
+
- Use `uv run <https://docs.astral.sh/uv/guides/scripts/>`_ to run scripts
111
+
- Activate the environment manually (``source .venv/bin/activate``)
112
+
- Configure your IDE to use this environment
113
+
- `Launch JupyterLab together with your project's dependencies <https://docs.astral.sh/uv/guides/integration/jupyter/>`_::
114
+
115
+
cd my-science-project
116
+
uv run --with jupyter jupyter lab
117
+
118
+
You should avoid using pip to install or update packages. By instead using ``uv add <package>``, or ``uv sync --upgrade-package <package>``, this lets uv track your project's dependencies (via the ``pyproject.toml`` file) and the exact versions used (via the ``uv.lock`` file) to help with safer updates and additions to the environment, and to ensure reproducibility.
1. (If you do not have conda already) Install Miniconda: https://docs.conda.io/en/latest/miniconda.html
41
123
42
124
2. Set the conda-forge channel as the priority to install packages from::
43
125
@@ -46,28 +128,55 @@ There are many ways to work with Python. We recommend using conda/mamba to manag
46
128
47
129
You should do this to avoid mixing packages from the anaconda channel (which can result in broken environments), and try to get all packages from conda-forge where available for consistency.
48
130
49
-
3. Create a new conda environment with some recommended packages, including viresclient::
131
+
3. Create a new environment with some packages (including viresclient)::
4. Activate the new environment (you do this each time you want to use it)::
54
136
55
137
conda activate myenv
56
138
57
-
.. group-tab:: mamba
139
+
5. Or run a command directly from within the environment (without needing to activate it), e.g.::
140
+
141
+
conda run -n myenv jupyter lab
58
142
59
-
`Mamba <https://mamba.readthedocs.io/>`_ is a drop-in replacement for conda. You can install it into an existing (base) conda environment (``conda install -c conda-forge mamba``) and then just use ``mamba`` in place of ``conda`` in any commands - mamba is significantly faster. You can also install *mambaforge* directly to get mamba and conda-forge immediately configured in the base environment.
143
+
.. group-tab:: mamba
60
144
61
-
1. Download and install the `mambaforge installer <https://github.com/conda-forge/miniforge#mambaforge>`_ or check the `mamba documentation <https://mamba.readthedocs.io/en/latest/installation.html>`_
145
+
1. Download and install `Miniforge <https://mamba.readthedocs.io/en/latest/installation/mamba-installation.html>`_
62
146
63
-
2. Create a new environment for your development work::
147
+
2. Create a new environment with some packages (including viresclient)::
- `Python in Heliophysics Community environment (pyhc-environment) <https://hub.docker.com/r/spolson/pyhc-environment>`_
166
+
167
+
.. group-tab:: cloud / online
168
+
169
+
Online services provide access to a range of scientific software within a Jupyter environment. viresclient may be pre-installed or can be added as above.
170
+
171
+
- `ESA Swarm VRE <https://vre.vires.services/>`_
172
+
173
+
- Run by us in connection with VirES (free self-signup, included with your VirES account)
0 commit comments