Welcome to GSPy: Geophysical Data Standard in Python

This package provides functions and workflows for standardizing geophysical datasets based on the Geophysical Survey (GS) data standard. The current implementation follows the GS Data Tree framework and supports both tabular (unstructured/scattered) and raster (structured/gridded) datasets.

Goals of the GS Data Standard & GSPy

1. Standardize geophysical data with a format based on the netCDF file format and Climate and Forecast (CF) metadata conventions.

2. Restructure various types of geophysical data (e.g., raw and processed data, inverted models, or derivative products) into a consistent format for sharing and archiving.

3. Document critical metadata pertinent to geophysical analysis and transferability.

4. Develop tools for generating and exploring standardized datasets, and facilitate handling of complex and diverse data and metadata information to accurately process, invert, and interpret geophysical data.

5. Develop visualization and exploratory tools to interrogate data.

Why netCDF?

• Metadata documentation - detailed metadata is directly attached to the digital data values as variable-specific attributes (e.g., names, units, null values, value ranges) and as dataset attributes.

• Hierarchical structure - multiple datasets can be organized into a single file within a tiered group structure. The GS standard takes advantage of this to define standardized group types and ordering to create an adaptable framework for organizing complex datasets with critical supporting information such as survey and acquisition details, system configurations, and modeling parameters.

• Portable and accessible format - netCDF is platform-independent and supports subsetting which keeps large datasets accessible and easy to use.

• Well-established metadata conventions - the CF convention provides a strong foundation for standardizing metadata and is widely recognized for netCDF files. For example, by following the CF guidelines for coordinate reference system (CRS) variables all GS files are accurately represented in GIS software (QGIS, ArcGIS, etc).

• Space-saving and scalable - netCDF is a binary format with extra packing and compression options to significantly reduce file sizes, and is immediately scalable for large datasets with efficient read/write and parallel capabilities.

GSPy Workflow

The GSPy package provides tools for reading datasets from a variety of original formats common for geophysical data (e.g., CSV, ASEG-GDF, GeoTIFF), combining with metadata information, and generating standardized GS netCDF files.

See our examples for detailed demonstrations of the GSPy workflow. In general, the steps for making a GS netCDF file are:

1. Initiate a Survey

   • pass a metadata file (YAML or JSON) with global information about the survey

2. Add a Container branch

3. Add data to the Container branch

   • pass a data file

   • pass a metadata file

4. (optional) Add Supplementary Stem

   • this can also be done simultaneous with Step 3 through the data’s metadata file

5. Repeat steps 2-4 for each dataset as needed

6. Export to File

---

• Getting Started
  • Installing GSPy
  • The GS Data Tree
    • Example GS Data Tree
  • NetCDF Basics
    • Group Attributes
    • Coordinates
    • Dimensions
    • Variables
    • Variables Attributes
  • Notes for ASEG-GDF2 Files
    • Mapping the DFN to the CF metadata convention
• Metadata Handling
  • Survey Metadata File
  • Data Leaf Metadata File
    • Dataset Attributes
    • Coordinates
    • Dimensions
    • Variables
    • Systems
    • Parameters
  • Systems
  • Parameters
  • Required Group Attributes
    • Survey
    • GS Group Attributes
      • Data Leaves & Supplementary Leaflets
  • Required Variable Attributes
• Examples
  • Creating GS Files
  • Interacting With GS Files
• GS Convention
• API
  • DataTree Accessors
    • Survey
      • Survey
        • Survey.from_dict()
        • Survey.metadata_template()
    • Container
      • Container
        • Container.Data()
        • Container.Parameters()
        • Container.Systems()
        • Container.add()
        • Container.add_container()
        • Container.add_timestamp()
        • Container.attrs
        • Container.content
        • Container.from_dict()
        • Container.get_all_attr()
        • Container.get_system_with_method()
        • Container.metadata_template()
        • Container.plot()
        • Container.plot_cross_section()
        • Container.read_metadata()
        • Container.required_metadata
        • Container.scatter()
        • Container.set_spatial_ref()
        • Container.subset()
        • Container.to_netcdf()
        • Container.to_tif()
        • Container.tree
        • Container.write_ncml()
  • Dataset Accessors
    • Dataset
      • Dataset
        • Dataset.Survey()
        • Dataset.add_bounds_to_coordinate()
        • Dataset.add_coordinate_from_dict()
        • Dataset.add_coordinate_from_dict_np()
        • Dataset.add_coordinate_from_values()
        • Dataset.add_dimensions_from_variables()
        • Dataset.add_timestamp()
        • Dataset.add_variable_from_dict()
        • Dataset.add_variable_from_dict_np()
        • Dataset.add_variable_from_values()
        • Dataset.assign_coords()
        • Dataset.attrs
        • Dataset.couplet_labels
        • Dataset.distance_along_line
        • Dataset.get_all_attr()
        • Dataset.interpolate()
        • Dataset.is_projected
        • Dataset.json_metadata
        • Dataset.metadata_template()
        • Dataset.plot()
        • Dataset.plot_cross_section()
        • Dataset.required_metadata
        • Dataset.scatter()
        • Dataset.set_spatial_ref()
        • Dataset.spatial_ref
        • Dataset.subset()
        • Dataset.to_netcdf()
        • Dataset.write_ncml()
        • Dataset.write_zarr()
        • Dataset.x_axis()
    • Raster
      • Raster
        • Raster.bounds
        • Raster.is_tif
        • Raster.open_rasterio()
        • Raster.read()
        • Raster.read_raster_using_metadata()
        • Raster.read_var_netcdf()
        • Raster.write_metadata_template()
    • Tabular
      • Tabular
        • Tabular.get_fortran_format()
        • Tabular.metadata_template()
        • Tabular.read()
        • Tabular.to_file()
    • System
      • System
        • System.check_against_data()
        • System.from_dict()
        • System.is_projected
        • System.open()
        • System.required_metadata
        • System.valid_instrument()
        • System.valid_method()
        • System.valid_model()
  • DataArray Accessors
    • gs_DataArray
      • DataArray
        • DataArray.add_bounds_to_coordinate_dimension()
        • DataArray.catch_nan()
        • DataArray.check_metadata()
        • DataArray.export_dataarray()
        • DataArray.from_values()
        • DataArray.label
        • DataArray.long_name
        • DataArray.metadata_template()
        • DataArray.standard_name
        • DataArray.units
        • DataArray.valid_range()
        • DataArray.write_ncml()
    • Coordinate
      • Coordinate
        • Coordinate.check_is_projected()
        • Coordinate.check_standard_coordinates()
        • Coordinate.from_dict()
        • Coordinate.from_values()
        • Coordinate.metadata_template()
    • Spatial ref
      • Spatial_ref
        • Spatial_ref.from_dict()
        • Spatial_ref.metadata_template()
• References
  • GS Data Standard & GSPy
  • netCDF
  • Climate & Forecasts (CF) metadata Conventions
  • Xarray