Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

Harmony

Harmony is Earthdata’s data transformation service for customizing NASA datasets. It is seamlessly integrated into the Earthdata Search platform, but users can also leverage the Harmony APIs or the Harmony-py Python library to interact with the data programmatically.

Download Customization Service

ASF and the Harmony team have developed a service for NISAR file customization, allowing users to extract individual datasets from NISAR HDF5 files as GeoTIFFs and optionally spatially subset and/or reproject them.

This Harmony service can be used to customize downloads for the following NISAR products:

Refer to the Tools and Services Roadmap to see the plan for additional Harmony service development in support of NISAR.

Dataset Extraction

This service provides Variable Subsetting, which extracts two-dimensional datasets from the /science/LSAR/$product-type/grids/ group as stand-alone Cloud-Optimized GeoTIFF (COG) files. This is particularly useful for users who are interested in accessing only one or two of the datasets in a NISAR HDF5 product or spatially subsetting datasets to a portion of the full product extent.

Because the HDF5 files are more compressed, users who want access to multiple layers for the full file extent may be better served by downloading the full HD5 file, as they are more efficient to download than extracted GeoTIFF files.

Note that in the Harmony interface, HDF5 datasets are referred to as ‘variables’.

Option: Extract a Spatial Subset

The Spatial Subsetting option subsets extracted datasets to the spatial filter used in Earthdata Search. Note that this option is only enabled when a Spatial Filter is applied during the search.

Option: Reproject Extracted Datasets

The Output Projection Selection option reprojects the output COGs to the selected coordinate system. Supported coordinate systems include:

For more information on supported NISAR projections, see NISAR Level 2 Projections.

Customize Downloads in Earthdata Search

Harmony services are available directly in Earthdata Search, which is a map-based web browser interface for data search and access. This makes it easy to find NISAR products for your area and time period of interest and extract just the datasets of interest from the HDF5 file. Each selected dataset is output as a Cloud Optimized GeoTIFF (COG) file.

Select Products

  1. Search for one of the supported product types in Earthdata Search and select the desired collection. To spatially subset NISAR products, make sure to use Spatial Filters to define your desired AOI.

    Screenshot of searching for a GCOV product in Earthdata Search

    Figure 1:Search for supported product type collections in Earthdata Search and select the desired collection.

  2. Add one or more granules to a project by clicking the green + icon for each item of interest.

    Screenshot of adding an item to a project in Earthdata Search

    Figure 2:Click the green + icon for a granule of interest to add it to your project.

  3. Click the My Project button to view the list of granules you’ve added.

    • You will need to log in with your Earthdata Login credentials if you have not already done so.

    Screenshot of opening the My Project pane in Earthdata Search

    Figure 3:Click the My Project button to view the list of granules you’ve added.

  4. If necessary, click the Edit Options button for the project to view the download and customization options.

    • If you add datasets for multiple collections to the same project, each collection will be listed in the left panel. You can switch collections by clicking the Edit Options link for the desired collection.

    Screenshot of accessing the download options for each collection when multiple collections are added to the same project

    Figure 4:When multiple collections are included in the project, click the Edit Options link for each collection to set the variables to extract.

Set Customization Options

  1. In the Edit Options menu, check the circle next to Customize Download to display the customization options.

    Screenshot of selecting the option to customize download and clicking the Edit Variables button

    Figure 5:Select the Customize Download option and select your desired customization settings.

    Spatial Subsetting

    If a spatial filter has been defined, the spatial constraint will be listed in the Spatial Subsetting section. Check the box next to the Trim output granules to the selected spatial constraint option to clip the datasets to the indicated extent.

    Screenshot of the Spatial Subsetting options section

    Figure 6:Check the box to clip the output datasets to the spatial extent defined with the Spatial Filter tool in the Earthdata Search interface.

    Variable Subsetting

    To select datasets to extract, click the Edit Variables button in the Variable Subsetting section. If no datasets are selected, every gridded dataset available in the list of variables will be extracted to individual GeoTIFFs, which will increase processing time.

    Screenshot of the Variable Subsetting section

    Figure 7:Click the Edit Variables button to choose which datasets to extract from the HDF5 file.

    Expand the HDF5 group structure by clicking on the directory icons to see their contents, as shown in Figure 8. Check the boxes next to the datasets you want to extract, then click the Back to Edit Options link near the top of the window.

    Screenshot of selecting the datasets to extract from a NISAR HDF5 file

    Figure 8:Expand the directory structure and select the datasets to be extracted to GeoTIFF format.

    • When selecting datasets to extract, note that a product may not contain all of the datasets listed in the interface. This list includes all possible datasets that may be present in a product of that type. As long as at least one of the selected datasets is available in the product, the Harmony job will run.

      • GeoTIFFs will be generated for any selected datasets that are present in the product, and any selected datasets that are not present will be ignored.

      • If you do not see a download link for a dataset you selected, refer to the file naming convention to verify which polarizations and frequencies would be expected for that product.

    Output Format Conversion

    The only output file format currently available for extracted NISAR datasets is Cloud Optimized GeoTIFF (COG). The drop-down menu in the Output Format Conversion section provides output options of Default Format and GEOTIFF. Choosing either of these options will export the selected NISAR datasets as COGs.

    Screenshot of selecting the output file format for extracted NISAR datasets

    Figure 9:Either leave the setting as Default Format or select GEOTIFF from the menu to output the extracted NISAR datasets in Cloud Optimized GeoTIFF (COG) format.

    When working with GCOV products, the drop-down menu may also include a PNG option. Selecting this format would trigger a different Harmony transformation service that would not perform the dataset extraction. The PNG menu item will be greyed out and non-selectable for most users.

    Output Projection Selection

    By default, the Output Projection Selection option is set to No Reprojection and the output files are in the same coordinate system as the source HDF5 file. Refer to NISAR Level 2 Projections for more information about the projections used by the NISAR project.

    Screenshot of the options in the Output Projection Selection section

    Figure 10:Leave the Output Projection Selection as the default No Projection option to output the extracted datasets in the same projection as the source HDF5 file, or select a different projection from the available options in the drop-down menu.

    If you would like to reproject the extracted datasets, select the desired output coordinate system from the list of options in the drop-down menu. This function currently only supports reprojection to the WGS84 Geographic Coordinate system or any of the projections used by the NISAR project, as listed in Option: Reproject Extracted Datasets.

Download Extracted Datasets

  1. Once customization options are defined, press the Download Data button to submit your data for processing.

    Screenshot highlighting the **Download Data** button

    Figure 11:Click the Download Data button to submit your data for processing.

    • If multiple collections are included in the Project, you will need to define the download options for each one. You can either:

      • Click the Edit Options link for each collection, as illustrated in Figure 4.

      • Click the Back to Edit Options link at the top of the panel once you have selected the desired datasets and click the Next button to progress through each collection.

        Screenshot of using the Next button to access the download options for each collection when multiple collections are added to the same project

        Figure 12:To set download options when multiple collections are included in the project, click the Next button at the bottom of the Edit Options panel to move to the next collection.

    • The Download Data button will launch the Harmony jobs for all collections in the project that have customization options defined.

  2. Harmony will process your request and indicate its progress on the status page. You may need to refresh the status page to see updated progress.

    Screenshot of the Harmony Status page in Earthdata Search

    Figure 13:Once you click the Download Data button, the Harmony Status page will open and indicate progress.

  3. Once processing is complete, the download links for the individual GeoTIFFs will be displayed. Click each link to download the products through the web browser, or click the Download Files button to leverage the Earthdata bulk download app.

    Screenshot of the Harmony Status page in Earthdata Search showing a completed job

    Figure 14:Once processing is complete, the Harmony Status page will display the download links for the extracted GeoTIFFs.