Installation and First Usage
Contents
Installation and First Usage#
Note
For VRE users (it’s free! read more: Swarm, Aeolus), viresclient is already installed and configured so skip these steps
1. Installation#
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).
pip install viresclient
conda install --channel conda-forge viresclient
mamba install --channel conda-forge viresclient
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.
Install Miniconda: https://docs.conda.io/en/latest/miniconda.html
Set the conda-forge channel as the priority to install packages from:
conda config --add channels conda-forge conda config --set channel_priority strict
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.
Create a new conda environment with some recommended packages, including viresclient:
conda create --name myenv python=3.10 jupyterlab scipy matplotlib pandas xarray cartopy h5py netCDF4 pytables ipywidgets viresclient
Activate the new environment (you do this each time you want to use it):
conda activate myenv
Mamba 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.
Download and install the mambaforge installer or check the mamba documentation
Create a new environment for your development work:
mamba create --name myenv python=3.10 jupyterlab scipy matplotlib pandas xarray cartopy h5py netCDF4 pytables ipywidgets viresclient
Activate it to use it:
mamba activate myenv
2. First usage / Configuration#
Note
For Jupyter notebook users, just try:
from viresclient import SwarmRequest
request = SwarmRequest()
and you will automatically be prompted to set a token.
A first usage guide is provided as a Jupyter notebook (view). To run the notebook on your computer running Jupyter locally, right click here to download, or use git to get the whole example repository:
git clone https://github.com/Swarm-DISC/Swarm_notebooks.git
Access to the service is through the same user account as on the web interface (https://vires.services/) and is enabled through an access token (essentially a password). To get a token, log in to the website and click on your name on the top right to access the settings (or follow this link). From here, click on “Manage access tokens” and follow the instructions to create a new token.
To set your token in the client, use either the Python interface:
from viresclient import set_token
set_token("https://vires.services/ows")
# (you will now be prompted to enter the token)
or the command line tool:
$ viresclient set_token https://vires.services/ows
Enter access token: r-8-mlkP_RBx4mDv0di5Bzt3UZ52NGg-
$ viresclient set_default_server https://vires.services/ows
See also: see Configuration Details and Access Token Management
Note
For Jupyter notebook users, just try:
from viresclient import AeolusRequest
request = AeolusRequest()
and you will automatically be prompted to set a token.
A first usage guide is provided as a Jupyter notebook (view). To run the notebook on your computer running Jupyter locally, right click here to download, or use git to get the whole example repository:
git clone https://github.com/ESA-VirES/Aeolus-notebooks.git
Access to the service is through the same user account as on the web interface (https://aeolus.services/) and is enabled through an access token (essentially a password). To get a token, log in to the website and click on your name on the top right to access the settings (or follow this link). From here, click on “Manage access tokens” and follow the instructions to create a new token.
To set your token in the client, use either the Python interface:
from viresclient import set_token
set_token("https://aeolus.services/ows")
# (you will now be prompted to enter the token)
or the command line tool:
$ viresclient set_token https://aeolus.services/ows
Enter access token: r-8-mlkP_RBx4mDv0di5Bzt3UZ52NGg-
$ viresclient set_default_server https://aeolus.services/ows
See also: see Configuration Details and Access Token Management
3. Example use#
Note
A brief introduction is given here. For more possibilities, see Introduction to notebooks, and VirES capabilities.
See also Swarm access through VirES
Choose which collection to access (see Available parameters for Swarm for more options):
import datetime as dt
from viresclient import SwarmRequest
request = SwarmRequest()
request.set_collection("SW_OPER_MAGA_LR_1B")
Next, use .set_products()
to choose a combination of variables to retrieve, specified by keywords.
measurements
are measured by the satellite and members of the specifiedcollection
models
are evaluated on the server at the positions of the satelliteauxiliaries
are additional parameters not unique to thecollection
if
residuals
is set toTrue
then only data-model residuals are returnedoptionally use
sampling_step
to specify a resampling of the original time series (an ISO-8601 duration).
request.set_products(
measurements=["F", "B_NEC"],
models=["MCO_SHA_2C", "MMA_SHA_2C-Primary", "MMA_SHA_2C-Secondary"],
auxiliaries=["QDLat", "QDLon", "MLT", "OrbitNumber", "SunZenithAngle"],
residuals=False,
sampling_step="PT10S"
)
Set a parameter range filter to apply. You can add multiple filters in sequence.
request.set_range_filter(parameter="Latitude", minimum=0, maximum=90)
request.set_range_filter("Longitude", 0, 90)
Specify the time range from which to retrieve data, make the request to the server:
data = request.get_between(
start_time=dt.datetime(2016,1,1),
end_time=dt.datetime(2016,1,2)
)
Transfer your data to a pandas.DataFrame, or a xarray.Dataset, or just save it as is:
df = data.as_dataframe()
ds = data.as_xarray()
data.to_file('outfile.cdf', overwrite=False)
The returned data has columns for:
Spacecraft, Timestamp, Latitude, Longitude, Radius
those specified by
measurements
andauxiliaries
… and model values and residuals, named as:
F_<model_id>
– scalar fieldB_NEC_<model_id>
– vector fieldF_res_<model_id>
– scalar field residual (F - F_<model_id>
)B_NEC_res_<model_id>
– vector field residual (B_NEC - B_NEC_<model_id>
)