Reference Guide for l2ss-py
l2ss-py
Harmony service for subsetting L2 data. l2ss-py supports:
Spatial subsetting
Bounding box
Shapefile subsetting
GeoJSON subsetting
Temporal subsetting
Variable 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: run_subsetter.py [-h] [--bbox BBOX BBOX BBOX BBOX]
[--variables VARIABLES [VARIABLES ...]]
[--min-time MIN_TIME] [--max-time MAX_TIME] [--cut]
input_file output_file
Run l2ss-py
positional arguments:
input_file File to subset
output_file Output file
optional arguments:
-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
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
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:
- Subset Module
- subset.py
align_time_to_lon_dim()
apply_scale_offset()
calculate_chunks()
compute_coordinate_variable_names()
compute_utc_name()
convert_bbox()
convert_bound()
convert_time_from_description()
create_geospatial_bounding_box()
create_geospatial_bounds()
datetime_from_mjd()
ensure_counter_clockwise()
extract_epoch()
get_coordinate_variable_names()
get_east_west_lon()
get_hdf_type()
get_path()
get_time_epoch_var()
get_variable_data()
is_360()
is_time_mjd()
new_build_temporal_cond()
normalize_paths()
open_as_nc_dataset()
override_decode_cf_datetime()
remove_scale_offset()
set_json_history()
set_version_history()
shoelace_area()
subset()
subset_with_bbox()
subset_with_shapefile_multi()
test_access_sst_dtime_values()
translate_longitude()
translate_timestamp()
update_netcdf_attrs()
- Subset Harmony Module
- Run Subsetter Module