viresclient

https://viresclient.readthedocs.io/en/latest/
Admin
viresclient is a Python client library for accessing and retrieving Earth observation data and...
Tokens:94,304
Snippets:613
Trust Score:9.6
Update:1 month ago
Show doc for...
Tokens:
Raw
### Clone Aeolus notebooks repository

Source: https://viresclient.readthedocs.io/en/latest/_sources/installation.rst

Clone the Aeolus notebooks example repository to get the first usage guide notebook locally.

```bash
git clone https://github.com/ESA-VirES/Aeolus-notebooks.git
```

--------------------------------

### Clone Swarm notebooks repository

Source: https://viresclient.readthedocs.io/en/latest/_sources/installation.rst

Clone the Swarm notebooks example repository to get the first usage guide notebook locally.

```bash
git clone https://github.com/Swarm-DISC/Swarm_notebooks.git
```

--------------------------------

### Show uploads example (valid file)

Source: https://viresclient.readthedocs.io/en/latest/_sources/cli.rst

Example output for a valid uploaded file.

```bash
$ viresclient show_uploads https://vires.services/ows
69f91765-ce9f-4be3-8475-76f7e0eb1d92
  filename:      test.csv
  is valid:      True
  data start:    2016-01-01T00:30:00Z
  data end:      2016-01-01T04:30:00Z
  uploaded on:   2019-09-04T08:50:30.592982Z
  content type:  text/csv
  size:          421
  MD5 checksum:  8afe55c47385d1556117e81bf5ba8c34
  fields:
    B_C
    B_E
    B_N
    B_NEC
    Latitude
    Longitude
    Observatory
    Radius
    Timestamp
```

--------------------------------

### Upload file example with output

Source: https://viresclient.readthedocs.io/en/latest/_sources/cli.rst

Example of uploading a CSV file and the resulting output.

```bash
$ viresclient upload_file https://vires.services/ows ./test.csv
69f91765-ce9f-4be3-8475-76f7e0eb1d92[test.csv] uploaded
```

--------------------------------

### Example output of get_collection_info

Source: https://viresclient.readthedocs.io/en/latest/api.html

Displays an example response showing the format of the dict returned by get_collection_info.

```python
[{'name': 'SW_OPER_MAGA_LR_1B',
'productType': 'SW_MAGx_LR_1B',
'productCount': 3579,
'timeExtent': {'start': '2013-11-25T11:02:52Z',
'end': '2023-09-28T23:59:59Z'}}]
```

--------------------------------

### Quick start: SwarmRequest and AeolusRequest

Source: https://viresclient.readthedocs.io/en/latest/_sources/config_details.rst

Two separate examples for initializing request objects for VirES for Swarm and Aeolus services. The SwarmRequest example uses the VirES for Swarm URL, while the AeolusRequest example uses the Aeolus URL. Both are shown as alternatives in a tip box.

```python
from viresclient import SwarmRequest
r = SwarmRequest("https://vires.services/ows")
```

```python
from viresclient import AeolusRequest
r = AeolusRequest("https://aeolus.services/ows")
```

--------------------------------

### Show uploads example (invalid file)

Source: https://viresclient.readthedocs.io/en/latest/_sources/cli.rst

Example output for an invalid uploaded file, showing missing mandatory fields and constant fields.

```bash
$ viresclient show_uploads https://staging.vires.services/ows
eff3bd47-0098-45d3-ba9e-158bea0fae12
  filename:      test_incomplete.cdf
  is valid:      False
  data start:    2019-02-02T23:59:59Z
  data end:      2019-02-03T23:59:58Z
  uploaded on:   2019-09-11T08:04:58.055294Z
  content type:  application/x-cdf
  size:          959888
  MD5 checksum:  778cfe6e60568b08750187dfc917b3e8
  missing mandatory fields:
    Latitude
    Longitude
  constant fields:
    Radius=6371200.0
  fields:
    B_NEC
    F
    Radius
    Timestamp
```

--------------------------------

### Clear uploads example with output

Source: https://viresclient.readthedocs.io/en/latest/_sources/cli.rst

Example of removing an uploaded file and the resulting output.

```bash
$ viresclient clear_uploads https://vires.services/ows
69f91765-ce9f-4be3-8475-76f7e0eb1d92[test.csv] removed
```

--------------------------------

### Install viresclient with pip

Source: https://viresclient.readthedocs.io/en/latest/_sources/installation.rst

Installs viresclient from PyPI into the current environment.

```sh
python -m pip install viresclient
```

--------------------------------

### DataUpload class usage example

Source: https://viresclient.readthedocs.io/en/latest/_modules/viresclient/_api/upload.html

Example usage of the DataUpload class, showing how to instantiate it with a URL and token, upload files, retrieve information, clear uploads, and manage constant parameters.

```python
from viresclient import ClientConfig, DataUpload

du = DataUpload("https://vires.services", token="...")

cc = ClientConfig()
url = cc.default_url
du = DataUpload(url, **cc.get_site_config(url))

# upload file
info = du.post("example.csv")
print(info)

# get information about the uploaded files
info = du.get()
print(info)

# remove any uploaded files
du.clear()

# check if the upload is valid and get list of missing mandatory parameters
info = du.post("example.cdf")
is_valid = info.get('is_valid', True)
missing_fields = info.get('missing_fields', {}).keys()
print(is_valid, missing_fields)

# get constant parameters
id = info['identifier']
parameters = du.get_constant_parameters(id)
print(parameters)

# set new constant parameters
parameters = du.set_constant_parameters(id, {'Radius': 7000000, 'Latitude': 24.0})
print(parameters)

# clear all constant parameters
parameters = du.set_constant_parameters(id, {}, replace=True)
print(parameters)
```

--------------------------------

### Launch JupyterLab with uv

Source: https://viresclient.readthedocs.io/en/latest/_sources/installation.rst

Starts JupyterLab together with the project's dependencies using uv run.

```sh
cd my-science-project
uv run --with jupyter jupyter lab
```

--------------------------------

### Install viresclient with uv

Source: https://viresclient.readthedocs.io/en/latest/_sources/installation.rst

Adds viresclient as a dependency to a uv project.

```sh
uv add viresclient
```

--------------------------------

### ReturnedData usage example

Source: https://viresclient.readthedocs.io/en/latest/_modules/viresclient/_data_handling.html

Example usage of the ReturnedData class, showing how to access sources, data_filters, magnetic_models, and convert data to xarray, dataframe, or file.

```python
        ...
        data = request.get_between(..., ...)
        data.sources
        data.data_filters
        data.magnetic_models
        data.as_xarray()
        data.as_xarray_dict()
        data.as_dataframe(expand=True)
        data.to_file()
```

--------------------------------

### ClientConfig.get_site_config(url)

Source: https://viresclient.readthedocs.io/en/latest/api.html

Gets the configuration for a given URL.

```APIDOC
## ClientConfig.get_site_config(url)

### Description
Gets the configuration for a given URL.

### Method
Method

### Endpoint
ClientConfig.get_site_config(url)

### Parameters
#### Method Parameters
- **url** (str) - Required - The URL for which to retrieve the configuration.

### Returns
- **config** - The configuration for the given URL.

```

--------------------------------

### Get list of available CLI commands: viresclient --help

Source: https://viresclient.readthedocs.io/en/latest/_sources/cli.rst

Displays the list of available CLI commands.

```bash
$ viresclient --help
```

--------------------------------

### viresclient show_uploads example: valid CSV upload details

Source: https://viresclient.readthedocs.io/en/latest/cli.html

Example output of show_uploads for a valid CSV upload. It lists the upload ID, filename, validity, data range, upload time, content type, size, MD5 checksum, and fields.

```shell
$ viresclient show_uploads https://vires.services/ows
69f91765-ce9f-4be3-8475-76f7e0eb1d92
  filename:      test.csv
  is valid:      True
  data start:    2016-01-01T00:30:00Z
  data end:      2016-01-01T04:30:00Z
  uploaded on:   2019-09-04T08:50:30.592982Z
  content type:  text/csv
  size:          421
  MD5 checksum:  8afe55c47385d1556117e81bf5ba8c34
  fields:
    B_C
    B_E
    B_N
    B_NEC
    Latitude
    Longitude
    Observatory
    Radius
    Timestamp

```

--------------------------------

### ClientConfig example usage

Source: https://viresclient.readthedocs.io/en/latest/_modules/viresclient/_config.html

Shows how to instantiate ClientConfig with default or custom configuration file, print path and configuration, set default URL, set site config, and save.

```python
cc = ClientConfig()      # use default configuration file
cc = ClientConfig("./viresconf.ini")  # use custom configuration file

print(cc.path)           # print path
print(cc)                # print the whole configuration

cc.default_url = "https://foo.bar/ows"  # set default server

# access to credentials configuration ...
cc.set_site_config("https://foo2.bar/ows", token="...")

cc.save()    # save configuration
```

--------------------------------

### Get collection info with SwarmRequest.get_collection_info()

Source: https://viresclient.readthedocs.io/en/latest/_modules/viresclient/_client_swarm.html

Example usage of get_collection_info() to retrieve metadata for a collection, followed by the returned JSON-like list of dictionaries.

```python
from viresclient import SwarmRequest
request = SwarmRequest("https://vires.services/ows")
info = request.get_collection_info("SW_OPER_MAGA_LR_1B")
```

```python
[{'name': 'SW_OPER_MAGA_LR_1B',
'productType': 'SW_MAGx_LR_1B',
'productCount': 3579,
'timeExtent': {'start': '2013-11-25T11:02:52Z',
'end': '2023-09-28T23:59:59Z'}}]
```

--------------------------------

### Install viresclient with conda

Source: https://viresclient.readthedocs.io/en/latest/_sources/installation.rst

Installs viresclient from the conda-forge channel.

```sh
conda install --channel conda-forge viresclient
```

--------------------------------

### Install viresclient with mamba

Source: https://viresclient.readthedocs.io/en/latest/_sources/installation.rst

Installs viresclient from the conda-forge channel using mamba.

```sh
mamba install --channel conda-forge viresclient
```

--------------------------------

### ClientConfig.init(env_var_name='VIRES_ACCESS_CONFIG')

Source: https://viresclient.readthedocs.io/en/latest/api.html

Initializes the client configuration, optionally using an environment variable to locate the configuration file.

```APIDOC
## ClientConfig.init(env_var_name='VIRES_ACCESS_CONFIG')

### Description
Initializes the client configuration, optionally using an environment variable to locate the configuration file.

### Method
Method

### Endpoint
ClientConfig.init(env_var_name='VIRES_ACCESS_CONFIG')

### Parameters
#### Method Parameters
- **env_var_name** (str) - Optional - Name of the environment variable that holds the path to the configuration file. Defaults to 'VIRES_ACCESS_CONFIG'.

```

--------------------------------

### Example configuration file content

Source: https://viresclient.readthedocs.io/en/latest/_sources/config_details.rst

Shows the structure of the configuration file (default location ~/.viresclient.ini) with a section for the server URL and a default section. This is the file that is edited directly or by the configuration methods.

```ini
[https://vires.services/ows]
token = r-8-mlkP_RBx4mDv0di5Bzt3UZ52NGg-

[default]
url = https://vires.services/ows
```

--------------------------------

### Create a new uv project with Python 3.12

Source: https://viresclient.readthedocs.io/en/latest/_sources/installation.rst

Initializes a new uv project named my-science-project with Python 3.12.

```sh
uv init --python 3.12 my-science-project
```

--------------------------------

### Show current configuration: viresclient show_configuration

Source: https://viresclient.readthedocs.io/en/latest/_sources/cli.rst

Displays the current configuration.

```bash
$ viresclient show_configuration
...
```

--------------------------------

### Filter example: Label D/N/X

Source: https://viresclient.readthedocs.io/en/latest/api.html

Example filter: match records with Label set to D, N or X.

```text
"(Label == "D" OR Label == "N" OR Label = "X")"
```

--------------------------------

### Parse environment configuration with defaults

Source: https://viresclient.readthedocs.io/en/latest/_modules/viresclient/_config.html

Returns a dictionary with instance_name, default_server, and servers, using DEFAULT_SERVER as fallback for missing values and an empty dict for servers.

```python
def _parse_env_config(env_config):
    return {
        "instance_name": env_config.get("instance_name") or DEFAULT_SERVER,
        "default_server": env_config.get("default_server") or DEFAULT_SERVER,
        "servers": env_config.get("servers") or {},
    }
```

--------------------------------

### Filter example: Elevation >= 15

Source: https://viresclient.readthedocs.io/en/latest/api.html

Example filter: match values with Elevation greater than or equal to 15.

```text
"Elevation >= 15"
```

--------------------------------

### Create request using configuration file

Source: https://viresclient.readthedocs.io/en/latest/_sources/config_details.rst

Shows how to create a SwarmRequest when the configuration file is present. The first example omits the token but provides the URL, the second omits both URL and token, reading them from the configuration.

```python
# access token read from configuration
request = SwarmRequest(url="https://vires.services/ows")

# both default URL and access token read from configuration
request = SwarmRequest()
```

--------------------------------

### Install viresclient in a notebook with %pip

Source: https://viresclient.readthedocs.io/en/latest/_sources/installation.rst

Installs or upgrades viresclient directly from a Jupyter or Google Colab notebook cell.

```sh
%pip install --upgrade viresclient
```

--------------------------------

### Filter example: exclude Type 1 or 34

Source: https://viresclient.readthedocs.io/en/latest/api.html

Example filter: exclude records with Type set to 1 or 34.

```text
"(Type != 1 AND Type != 34) NOT (Type == 1 OR Type == 34)"
```

--------------------------------

### set_products

Source: https://viresclient.readthedocs.io/en/latest/_modules/viresclient/_client_swarm.html

Sets the combination of products to retrieve. If residuals=True then just get the measurement-model residuals, otherwise get both measurement and model values.

```APIDOC
## set_products

### Description
Sets the combination of products to retrieve. If residuals=True then just get the measurement-model residuals, otherwise get both measurement and model values.

### Method
set_products

### Parameters
- **measurements** (list(str)) - Optional - List of measurement names from available_measurements(collection_key).
- **models** (list(str)/dict) - Optional - List of model names from available_models() or a dictionary with custom expressions.
- **custom_model** (str) - Optional - Path to a custom model in .shc format.
- **auxiliaries** (list(str)) - Optional - List of auxiliary names from available_auxiliaries().
- **residuals** (bool) - Optional - If True, only return measurement-model residual (default: False).
- **sampling_step** (str) - Optional - ISO_8601 duration, e.g., PT10S for 10 seconds, PT1M for 1 minute.
- **ignore_cached_models** (bool) - Optional - If True, ignore cached models and calculate on-the-fly (default: False).
- **do_not_interpolate_models** (bool) - Optional - If True, do not interpolate models for HR collection from LR collection (default: False).

### Returns
- Returns self for chaining.
```

--------------------------------

### Initialize AeolusRequest for Aeolus

Source: https://viresclient.readthedocs.io/en/latest/config_details.html

Quick start for Jupyter notebooks: create an AeolusRequest object pointing to the Aeolus server. The token is not provided here; follow automatic instructions to configure it if not already set.

```python
from viresclient import AeolusRequest
r = AeolusRequest("https://aeolus.services/ows")
```

--------------------------------

### Filter example: Flags & 128 == 0

Source: https://viresclient.readthedocs.io/en/latest/api.html

Example filter: match records with Flag bit 7 set to 0.

```text
"Flags & 128 == 0"
```

--------------------------------

### viresclient clear_uploads example: remove test.csv

Source: https://viresclient.readthedocs.io/en/latest/cli.html

Example of removing an uploaded file. The output confirms the upload ID and filename were removed.

```shell
$ viresclient clear_uploads https://vires.services/ows
69f91765-ce9f-4be3-8475-76f7e0eb1d92[test.csv] removed

```

--------------------------------

### get(identifier=None)

Source: https://viresclient.readthedocs.io/en/latest/_modules/viresclient/_api/upload.html

Performs a REST/API GET request. If an identifier is provided, retrieves info about the uploaded item; otherwise, lists all uploaded items.

```APIDOC
## get(identifier=None)

### Description
Performs a REST/API GET request. If an identifier is provided, retrieves info about the uploaded item; otherwise, lists all uploaded items.

### Method
GET

### Endpoint
`{url}/{identifier}` (if identifier provided) or `{url}` (if not)

### Parameters
- **identifier** (string) - Optional - The identifier of the uploaded item.

### Response
#### Success Response (200)
- Returns the parsed JSON response.

#### Error Response
- Raises an exception with status code and reason if status is not 200.

### Example
python
client.get()  # list all
client.get('dataset_id')  # get specific

```

--------------------------------

### Python: ClientConfig to store token

Source: https://viresclient.readthedocs.io/en/latest/_sources/config_details.rst

Uses the ClientConfig class to set the site configuration with a token and default URL, then saves the configuration.

```python
from viresclient import ClientConfig

cc = ClientConfig()
cc.set_site_config("https://vires.services/ows", token="r-8-mlkP_RBx4mDv0di5Bzt3UZ52NGg-")
cc.default_url = "https://vires.services/ows"
cc.save()
```
Tokens:
Raw