diff --git a/README.md b/README.md index 9afd727d..f2759fae 100644 --- a/README.md +++ b/README.md @@ -11,8 +11,10 @@ ## Features + The `copernicusmarine` offers capabilities through both **Command Line Interface (CLI)** and **Python API**: + - **Metadata Information**: List and retrieve metadata information on all variables, datasets, products, and their associated documentation. - **Subset Datasets**: Subset datasets to extract only the parts of interest, in preferred format, such as Analysis-Ready Cloud-Optimized (ARCO) Zarr or NetCDF file format. - **Advanced Filters**: Apply simple or advanced filters to get multiple files, in original formats like NetCDF/GeoTIFF, via direct Marine Data Store connections. @@ -20,56 +22,67 @@ The `copernicusmarine` offers capabilities through both **Command Line Interface ## Installation + For installation, multiple options are available depending on your setup: ### Mamba | Conda + A `conda` package is available on [Anaconda](https://anaconda.org/conda-forge/copernicusmarine). You can install it using `mamba` (or conda) through the `conda-forge` channel with the following command: + ```bash mamba install conda-forge::copernicusmarine --yes ``` To upgrade the Toolbox with mamba (or conda): + ```bash mamba update --name copernicusmarine copernicusmarine --yes ``` ### Docker + A docker image is also available here: [https://hub.docker.com/r/copernicusmarine/copernicusmarine](https://hub.docker.com/r/copernicusmarine/copernicusmarine) First step is to pull the container image: + ```bash docker pull copernicusmarine/copernicusmarine:latest ``` Then run it: + ```bash docker run -it --rm copernicusmarine/copernicusmarine --version ``` ### Pip + Otherwise, if you already have an environment (safer to clone it), the package can be installed using the `pip` command: + ```bash python -m pip install copernicusmarine ``` And to **upgrade the package** to the newest available version, run: + ```bash python -m pip install copernicusmarine --upgrade ``` ## User Guide + For more comprehensive details on how to use the `copernicusmarine` Toolbox, please refer to our [Help Center](https://help.marine.copernicus.eu/en/collections/9080063-copernicus-marine-toolbox). It ensures a smooth migration for existing users of legacy services such as MOTU, OPeNDAP or FTP. ### Network configuration @@ -161,6 +174,7 @@ You can use the `--skip-if-user-logged-in` option to skip the configuration file #### Access points migration and evolution + If you still have a configuration for legacy services (e.g. `~/motuclient/motuclient-python.ini`, `~/.netrc` or `~/_netrc`) in your home directory, it will automatically be taken into account with commands `get` and `subset` without the need for running the `login` command. If the configuration files are already available in another directory, when running commands `subset` or `get`, you can use the `--credentials-file` option to point to the files. @@ -389,6 +403,7 @@ Example of `file_list.txt` with paths that would be directly downloaded without > another_dataset/history/BO/AR_PR_BO_58JM.nc ``` + Example of `file_list.txt` with absolute paths: ```txt @@ -397,13 +412,11 @@ s3://mdl-native-10/native/IBI_MULTIYEAR_PHY_005_002/cmems_mod_ibi_phy_my_0.083de s3://mdl-native-10/native/IBI_MULTIYEAR_PHY_005_002/cmems_mod_ibi_phy_my_0.083deg-3D_P1M-m_202012/2021/CMEMS_v5r1_IBI_PHY_MY_PdE_01mav_20210301_20210331_R20230101_RE01.nc ``` -Example of `file_list.txt` with partial paths matching the absolute paths (equivalent to previous example): +Note that a path to a file can be seen in 3 parts: -```txt -CMEMS_v5r1_IBI_PHY_MY_NL_01yav_20000101_20001231_R20221101_RE01.nc -CMEMS_v5r1_IBI_PHY_MY_NL_01yav_20010101_20011231_R20221101_RE01.nc -CMEMS_v5r1_IBI_PHY_MY_NL_01yav_20020101_20021231_R20221101_RE01.nc -``` +- the provenance that indicates in which bucket the data is. For example, `s3://mdl-native-10/`. It can be found in the metadata. +- the productID and datasetID. For example, `IBI_MULTIYEAR_PHY_005_002/cmems_mod_ibi_phy_my_0.083deg-3D_P1M-m_202012/`. It also contains the version when the dataset has one. +- the filename which is everything that comes after the dataset id. For example, `2021/CMEMS_v5r1_IBI_PHY_MY_PdE_01mav_20210301_20210331_R20230101_RE01.nc`. It should be considered like a filename. If any components are absent, the file name is not complete and the file cannot be directly downloaded. Thus a listing of all the files is necessary in order to download the file. For example, `2021/CMEMS_v5r1_IBI_PHY_MY_PdE_01mav_20210301_20210331_R20230101_RE01.nc` is a filename and `CMEMS_v5r1_IBI_PHY_MY_PdE_01mav_20210301_20210331_R20230101_RE01.nc` is an incomplete filename. > **_NOTE:_** This option is compatible with the file generated by the `--create-file-list` option if you generated a ".txt" file. @@ -440,7 +453,7 @@ copernicusmarine get --dataset-id cmems_obs-ins_blk_phybgcwav_mynrt_na_irr --ind Returns: -```text +```txt INFO - 2024-04-03T12:58:40Z - Dataset version was not specified, the latest one was selected: "202311" INFO - 2024-04-03T12:58:40Z - Dataset part was not specified, the first one was selected: "history" INFO - 2024-04-03T12:58:40Z - You forced selection of service: original-files