Python Interface#
The altimetry_downloader_aviso tool provides a simple Python API to programmatically interact
with the Aviso catalog.
It exposes the Python functions equivalent to the CLI
Command Line Interface |
Python Function |
|---|---|
from altimetry_downloader_aviso import summary, details, get, get_product_from_short_name, filter_infos, subset
Basic Usage#
List available products#
Retrieve a summary of the available products in Aviso catalog using altimetry_downloader_aviso.summary() function. Retrieve an altimetry_downloader_aviso.AvisoCatalog object.
>>> catalog = summary()
>>> catalog
AvisoCatalog(products=[AvisoProduct(id='d1f06620-d11c-4945-b53d-6769e909be01', title='Wind & Wave product SWOT Level-3 WindWave - Extended'), ...])
To list available products in the catalog, use the altimetry_downloader_aviso.AvisoCatalog.products attribute, that is a list of altimetry_downloader_aviso.AvisoProduct objects.
>>> for product in catalog.products:
>>> print(f"{product.id} {product.title}")
SWOT_L3_LR_WIND_WAVE_Extended Wind & Wave product SWOT Level-3 WindWave - Extended
SWOT_L3_LR_SSH_Basic Altimetry product SWOT Level-3 Low Rate SSH - Basic
...
View product details#
Get detailed metadata for a given product using altimetry_downloader_aviso.details() function. It returns an altimetry_downloader_aviso.AvisoProduct object.
>>> product = altimetry_downloader_aviso.details("SWOT_L3_LR_SSH_Basic")
>>> print(product.abstract)
The SWOT L3_LR_SSH product provides ocean topography measurements obtained from the SWOT KaRIn and nadir altimeter instruments,...
Download a product#
Download a product using altimetry_downloader_aviso.get() function.
>>> local_files = get("SWOT_L3_LR_SSH_Basic", output_dir="aviso_dir", cycle_number=7, pass_number=[12, 13])
About to download 2 file(s),estimated total size: 7.7 MB
>>> print(local_files)
['aviso_dir/SWOT_L3_LR_SSH_Basic_007_012_20231123T193011_20231123T202137_v3.0.nc',
'aviso_dir/SWOT_L3_LR_SSH_Basic_007_013_20231123T202138_20231123T211304_v3.0.nc']
Note
By default, already existing files are not re-downloaded. Use overwrite=True parameter to force re-download.
Note
By default, get() prints an estimate of the total download size and
downloads data. Pass assume_yes=False parameter to display a confirmation
prompt on standard input before downloading.
Note
By default, get() does not display a progress bar (show_progress=False),
to avoid unwanted output in scripts and automated pipelines. Pass
show_progress=True to display one — useful for interactive use in a
notebook or a terminal session.
List filter values#
List the relevant filter values of the get command using the altimetry_downloader_aviso.filter_infos() function.
>>> product = get_product_from_short_name("SWOT_L3_LR_SSH_Basic")
>>> temporal_coverage, half_orbit_range, versions = filter_infos(product)
>>> print(temporal_coverage)
{'CALVAL': [2023-03-28T23:44:17.000000, 2023-07-10T09:12:05.000000], 'SCIENCE': [2023-07-26T12:27:56.000000, 2026-06-22T20:46:05.000000]}
>>> print(half_orbit_range)
{'CALVAL': ((474, 3), (578, 4)), 'SCIENCE': ((1, 149), (52, 99))}
>>> print(versions)
{'1.0.2', '3.0', '2.0', '2.0.1'}
Download a subset#
Downloading a subset of a product using altimetry_downloader_aviso.subset() function. It filters granules from the Aviso’TDS server, subset the datasets using OpenDAP protocol, and writes a subset file.
Cycle/pass, time, version and box filters are available.
The box filter can be used to download a spatial subset of the product. It should be provided as a tuple of four floats: (lon_min, lat_min, lon_max, lat_max).
An additional selected_variables filter can be used to download only a subset of the product variables. It should be provided as a list of strings.
Caution
- Subsetting is not implemented yet for the following products:
L4_with_SWOT
SWOT_L3_LR_SSH_Basic
SWOT_L3_LR_SSH_Expert
SWOT_L3_LR_WIND_WAVE_Light
SWOT_L3_LR_WIND_WAVE_Extended
SWOT_L2_LR_SSH_Unsmoothed
>>> local_files = subset(
"SWOT_L3_LR_SSH_Unsmoothed",
box=(-10, 10, 10, 40),
selected_variables=["ssha_unfiltered", "time"],
output_dir="aviso_dir",
cycle_number=1,
pass_number=[223, 225, 236],
version="3.0"
)
>>> print(local_files)
['aviso_dir/SWOT_L3_LR_SSH_Unsmoothed_001_223_20230729T035501_20230729T044628_v3.0.nc']