Pre release (#49)

* API improvements (#41)

0.8.0-alpha pre-release

 - new LatLon type definition for a (latitude, longitude) named tuple
 - nzshm_common.constants.DEFAULT_RESOLUTION (0.001 degree)
 - sorting for CodedLocation objects (N->S then W->E)
 - get_location_grid and get_location_grid_names functions for grids
 - get_location_list and get_location_list_names functions for location lists
 - CodedLocation (and new LatLon) can be imported directly from nzshm_common
 - several function signatures now use LatLon instead of Tuple[float, float]

 - a variety of documentation strings and typo fixups
 - included grids.region_grid in docs config
 - improving test coverage
 - does_not_raise test context manager moved into tests/helpers.py
 - housekeeping on some imports

* Add binning of CodedLocation objects into a CodedLocationBin at coarser resolution.

* Added 0.8.0-alpha.1 Changelog

* Refactored get_location_grid to use native RegionGrid resolution. (#48)

* update changelog; remove empty usage docs form mkdocs index.

* Bump version: 0.7.0 → 0.8.0

---------

Co-authored-by: David Thompson <DrCuriosity@users.noreply.github.com>
Co-authored-by: David Thompson <david.thompson@catalyst.net.nz>

.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 0.7.0
+current_version = 0.8.0
 commit = True
 tag = True
 

CHANGELOG.md

@@ -5,6 +5,35 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+
+## [0.8.0] - 2024-07-03
+
+official 0.8.0 release
+
+## [0.8.0-alpha.1] - 2024-05-08
+### Added
+ - CodedLocationBin class
+ - bin_locations for collecting coded locations at a coarser resolution
+ - Illustration of bin_locations applied to a grid dataset
+ - More documentation and examples
+ - Fixture for sampling on a reduced set of NZ_0_1_NB_1_0
+
+### Changed
+ - location/code_location.py is renamed to coded_location for consistency
+
+## [0.8.0-alpha] - 2024-03-29
+### Added
+ - new LatLon type definition for a (latitude, longitude) named tuple
+ - nzshm_common.constants.DEFAULT_RESOLUTION (0.001 degree)
+ - sorting for CodedLocation objects (N->S then W->E)
+ - get_location_grid and get_location_grid_names functions for grids
+ - get_location_list and get_location_list_names functions for location lists
+
+### Changed
+ - CodedLocation (and new LatLon) can be imported directly from nzshm_common
+ - several function signatures now use LatLon instead of Tuple[float, float]
+      - non-breaking change; they are functionally equivalent in runtime
+
 ## [0.7.0] - 2024-03-19
 ### Added
  - get_locations function

docs/api/constants.md

@@ -0,0 +1 @@
+::: nzshm_common.constants

docs/api/grids/region_grid.md

@@ -0,0 +1,3 @@
+::: nzshm_common.grids.region_grid
+    options:
+        filters: ["!^_"]

docs/api/location/coded_location.md

@@ -0,0 +1,6 @@
+::: nzshm_common.location.coded_location
+    options:
+        filters: ["!^_"]
+        docstring_options:
+            ignore_init_summary: false
+        merge_init_into_class: true

docs/api/location/types.md

@@ -0,0 +1,3 @@
+::: nzshm_common.location.types
+    options:
+        filters: ["!^_"]

mkdocs.yml

@@ -10,11 +10,15 @@ watch:
 nav:
   - Home: index.md
   - Installation: installation.md
-  - Usage: usage.md
+  # - Usage: usage.md
   - API Reference:
+    - constants: api/constants.md
+    - grids (package):
+      - region_grid (module): api/grids/region_grid.md
     - location (package):
+      - coded_location (module): api/location/coded_location.md
       - location (module): api/location/location.md
-      - CodedLocation (class): api/location/code_location.CodedLocation.md
+      - types (module): api/location/types.md
   - Contributing: contributing.md
   - Changelog: changelog.md
 theme:

nzshm_common/__init__.py

@@ -1,5 +1,9 @@
 __author__ = "GNS Science"
 __email__ = 'nshm@gns.cri.nz'
-__version__ = '0.7.0'
+__version__ = '0.8.0'
 
 from .location import location
+
+# Common classes at the top level for convenience
+from .location.coded_location import CodedLocation, CodedLocationBin
+from .location.types import LatLon

nzshm_common/constants.py

@@ -0,0 +1,10 @@
+"""
+Standard values that are useful in multiple places.
+"""
+
+DEFAULT_RESOLUTION = 0.001
+"""
+Default coordinate resolution in degrees.
+This is typically used for
+[`CodedLocation`](location/coded_location.md#nzshm_common.location.coded_location.CodedLocation) values.
+"""

nzshm_common/grids/__init__.py

@@ -1 +1 @@
-from .region_grid import RegionGrid, load_grid
+from .region_grid import RegionGrid, get_location_grid, get_location_grid_names, load_grid

nzshm_common/grids/io.py

@@ -2,15 +2,18 @@
 import csv
 import io
 import zipfile
+from typing import List
 
+from nzshm_common.location.types import LatLon
 
-def latlon_from_base64_zip(b64_data: str) -> list:
+
+def latlon_from_base64_zip(b64_data: str) -> List[LatLon]:
     result = []
     byte_data = base64.b64decode(b64_data)
     data = io.BytesIO(byte_data)
     with zipfile.ZipFile(data) as fz:
         plain_bytes = io.BytesIO(fz.read("data"))
         reader = csv.reader(io.StringIO(plain_bytes.getvalue().decode("utf-8", "ignore")))
         for row in reader:
-            result.append((float(row[1]), float(row[0])))
+            result.append(LatLon(float(row[1]), float(row[0])))
     return result

nzshm_common/grids/region_grid.py

@@ -1,17 +1,25 @@
+import warnings
 from collections import namedtuple
 from enum import Enum
-from typing import Tuple
+from functools import partial
+from typing import Iterable, List, Optional
 
 from nzshm_common.grids.nz_0_1_nb_1_v0 import NZ01nb1v0
 from nzshm_common.grids.nz_0_1_nb_1_v1 import NZ01nb1v1
 from nzshm_common.grids.nz_0_2_nb_1_1 import NZ_0_2_nb_1_1
 from nzshm_common.grids.wlg_0_01_nb_1_1 import WLG_0_01_nb_1_1
 from nzshm_common.grids.wlg_0_05_nb_1_1 import WLG_0_05_nb_1_1
+from nzshm_common.location.coded_location import CodedLocation
+from nzshm_common.location.types import LatLon
 
 RegionGridEntry = namedtuple("RegionGridEntry", "region_name resolution neighbours grid version")
 
 
 class RegionGrid(Enum):
+    """
+    An enumerated collection of region grids defined in this module.
+    """
+
     NZ_0_1_NB_1_0 = RegionGridEntry(region_name="NZ", resolution=0.1, neighbours=1, grid=NZ01nb1v0(), version=0)
     NZ_0_1_NB_1_1 = RegionGridEntry(region_name="NZ", resolution=0.1, neighbours=1, grid=NZ01nb1v1(), version=1)
     NZ_0_2_NB_1_1 = RegionGridEntry(region_name="NZ", resolution=0.2, neighbours=1, grid=NZ_0_2_nb_1_1(), version=1)
@@ -41,5 +49,81 @@ def load(self):
         return self.grid.load()
 
 
-def load_grid(gri_name: str) -> Tuple[float, float]:
-    return RegionGrid[gri_name].load()
+def load_grid(grid_name: str) -> List[LatLon]:
+    """
+    Load values from a region grid as `LatLon` pairs.
+
+    Examples:
+        >>> from nzshm_common import grids
+        >>> grids.load_grid("NZ_0_1_NB_1_0")
+        [
+            LatLon(latitude=-46.1, longitude=166.4),
+            LatLon(latitude=-46.0, longitude=166.4),
+            LatLon(latitude=-45.9, longitude=166.4),
+            ...
+        ]
+    """
+    return RegionGrid[grid_name].load()
+
+
+def get_location_grid(location_grid_name: str, resolution: Optional[float] = None) -> Iterable[CodedLocation]:
+    """
+    Get all coded locations within a grid.
+
+    Note:
+        When downsampling to a lower resolution, duplicate location values will be removed.
+
+    Parameters:
+        location_grid_name: A valid member key from RegionGrid (e.g. "NZ_0_1_NB_1_1")
+        resolution: The resolution of the CodedLocation values generated.
+            Defaults to the native RegionGrid resolution value.
+
+    Returns:
+        A list of coded locations with the specified resolution.
+
+    Examples:
+        >>> from nzshm_common import grids
+        >>> grids.get_location_grid("NZ_0_1_NB_1_0")
+        [
+            CodedLocation(lat=-46.1, lon=166.4, resolution=0.1),
+            CodedLocation(lat=-46.0, lon=166.4, resolution=0.1)
+            ...
+        ]
+    """
+    if not resolution:
+        resolution = RegionGrid[location_grid_name].resolution
+    elif resolution > RegionGrid[location_grid_name].resolution:
+        warn_msg = "The requested resolution is lower than the grid resolution and will result in fewer points."
+        warnings.warn(warn_msg, stacklevel=2)
+
+    grid_values = load_grid(location_grid_name)
+    coded_at_resolution = partial(CodedLocation.from_tuple, resolution=resolution)
+    # Remove duplicate coordinates from collection, preserving order.
+    location_list = []
+    for loc in map(coded_at_resolution, grid_values):
+        if loc not in location_list:
+            location_list.append(loc)
+
+    return location_list
+
+
+def get_location_grid_names() -> Iterable[str]:
+    """
+    Return a collection of of valid region grids.
+
+    Returns:
+        member names from the RegionGrid Enum class.
+
+    Examples:
+        >>> from nzshm_common import grids
+        >>> grids.get_location_grid_names()
+        dict_keys([
+            'NZ_0_1_NB_1_0',
+            'NZ_0_1_NB_1_1',
+            'NZ_0_2_NB_1_1',
+            'WLG_0_01_nb_1_1',
+            'WLG_0_05_nb_1_1'
+        ])
+    """
+
+    return RegionGrid.__members__.keys()

nzshm_common/location/__init__.py

@@ -1 +1 @@
-from .code_location import CodedLocation
+from .coded_location import CodedLocation, CodedLocationBin