Reference Guide for l2ss-py

l2ss-py

develop:
main:

Harmony service for subsetting L2 data. l2ss-py supports:

Spatial subsetting
- Bounding box
- Shapefile subsetting
- GeoJSON subsetting
Temporal subsetting
Variable subsetting
Vertical subsetting

If you would like to contribute to l2ss-py, refer to the contribution document.

Initial setup, with poetry

Follow the instructions for installing poetry here.
Install l2ss-py, with its dependencies, by running the following from the repository directory:

poetry install

Note: l2ss-py can be installed as above and run without any dependency on harmony. However, to additionally test the harmony adapter layer, extra dependencies can be installed with poetry install -E harmony.

How to test l2ss-py locally

Unit tests

There are comprehensive unit tests for l2ss-py. The tests can be run as follows:

poetry run pytest -m "not aws and not integration" tests/

You can generate coverage reports as follows:

poetry run pytest --junitxml=build/reports/pytest.xml --cov=podaac/ --cov-report=html -m "not aws and not integration" tests/

Note: The majority of the tests execute core functionality of l2ss-py without ever interacting with the harmony python modules. The test_subset_harmony tests, however, are explicitly for testing the harmony adapter layer and do require the harmony optional dependencies be installed, as described above with the -E harmony argument.

l2ss-py script

You can run l2ss-py on a single granule without using Harmony. In order to run this, the l2ss-py package must be installed in your current Python interpreter

$ l2ss-py --help
usage: l2ss-py [-h] [--bbox BBOX BBOX BBOX BBOX] [--variables VARIABLES [VARIABLES ...]] [--min-time MIN_TIME] [--max-time MAX_TIME] [--cut] [--shapefile SHAPEFILE] [--pixel_subset] [--vertical-var VERTICAL_VAR] [--vertical-min VERTICAL_MIN] [--vertical-max VERTICAL_MAX]
               input_file output_file

Run l2ss-py

positional arguments:
  input_file            File to subset
  output_file           Output file

options:
  -h, --help            show this help message and exit
  --bbox BBOX BBOX BBOX BBOX
                        Bounding box in the form min_lon min_lat max_lon max_lat
  --variables VARIABLES [VARIABLES ...]
                        Variables, only include if variable subset is desired. Should be a space separated list of variable names e.g. sst wind_dir sst_error ...
  --min-time MIN_TIME   Min time. Should be ISO-8601 format. Only include if temporal subset is desired.
  --max-time MAX_TIME   Max time. Should be ISO-8601 format. Only include if temporal subset is desired.
  --cut                 If provided, scanline will be cut
  --shapefile SHAPEFILE
                        Path to either shapefile or geojson file used to subset the provided input granule
  --pixel_subset        To pixel cut based the lon lat on the bounding box
  --vertical-var VERTICAL_VAR
                        Name of the vertical variable to subset by (e.g., depth, altitude)
  --vertical-min VERTICAL_MIN
                        Minimum value for vertical subsetting (inclusive)
  --vertical-max VERTICAL_MAX
                        Maximum value for vertical subsetting (inclusive)

Additional subsetting options

The following options are also recorded in the output file’s metadata history for provenance and reproducibility:

--min-time and --max-time (temporal subsetting)
--variables (variable subsetting)
--vertical-var, --vertical-min, --vertical-max (vertical subsetting)
--cut, --pixel_subset, --shapefile, and --bbox (spatial subsetting)

All subsetting parameters used in a run are included in the output file’s history and history_json attributes.

For example:

l2ss-py /path/to/input.nc /path/to/output.nc --bbox -50 -10 50 10 --variables wind_speed wind_dir ice_age time --min-time '2015-07-02T09:00:00' --max-time '2015-07-02T10:00:00' --cut --vertical-var depth --vertical-min 0 --vertical-max 100

An addition to providing a bounding box, spatial subsetting can be achieved by passing in a shapefile or a geojson file.

poetry run l2ss-py /path/to/input.nc /path/to/output.nc --shapefile /path/to/test.shp

or

poetry run l2ss-py /path/to/input.nc /path/to/output.nc --shapefile /path/to/test.geojson

Running Harmony locally

In order to fully test l2ss-py with Harmony, you can run Harmony locally. This requires the data exists in UAT Earthdata Cloud.

Set up local Harmony instance. Instructions here
Add concept ID for your data to services.yml

Execute a local Harmony l2ss-py request. For example:

localhost:3000/YOUR_COLLECTION_ID/ogc-api-coverages/1.0.0/collections/all/coverage/rangeset?format=application%2Fx-netcdf4&subset=lat(-10%3A10)&subset=lon(-10%3A10)&maxResults=2

NASA EOSDIS Integration

Detailed instructions for integrating with EOSDIS can be found here.

Contents: