xopr 0.1.2__py3-none-any.whl

xopr/__init__.py

@@ -0,0 +1,34 @@
+# MIT License
+#
+# Copyright (c) 2025 Thomas Teisberg, Shane Grigsby
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice (including the next
+# paragraph) shall be included in all copies or substantial portions of the
+# Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+"""
+Add a docstring here for the init module.
+
+This might include a very brief description of the package,
+its purpose, and any important notes.
+"""
+
+try:
+    from ._version import __version__
+except ImportError:
+    __version__ = "unknown"

xopr/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '0.1.2'
+__version_tuple__ = version_tuple = (0, 1, 2)
+
+__commit_id__ = commit_id = None

xopr/cf_units.py

@@ -0,0 +1,148 @@
+# TODO: This is entirely AI generated and unchecked.
+# I just wanted something to quickly demonstrate what units might looks like.
+# Should be carefully reviewed.
+
+import xarray as xr
+import numpy as np
+
+def apply_cf_compliant_attrs(ds):
+    """
+    Apply CF-compliant units and comments to radar echogram dataset variables.
+    
+    Parameters:
+    -----------
+    ds : xarray.Dataset
+        The input radar echogram dataset
+        
+    Returns:
+    --------
+    xarray.Dataset
+        Dataset with CF-compliant attributes applied
+    """
+    
+    # Create a copy to avoid modifying the original dataset
+    ds_cf = ds.copy()
+    
+    # Define CF-compliant attributes for coordinates
+    coordinate_attrs = {
+        'slow_time': {
+            #'units': 'seconds since 1970-01-01T00:00:00Z',
+            'standard_name': 'time',
+            'long_name': 'slow time',
+            'comment': 'Time coordinate for radar pulse transmission along flight track'
+        },
+        'twtt': {
+            'units': 's',
+            'standard_name': 'time',
+            'long_name': 'two-way travel time',
+            'comment': 'Two-way travel time from radar to target and back'
+        }
+    }
+    
+    # Define CF-compliant attributes for data variables
+    data_var_attrs = {
+        'Bottom': {
+            'units': 's',
+            'long_name': 'bottom surface two-way travel time',
+            'comment': 'Two-way travel time to detected bottom surface. NaN where bottom not detected.',
+            '_FillValue': np.nan
+        },
+        'Data': {
+            'units': '1',  # TODO: Appropriate units for radar data -- can we calibrate to watts?
+            'long_name': 'radar echo power',
+            'comment': 'Radar echo power in linear scale',
+            'coordinates': 'slow_time twtt'
+        },
+        'Elevation': {
+            'units': 'm',
+            'standard_name': 'height_above_reference_ellipsoid',
+            'long_name': 'platform elevation above WGS84 ellipsoid',
+            'comment': 'GPS-derived elevation of radar platform above WGS84 reference ellipsoid'
+        },
+        'Heading': {
+            'units': 'radians',
+            'standard_name': 'platform_orientation',
+            'long_name': 'platform heading angle',
+            'comment': 'Platform heading angle in radians from north, clockwise positive',
+            'valid_min': -np.pi,
+            'valid_max': np.pi,
+            'valid_range': [-np.pi, np.pi],
+        },
+        'Latitude': {
+            'units': 'degrees_north',
+            'standard_name': 'latitude',
+            'long_name': 'platform latitude',
+            'comment': 'GPS-derived latitude of radar platform in WGS84 coordinate system',
+            'valid_min': -90.0,
+            'valid_max': 90.0,
+            'valid_range': [-90.0, 90.0]
+        },
+        'Longitude': {
+            'units': 'degrees_east',
+            'standard_name': 'longitude',
+            'long_name': 'platform longitude',
+            'comment': 'GPS-derived longitude of radar platform in WGS84 coordinate system',
+            'valid_min': -180.0,
+            'valid_max': 180.0,
+            'valid_range': [-180.0, 180.0]
+        },
+        'Pitch': {
+            'units': 'radians',
+            'standard_name': 'platform_pitch_angle',
+            'long_name': 'platform pitch angle',
+            'comment': 'Platform pitch angle in radians, positive nose up',
+            'valid_min': -np.pi/2,
+            'valid_max': np.pi/2,
+            'valid_range': [-np.pi/2, np.pi/2]
+        },
+        'Roll': {
+            'units': 'radians',
+            'standard_name': 'platform_roll_angle',
+            'long_name': 'platform roll angle',
+            'comment': 'Platform roll angle in radians, positive right wing down',
+            'valid_min': -np.pi,
+            'valid_max': np.pi,
+            'valid_range': [-np.pi, np.pi]
+        },
+        'Surface': {
+            'units': 's',
+            'long_name': 'surface two-way travel time',
+            'comment': 'Two-way travel time to detected surface. Zero indicates surface at platform level.',
+            'valid_min': 0.0
+        }
+    }
+    
+    # Apply coordinate attributes
+    for coord_name, attrs in coordinate_attrs.items():
+        if coord_name in ds_cf.coords:
+            ds_cf[coord_name].attrs.update(attrs)
+    
+    # Apply data variable attributes
+    for var_name, attrs in data_var_attrs.items():
+        if var_name in ds_cf.data_vars:
+            ds_cf[var_name].attrs.update(attrs)
+    
+    # Add global attributes for CF compliance
+    global_attrs = {
+        'Conventions': 'CF-1.8',
+        'title': 'Radar Echogram Data',
+        'institution': 'Open Polar Radar (OPR)',
+        'source': 'Airborne/ground-based radar sounder',
+        'history': f'Converted to CF-compliant format on {np.datetime64("now").astype(str)}',
+        'references': 'https://gitlab.com/openpolarradar/opr',
+        'comment': 'Polar radar echogram data with CF-compliant metadata',
+        'geospatial_lat_min': float(ds_cf.Latitude.min()) if 'Latitude' in ds_cf else None,
+        'geospatial_lat_max': float(ds_cf.Latitude.max()) if 'Latitude' in ds_cf else None,
+        'geospatial_lon_min': float(ds_cf.Longitude.min()) if 'Longitude' in ds_cf else None,
+        'geospatial_lon_max': float(ds_cf.Longitude.max()) if 'Longitude' in ds_cf else None,
+        'time_coverage_start': str(ds_cf.slow_time.min().values) if 'slow_time' in ds_cf else None,
+        'time_coverage_end': str(ds_cf.slow_time.max().values) if 'slow_time' in ds_cf else None
+    }
+    
+    # Remove None values from global attributes
+    global_attrs = {k: v for k, v in global_attrs.items() if v is not None}
+    
+    # Update global attributes
+    ds_cf.attrs.update(global_attrs)
+    
+    return ds_cf

xopr/example.py

@@ -0,0 +1,36 @@
+"""
+A module that adds numbers together.
+
+You may want to delete this module or modify it for your package.
+It's generally good practice to have a docstring
+that explains the purpose of the module, at the top.
+"""
+
+def add_numbers(a: float, b: float) -> float:
+    """
+    Add two numbers together and return the result.
+
+    This is an example function with a numpy style docstring.
+    We recommend using this style for consistency and readability.
+
+    Parameters
+    ----------
+    a : float
+        The first number to add.
+    b : float
+        The second number to add.
+
+    Returns
+    -------
+    float
+        The sum of the two numbers.
+
+    Examples
+    --------
+    >>> add_numbers(3, 5)
+    8
+    >>> add_numbers(-2, 7)
+    5
+
+    """
+    return a + b

xopr/geometry.py

@@ -0,0 +1,104 @@
+import geopandas as gpd
+import json
+from cartopy import crs
+from pyproj import Transformer
+import shapely.ops
+
+
+def get_antarctic_regions(
+    name=None,
+    regions=None, 
+    subregions=None,
+    type=None,
+    merge_regions=True,
+    measures_boundaries_url = "https://storage.googleapis.com/opr_stac/reference_geometry/measures_boundaries_4326.geojson"
+):
+    """
+    Load and filter Antarctic regional boundaries from the MEASURES dataset.
+    
+    Parameters
+    ----------
+    name : str or list, optional
+        NAME field value(s) to filter by
+    regions : str or list, optional
+        REGIONS field value(s) to filter by  
+    subregions : str or list, optional
+        SUBREGION field value(s) to filter by
+    type : str or list, optional
+        TYPE field value(s) to filter by
+    merge_regions : bool, default True
+        If True, return a single merged geometry; if False, return list of geometries
+    measures_boundaries_url : str, default "https://storage.googleapis.com/opr_stac/reference_geometry/measures_boundaries_4326.geojson"
+        URL to the GeoJSON file containing Antarctic region boundaries
+        
+    Returns
+    -------
+    list or dict
+        If merge_regions=False: List of GeoJSON geometry dicts
+        If merge_regions=True: Single GeoJSON geometry dict of merged regions
+        
+    Examples
+    --------
+    # Get George VI ice shelf
+    >>> george_vi = get_antarctic_regions(name="George_VI", type="FL")
+    
+    # Get all ice shelves, merged into one geometry
+    >>> all_shelves = get_antarctic_regions(type="FL", merge_regions=True)
+    
+    # Get multiple regions by name
+    >>> regions = get_antarctic_regions(name=["George_VI", "LarsenC"])
+    """
+    
+    
+    # Load the boundaries GeoJSON from the reference URL
+    filtered = gpd.read_file(measures_boundaries_url)
+    
+    # Apply filters based on provided parameters
+    if name is not None:
+        if isinstance(name, str):
+            name = [name]
+        filtered = filtered[filtered['NAME'].isin(name)]
+    
+    if regions is not None:
+        if isinstance(regions, str):
+            regions = [regions] 
+        filtered = filtered[filtered['Regions'].isin(regions)]
+        
+    if subregions is not None:
+        if isinstance(subregions, str):
+            subregions = [subregions]
+        filtered = filtered[filtered['Subregions'].isin(subregions)]
+        
+    if type is not None:
+        if isinstance(type, str):
+            type = [type]
+        filtered = filtered[filtered['TYPE'].isin(type)]
+
+    # Filter out invalid geometries
+    filtered = filtered[filtered.is_valid]
+    
+    if len(filtered) == 0:
+        return [] if not merge_regions else None
+    
+    if merge_regions:
+        merged = filtered.iloc[0].geometry
+        for i in range(1, len(filtered)):
+            merged = merged.union(filtered.iloc[i].geometry)
+        return merged
+    else:
+        return filtered
+    
+def project_dataset(ds, target_crs):
+    projected_coords = target_crs.transform_points(
+        crs.PlateCarree(), ds['Longitude'].values, ds['Latitude'].values
+    ).T
+    ds = ds.assign_coords({
+        'x': (('slow_time'), projected_coords[0]),
+        'y': (('slow_time'), projected_coords[1])
+    })
+    return ds
+
+def project_geojson(geometry, source_crs="EPSG:4326", target_crs="EPSG:3031"):
+    transformer = Transformer.from_crs(source_crs, target_crs, always_xy=True)
+    projected_geometry = shapely.ops.transform(transformer.transform, geometry)
+    return projected_geometry