chore: finalize v0.7 public API and release checks

Author: mwyau

.github/dependabot.yml

@@ -12,6 +12,13 @@ updates:
         patterns: ['*']
         update-types: [minor, patch]
 
+  - package-ecosystem: pre-commit
+    directory: /
+    schedule:
+      interval: daily
+      time: '04:10'
+      timezone: America/New_York
+
   - package-ecosystem: github-actions
     directory: /
     schedule:

.github/workflows/ci.yml

@@ -424,7 +424,7 @@ jobs:
           python-version: ${{ env.PYTHON_VERSION }}
 
       - name: Build documentation
-        run: uv run --no-dev --group docs sphinx-build -b html docs docs/_build/html
+        run: uv run --no-dev --group docs sphinx-build -W --keep-going -b html docs docs/_build/html
 
   docker-build:
     name: Build and test Docker images

.pre-commit-config.yaml

@@ -26,7 +26,7 @@ repos:
     types_or: [ python ]
 
 - repo: https://github.com/astral-sh/ty-pre-commit
-  rev: v0.0.66
+  rev: v0.0.74
   hooks:
   - id: ty
     args: [ --all-extras, --isolated ]

.readthedocs.yaml

@@ -9,9 +9,6 @@ build:
     nodejs: "20"
   jobs:
     post_install:
-      - >-
-        uv pip install --python "$READTHEDOCS_VIRTUALENV_PATH/bin/python"
-        "sphinxcontrib-mermaid==2.0.2"
       - npm install -g @mermaid-js/mermaid-cli
 
 python:

CONTRIBUTING.md

@@ -20,22 +20,36 @@ We welcome ideas for new features or improvements. Please [open an issue](https:
 ### Submitting Pull Requests
 
 1. **Fork the repository** and create your branch from `main`.
+
 1. **Install development dependencies**:
+
    ```bash
    uv sync
    ```
+
 1. **Make your changes**:
+
    - Ensure your code follows the project's style (use `ruff` for formatting and linting).
    - Add or update tests for your changes.
    - Ensure all tests pass.
-1. **Run Quality Control Checks**:
+
+1. **Run the local quality checks**:
+
    ```bash
-   uv run ruff check . --fix
-   uv run ruff format .
+   uv run prek run --all-files
    uv run mypy
-   uv run pytest tests/unit tests/integration tests/parity
+   uv run pytest
+   uv run pytest tests/integration -m "not slow and not data"
+   uv run pytest tests/parity -m "not slow and not data"
+   uv run python scripts/generate_trackjson_schema.py --check
    ```
+
+   `uv run pytest` is the fast unit suite because the default test paths are
+   `tests/unit`. See [the testing guide](docs/development/testing.md) for
+   external-data and expensive validation.
+
 1. **Submit the Pull Request**:
+
    - Provide a clear description of the changes.
    - Reference any related issues.
 

README.md

@@ -83,4 +83,4 @@ Additional method-specific references are given in the relevant documentation.
 
 ## License
 
-PyStormTracker is distributed under the [BSD 3-Clause License](LICENSE).
+PyStormTracker is distributed under the [BSD 3-Clause License](https://github.com/mwyau/PyStormTracker/blob/main/LICENSE).

docs/api.md

@@ -1,6 +1,10 @@
 # Python API Reference
 
-PyStormTracker provides an object-oriented Python API. Tracker instances encapsulate algorithm, preprocessing, and execution configuration. The `.track()` method executes tracking on an input file or xarray dataset and returns an immutable `Tracks` container, which provides `.write()` for output serialization.
+PyStormTracker provides an object-oriented Python API. Tracker instances
+encapsulate algorithm, preprocessing, and execution configuration. The
+`.track()` method executes tracking on an input file or xarray dataset and
+returns an immutable `Tracks` container, which provides `.write()` for output
+serialization.
 
 ## Overview
 
@@ -32,41 +36,74 @@ tracks = tracker.track(
 tracks.write("tracks.trackjson")
 ```
 
-### API Division
+## API policy
 
-- **Constructor**: Specifies algorithm parameters, spatial/spectral preprocessing filters, projections, and backend/concurrency settings.
-- **`track()`**: Specifies input data (`data`, `variable`), time window (`start_time`, `end_time`), extremum mode (`detection_mode`), thresholds (`feature_threshold` for Simple, `object_threshold` for Hodges and HEALPix), and reader engine (`engine`).
-- **`Tracks.write()`**: Handles output serialization to supported formats (`json`, `track`, `imilast`).
+PyStormTracker is a pre-1.0 project with a deliberately small compatibility
+surface. Python importability alone does not make a name supported. The
+`__all__` declarations, package re-exports, and the explicitly documented
+members below define the intended API.
 
-For `HodgesTracker`, `frame_workers` controls concurrent frame tasks,
-`sht_threads` controls DUCC0 threads per active spherical-harmonic transform,
-and `mge_workers` controls concurrent MGE segment tasks. `segment_frames`
-remains the scientific temporal segment length and is independent of these
-controls.
+### Primary API
 
-## Core Exports
+The preferred interface is the package root:
 
-The package root exports only the public tracker classes, domain entities, and format functions:
+```python
+import pystormtracker as pst
+```
+
+The root exports exactly these nine names:
 
-- `pst.Tracker` (Protocol)
-- `pst.SimpleTracker`
-- `pst.HodgesTracker`
-- `pst.HealpixTracker`
 - `pst.Center`
+- `pst.HealpixTracker`
+- `pst.HodgesTracker`
+- `pst.SimpleTracker`
 - `pst.Track`
+- `pst.Tracker`
 - `pst.Tracks`
 - `pst.load_tracks`
 - `pst.save_tracks`
 
-Domain value types remain available under `pystormtracker.models`:
+`pystormtracker.__version__` remains normally accessible, but is not part of
+the root `__all__` compatibility list.
+
+### Advanced supported APIs
 
-- `pystormtracker.models.Center`
-- `pystormtracker.models.CenterFrame`
-- `pystormtracker.models.SpatialBounds`
-- `pystormtracker.models.ProcessingStep`
-- `pystormtracker.models.TracksMetadata`
+The following package and direct-module APIs are supported when explicitly
+documented here or in the linked methodology pages:
 
-## Trackers
+- `pystormtracker.models`: domain types `Center`, `DetectionMode`,
+  `ProcessingStep`, `Projection`, `ResolvedDetectionMode`, `SpatialBounds`,
+  `Track`, `Tracker`, `Tracks`, and `TracksMetadata`.
+- `pystormtracker.io`: generic `DataLoader`, `SUPPORTED_FORMATS`,
+  `SupportedFormat`, `infer_format`, `load_tracks`, and `save_tracks`.
+- `pystormtracker.preprocessing`: `BoundaryTaper`, `DCTFilter`, `SHTFilter`,
+  `SpectralRegridder`, and `compute_vorticity_divergence`.
+- `pystormtracker.metrics`: the high-level metric functions and the explicit
+  comparison API documented below.
+- `pystormtracker.sample.sample_tracks`.
+- `pystormtracker.hodges.rsplice.filter_rsplice`.
+
+TRACK-specific `read_track`, `write_track`, and `TrackNumericTime` remain
+available from `pystormtracker.io.track` for deliberate advanced use. The
+provisional TrackJSON wire structs and encoder remain in
+`pystormtracker.io.trackjson`, but are not re-exported by generic
+`pystormtracker.io`.
+
+### Implementation modules
+
+Detector, linker, MGE, segment, execution-helper, refinement, CLI-routing,
+schema-generation, and TrackJSON wire-structure internals are not a general
+compatibility surface. Feature-point refinement is selected through tracker
+configuration, for example `feature_refinement="grid"`,
+`"quadratic"`, `"spherical_quadratic"`, `"bspline"`, or
+`"spherical_bspline"`; the low-level refinement structures remain in their
+implementation modules.
+
+Modules not listed here may be importable but are implementation details and
+are not part of the supported compatibility surface. This project makes no
+semantic-version stability claim for unlisted names while it remains pre-1.0.
+
+## Tracker classes
 
 ```{eval-rst}
 .. automodule:: pystormtracker.simple.tracker
@@ -82,117 +119,154 @@ Domain value types remain available under `pystormtracker.models`:
    :show-inheritance:
 ```
 
-## Core Models
+## Domain models
 
-### Tracks
+### Tracks and metadata
 
 ```{eval-rst}
 .. automodule:: pystormtracker.models.tracks
-   :members: Track, Tracks
+   :members: DetectionMode, ProcessingStep, ResolvedDetectionMode, Track, Tracks, TracksMetadata
    :show-inheritance:
 ```
 
-### Storm Centers
+### Storm centers
 
 ```{eval-rst}
 .. automodule:: pystormtracker.models.center
    :members: Center
    :show-inheritance:
 ```
 
-## Data Loader
+### Geographic domain types
+
+```{eval-rst}
+.. automodule:: pystormtracker.models.geo
+   :members: Projection, SpatialBounds
+   :show-inheritance:
+```
+
+### Tracker protocol
+
+```{eval-rst}
+.. automodule:: pystormtracker.models.tracker
+   :members: Tracker
+```
+
+`CenterFrame` is an internal frame-processing transport type. It is not a
+public model or part of the Tracker return contract.
+
+## Generic I/O
 
 ```{eval-rst}
 .. automodule:: pystormtracker.io.data_loader
    :members: DataLoader
+
+.. automodule:: pystormtracker.io.format
+   :members: SUPPORTED_FORMATS, SupportedFormat, infer_format, load_tracks, save_tracks
 ```
 
-## Preprocessing
+Use `load_tracks` and `save_tracks` for ordinary format handling. TrackJSON/1.0
+is provisional; its typed wire structures and direct encoder are documented in
+the [TrackJSON reference](trackjson.md), not promoted to the generic I/O
+namespace.
+
+## Scientific preprocessing
 
-Trackers accept preprocessing options in their constructors: `lmin` and `lmax` request an optional spectral filter when supplied together, while `taper_points` controls spatial tapering independently. `HodgesTracker` accepts `spectral_taper` with source-compatible default `1.0`; `HealpixTracker` owns a separate default of `0.1`. Hodges' default `feature_refinement="bspline"` uses TRACK/SMOOPY-compatible rectangular B-spline refinement with coordinate-space GDFP optimization. The advanced experimental `"spherical_bspline"` option uses a global spherical B-spline with a candidate-local feasible region on eligible periodic latitude-longitude frames. `"quadratic"` and `"spherical_quadratic"` provide local polynomial subgrid refinement, and `"grid"` disables subgrid refinement. `missing_frame_parameters` and `time_step` model known input-time gaps.
+Tracker constructors accept preprocessing options: `lmin` and `lmax` request an
+optional spectral filter when supplied together, while `taper_points` controls
+spatial tapering independently. `HodgesTracker` accepts `spectral_taper` with
+source-compatible default `1.0`; `HealpixTracker` owns a separate default of
+`0.1`. The Hodges default `feature_refinement="bspline"` uses the
+TRACK/SMOOPY-compatible rectangular B-spline path with coordinate-space GDFP
+optimization. The advanced experimental `"spherical_bspline"` option uses a
+global spherical B-spline with a candidate-local feasible region on eligible
+periodic latitude-longitude frames. `"quadratic"` and
+`"spherical_quadratic"` provide local polynomial alternatives, and `"grid"`
+disables subgrid refinement. `missing_frame_parameters` and `time_step` model
+known input-time gaps for Hodges tracking.
 
-### Kinematics (vorticity and divergence)
+### Vorticity and divergence
 
 ```{eval-rst}
 .. automodule:: pystormtracker.preprocessing.kinematics
-   :members:
+   :members: compute_vorticity_divergence
 ```
 
-### Spectral Filtering
+### Spectral filtering
 
 ```{eval-rst}
 .. automodule:: pystormtracker.preprocessing.spectral
-   :members:
+   :members: DCTFilter, SHTFilter
 ```
 
 ### Regridding
 
 ```{eval-rst}
 .. automodule:: pystormtracker.preprocessing.regrid
-   :members:
+   :members: SpectralRegridder
 ```
 
-### Feature Refinement
+### Spatial tapering
 
 ```{eval-rst}
-.. automodule:: pystormtracker.refinement
-   :members:
+.. automodule:: pystormtracker.preprocessing.taper
+   :members: BoundaryTaper
 ```
 
-### Spatial Tapering
+The HEALPix example uses the supported package import:
 
-```{eval-rst}
-.. automodule:: pystormtracker.preprocessing.taper
-   :members:
+```python
+from pystormtracker.preprocessing import SpectralRegridder
 ```
 
-## Post-processing and Analysis
+## Metrics and post-processing
 
-### Secondary-variable Sampling
+### Secondary-variable sampling
 
 ```{eval-rst}
 .. automodule:: pystormtracker.sample
    :members: sample_tracks
 ```
 
-### Track Matching
-
-```{eval-rst}
-.. automodule:: pystormtracker.metrics.compare
-   :members: compare_tracks, TrackComparisonConfig, TrackComparison, TrackMatch
-```
+### Track comparison
 
-### Spherical Weighting Kernels
+The comparison result uses `TrackProperties` for lifecycle and intensity
+summaries and `IntensityDifference` for pointwise candidate-minus-reference
+statistics. These result structures are part of the documented comparison
+module, but are not re-exported through `pystormtracker.metrics`.
 
 ```{eval-rst}
-.. automodule:: pystormtracker.metrics.weighting
-   :members:
+.. automodule:: pystormtracker.metrics.compare
+   :members: compare_tracks, TrackComparisonConfig, TrackComparison, TrackMatch, TrackProperties, IntensityDifference
 ```
 
-### Eulerian Track Metrics
+### Eulerian metrics
 
 ```{eval-rst}
 .. automodule:: pystormtracker.metrics.eulerian
-   :members:
+   :members: compute_eke, compute_high_wind_index, compute_variance_metric
 ```
 
-### Lagrangian Track Metrics
+### Lagrangian metrics
 
 ```{eval-rst}
 .. automodule:: pystormtracker.metrics.lagrangian
    :members: compute_track_metrics
 ```
 
-### Hodges Splice Filtering
+### CORMAX and CCA cross-validation
 
 ```{eval-rst}
-.. automodule:: pystormtracker.hodges.rsplice
-   :members: filter_rsplice
+.. automodule:: pystormtracker.metrics.cross_validation
+   :members: compute_cormax, find_best_cca_truncation, train_cca_model
 ```
 
-### CORMAX and CCA/PCA Cross-validation
+Spherical weighting helpers are implementation details of the scientific metric
+workflows and are not documented as standalone convenience APIs.
+
+### Hodges splice filtering
 
 ```{eval-rst}
-.. automodule:: pystormtracker.metrics.cross_validation
-   :members:
+.. automodule:: pystormtracker.hodges.rsplice
+   :members: filter_rsplice
 ```