sonic-spatial 1.0.0rc1__tar.gz

sonic_spatial-1.0.0rc1/.github/workflows/release.yml

@@ -0,0 +1,80 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install build twine
+      - run: python -m build
+      - run: python -m build compat/quadsv --outdir compat-dist
+      - run: python -m twine check dist/* compat-dist/*
+      - name: Verify release version and wheel ownership
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          case "$RELEASE_TAG" in
+            v*) version="${RELEASE_TAG#v}" ;;
+            *) echo "Release tag must start with v"; exit 1 ;;
+          esac
+          sonic_wheel="dist/sonic_spatial-${version}-py3-none-any.whl"
+          quadsv_wheel="compat-dist/quadsv-${version}-py3-none-any.whl"
+          test -f "$sonic_wheel"
+          test -f "$quadsv_wheel"
+          unzip -Z1 "$sonic_wheel" | grep -qx 'sonic/__init__.py'
+          ! unzip -Z1 "$sonic_wheel" | grep -q '^quadsv/'
+          unzip -Z1 "$quadsv_wheel" | grep -qx 'quadsv/__init__.py'
+          unzip -p "$quadsv_wheel" 'quadsv-*.dist-info/METADATA' |
+            grep -Eq '^Requires-Dist: sonic-spatial(<2,>=1\.0\.0rc1|>=1\.0\.0rc1,<2)$'
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sonic-dist
+          path: dist/
+      - uses: actions/upload-artifact@v4
+        with:
+          name: quadsv-dist
+          path: compat-dist/
+
+  publish-sonic:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: sonic-dist
+          path: dist/
+      - name: Publish SONIC
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist
+
+  publish-quadsv:
+    needs: [build, publish-sonic]
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: quadsv-dist
+          path: compat-dist/
+      - name: Publish QuadSV compatibility package
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: compat-dist

sonic_spatial-1.0.0rc1/.gitignore

@@ -0,0 +1,80 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+venv/
+ENV/
+env/
+.venv
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# PyCharm
+.idea/
+
+# VSCode
+.vscode/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+.hypothesis/
+
+# Data + analysis outputs (project-root-anchored so nested packages aren't ignored)
+/data/
+/results/
+*.h5ad
+*.csv
+figures/
+*.png
+*.jpg
+*.pdf
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Misc
+*.log
+.cache/
+
+# copilot 
+.github/copilot-instructions.md
+
+# Sphinx documentation build
+docs/_build/
+docs/_static/
+docs/_templates/
+
+# setuptools-scm generated version file (see [tool.setuptools_scm] in pyproject.toml)
+src/sonic/_version.py
+
+# claude code
+CLAUDE.md
+.claude/

sonic_spatial-1.0.0rc1/.readthedocs.yaml

@@ -0,0 +1,20 @@
+# Read the Docs configuration file.
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details.
+
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: true
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

sonic_spatial-1.0.0rc1/CHANGELOG.md

@@ -0,0 +1,292 @@
+# Changelog
+
+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).
+
+## [Unreleased]
+
+## [1.0.0rc1] - 2026-08-29
+
+### Changed
+- **QuadSV is now SONIC** (Spatial Organization through Nonrandom-pattern
+  Inference and Comparison). The canonical distribution is `sonic-spatial`
+  and the import package is `sonic`; the `quadsv` distribution and import
+  namespace remain as a compatibility bridge for existing users.
+
+### Added
+- **GLM design API for cross-sample pattern comparison.** New public
+  `compare_glm(spectra, design, contrast, …)` generalises the
+  two-group test to arbitrary OLS designs (binary, continuous,
+  multi-factor) with an analytic Wald test. The two-group case is
+  recovered exactly. `Comparator.test_diff_freq(...)` gains a
+  `contrast=` argument (column name, dict, or contrast vector).
+- **Analytic null for `log_l2`** (`null="analytic"`) on
+  `compare_two_groups`, `compare_two_groups_masked`, and
+  `compare_glm`. Per-gene statistic is integrated via Liu's
+  approximation against a pooled-across-genes **full** within-group
+  Σ (a single 30×30 eigendecomposition before each Liu integration);
+  bypasses the small-n permutation BH-floor while keeping mean
+  within-group null FPR at ~0.012 across the three benchmark panels.
+  Emits a `UserWarning` at residual df < 3. The masked variant uses
+  a mask-aware pooled estimator with per-gene noncentrality scaling
+  so genes with different observed cohorts get correctly-scaled
+  eigenvalues.
+- **Analytic Welch t tests for `compare_two_groups_scalar`**.
+  Computes per-gene two-sided p-values from the
+  Welch-Satterthwaite t-distribution; the scalar DE companion uses
+  this fixed analytic null rather than exposing a `null=` selector.
+- **`normalize_shape: bool = False` keyword** on every spectrum-input
+  comparison test (`compare_two_groups`, `compare_two_groups_masked`,
+  `compare_glm`). When True, divides each per-(sample, gene)
+  spectrum by its sum along the frequency axis before the statistic
+  is computed, so the test fires only on shape-only redistribution
+  of power across radial frequencies. Statistic-agnostic; default
+  False preserves prior behaviour.
+- **Comparator null-covariance and effective-rank diagnostics**:
+  `Comparator.effective_rank(weights=None)` for per-sample heterogeneity 
+  in the gene spectrum cross-frequency covariance; 
+  `Comparator.estimate_null_covariance(design, contrast=...)`for the
+  pooled log-spectrum covariance, weighted covariance, scaled Liu
+  eigenvalues, effective rank, residual df, and masked-path eligibility
+  metadata used by `test_diff_freq(..., statistic="log_l2", null="analytic")`.
+- **Top-level convenience exports**:
+  `sonic.Detector(data, …)` and `sonic.Comparator(data_list, …)`
+  factories that dispatch on `AnnData` vs `SpatialData`;
+  `sonic.compute_null_params`, `sonic.auto_chunk_size`,
+  `sonic.liu_sf` promoted to top level (canonical
+  `sonic.statistics` paths still work).
+- **Public-API freeze test** (`tests/test_public_api.py`) snapshots
+  `__all__`, docstring presence, canonical-path identity, and
+  asserts removed legacy paths raise `ModuleNotFoundError`.
+- **Convenience input modes for `Comparator.normalize_covariates`.**
+  In addition to the existing per-sample
+  `Sequence[np.ndarray]` of pre-rasterized
+  `(n_covariates, ny, nx)` images, the method now accepts a shared
+  `Sequence[str]` of column names; the subclass interprets it
+  natively:
+
+    * `ComparatorIrregular` looks each key up in `adata.obs.columns`
+      first, then `adata.var_names` (preferring obs on collision);
+      the resolved per-spot vector is NUFFTed directly onto the
+      sample's k-grid — so the same call accepts deconvolved
+      cell-type proportion columns *and* per-gene expression columns
+      (e.g., a housekeeping or marker gene) interchangeably.
+    * `ComparatorGrid` forwards the keys as `value_key=` to
+      `spatialdata.rasterize_bins`, so any combination of `.obs`
+      columns and `var_names` in the comparator's table works.
+
+  Mode is detected from the first element's type. Both paths reduce
+  to the same `(n_covariates, K)` per-sample features fed into the
+  log-space residualization, so the math is identical — only the
+  input boilerplate is different.
+
+### Changed
+- **Breaking: package layout migrated to `src/sonic/`** with the
+  four conceptual layers as physical subpackages —
+  `sonic.kernels.{fft,nufft}`,
+  `sonic.detectors.{base,irregular,grid}`,
+  `sonic.comparators.{__init__,multisample}`. `import sonic` and
+  `from sonic import …` keep working; editable installs must be
+  reissued (`pip install -e ".[dev]"`). Lint / format commands now
+  target `src/ tests/`.
+- **Breaking: unified `normalize_*` surface API in
+  `sonic.comparators.multisample`** (no aliases):
+    * `normalize_by_background` → `normalize_background`
+    * `residualize_against_covariates` → `normalize_covariates`
+    * `shape_normalize` → `normalize_shape`
+  Consistent first-arg `spectra`, keyword-only after, `eps=1e-12`
+  default on every helper, and NumPy-style docstrings with LaTeX
+  math. `normalize_covariates`'s first positional arg is renamed
+  `gene_spectra` → `spectra`, and its implementation now operates in
+  **log-space**: it residualises `log(spectra + ε)` against
+  `[1, log(C^T + ε)]` and exponentiates, so the output stays strictly
+  positive and composes cleanly with downstream `log_l2` tests.
+  Log-space `normalize_covariates` also **commutes exactly** with
+  `normalize_background` (left- vs right-multiplication of the
+  log-spectrum matrix by orthogonal-projection matrices on disjoint
+  axes), so the two can be applied in either order. The remaining
+  chainable comparator instance method follows the rename:
+    * `.residualize()` → `.normalize_covariates()`
+- **Breaking: `Comparator.fit()` renamed to `Comparator.compute_spectra()`**.
+  The method computes per-sample radial-binned power spectra rather than
+  fitting model parameters; the new name describes the operation
+  directly and matches the codebase's verb-first method convention. All
+  three keyword arguments (`n_jobs`, `landmark_genes`, `progress`) and
+  the chainable `return self` behaviour are unchanged.
+- **Breaking: `design` moved from Comparator constructor to test
+  time.** The cross-sample contrast is no longer a construction
+  argument — it is supplied directly to `.test_diff_freq(design, ...)`
+  / `.test_diff_expr(design, ...)` (positional first arg). A single fitted comparator can now
+  serve any number of unrelated contrasts on the same `spectra_`
+  without recomputing per-sample spectra. `min_samples_per_group`
+  follows `design` to `test_diff_freq` (kwarg) since it's a property
+  of the design's group sizes, not of the spectra. `design` accepts
+  the same three forms as before:
+    * 1-D array / Series of binary labels → two-sample dispatch
+      (`compare_two_groups` / `compare_two_groups_masked`);
+    * 2-D `np.ndarray` of shape `(n_samples, p)` → GLM design matrix,
+      used verbatim by `compare_glm`;
+    * `pandas.DataFrame` → GLM design, patsy-encoded by
+      `compare_glm`.
+- **Breaking: default `null` switched from `"permutation"` to
+  `"analytic"` across the spectral comparison surface** —
+  `Comparator.test_diff_freq`,
+  `sonic.comparators.multisample.compare_two_groups`, and
+  `sonic.comparators.multisample.compare_two_groups_masked`. The
+  analytic Wald test (Liu mixture-χ² null) bypasses the small-n permutation
+  BH-floor and is the only path that works on every dispatch target
+  (binary permutation/analytic + GLM analytic), so it makes a single sensible
+  package-wide default. Callers who want the permutation null must
+  now pass `null="permutation"` explicitly. As a related
+  ergonomic fix, `compare_two_groups{,_masked}(statistic="welch_t_cauchy",
+  null="analytic")` no longer raises — `welch_t_cauchy` carries its own
+  analytic null (documented as ignoring the `null` kwarg) so the
+  package default `null="analytic"` is treated as a no-op for that
+  statistic.
+- **Breaking: statistical-test naming cleanup** in
+  `sonic.comparators.multisample` and the corresponding
+  `Comparator.test_diff_*` methods:
+    * **`compare_designs` → `compare_glm`.** The plural form was
+      awkward (one design per call); `compare_glm` names the test
+      family at the call site and parallels the binary
+      `compare_two_groups` cleanly.
+    * **Statistic `"cauchy_welch"` → `"welch_t_cauchy"`.** The new
+      token reads in pipeline order (per-bin Welch t first, gene-level
+      Cauchy combination second) and disambiguates from naming the
+      gene-level aggregator alone.
+    * **Scalar DE `null=` selector retired** on
+      `compare_two_groups_scalar` / `Comparator.test_diff_expr`.
+      Scalar DE now always uses the analytic Welch-Satterthwaite
+      t-distribution null.
+    * **`null="liu"` alias retired.** The `liu` token referred to
+      the numerical algorithm used to integrate the analytic χ² mixture
+      tail (see `sonic.statistics.liu_sf`), not a separate
+      statistical concept. Single canonical token: `analytic`.
+- **Breaking: Comparator attribute surface narrowed** (sklearn-style
+  moderate-privacy convention). The public surface is now `samples`,
+  `gene_names`, `feature_mode`, `freq_edges`, plus the
+  trailing-underscore fitted attributes (`spectra_`, `dc_`,
+  `presence_`, `rotation_angles_`). `design`/`groups_` are no longer
+  carried as instance state — the comparator is design-agnostic.
+  Internal config knobs that were inadvertently public are now
+  single-underscore-prefixed: `_n_radial_bins`, `_fft_solver`,
+  `_workers`, `_presence_threshold`, `_spacings`, `_grid_shapes`,
+  `_spectrum_fft_solver`, `_fft_chunk_size`, `_spacing_override`,
+  `_bins`, `_table_name`, `_col_key`, `_row_key`, `_value_key`.
+- **Breaking: Comparator test methods renamed and aligned with the
+  standalone `compare_*` API** in `sonic.comparators.multisample`:
+    * `.test_pattern()`    → `.test_diff_freq()` — gains a new
+      `normalize_shape: bool = False` keyword, forwarded to its
+      dispatch target (`compare_two_groups`,
+      `compare_two_groups_masked`, or `compare_glm`) so users get
+      the shape-only DF path without mutating `cmp.spectra_`.
+    * `.test_expression()` → `.test_diff_expr()` — uses analytic
+      t-distribution tests for scalar DE and supports both binary
+      two-group and GLM contrast designs.
+
+### Removed
+- **Breaking: `groups=` / `design=` constructor kwargs on
+  `ComparatorIrregular` and `ComparatorGrid` are gone.** Supply the
+  1-D labels or design matrix to the test method instead
+  (`cmp.test_diff_freq(design, ...)`, `cmp.test_diff_expr(design,
+  ...)`). The comparator no longer carries design state; one fitted
+  comparator can serve any number of contrasts on the same spectra.
+- **Breaking: `Comparator.shape_normalize()` chainable method
+  retired.** Use the equivalent
+  `cmp.test_diff_freq(..., normalize_shape=True)` keyword path for the
+  one-shot non-destructive test, or call
+  `sonic.comparators.multisample.normalize_shape(cmp.spectra_)`
+  directly to obtain the standalone transform. The previous in-place
+  method silently mutated `cmp.spectra_` and surprised subsequent
+  `.test_diff_freq()`/`.test_diff_expr()` calls on the same comparator.
+- **Breaking: the `test = test_pattern` alias retired.** Use the
+  explicit `cmp.test_diff_freq(...)` (or `cmp.test_diff_expr(...)` for
+  the DE companion); the unqualified `cmp.test()` was ambiguous once
+  the API exposed two complementary tests.
+- **Breaking: `center` argument retired** across the comparator API.
+  `ComparatorIrregular`, `ComparatorGrid`, and
+  `compute_sample_spectrum` no longer accept `center`. Per-gene
+  mean centring (the previous default) is now the only spectrum
+  normalisation path. The `_ZSCORE_CLIP` constant, the
+  `zscore_clip` parameter, and the per-bin clamp in the NUFFT loop
+  are deleted (~50 LOC).
+- **Breaking: `benchmark_statistics` function and the matching
+  `Comparator.benchmark()` method retired.** Invoke
+  `compare_two_groups` directly with each `statistic=` value to A/B
+  compare on the same fitted spectra (~95 LOC).
+- **Breaking: `statistic="hotelling_lw"` and `statistic="mmd_rbf"`
+  paths retired** from every comparison function. Both were
+  impractically slow and consistently dominated on sensitivity by
+  `log_l2 + null='analytic'` or `welch_t_cauchy`. `_AVAILABLE_STATISTICS`
+  now reads `("log_l2", "welch_t_cauchy")`.
+- **Breaking: six legacy-path shim modules removed** —
+  `sonic.fft`, `sonic.nufft`, `sonic.detector`,
+  `sonic.detector_grid`, `sonic._detector_base`,
+  `sonic.multisample`. Use the canonical subpackage paths.
+- **Breaking: backend ABCs `Kernel` and `MatrixKernelBase` no
+  longer re-exported from top-level `sonic`**. They live at
+  `sonic.kernels` and are intended for backend authors.
+
+### Fixed
+- CI workflow install step referenced non-existent extras
+  (`[dev,test,spatial]` and `[docs,spatial]`); narrowed to the
+  actual `[dev]` / `[docs]` extras in `pyproject.toml`.
+
+## Release Process
+
+The immediate release is the real prerelease `1.0.0rc1`. The thorough
+documentation rewrite remains deferred to the final `1.0.0`; until the RC is
+tagged, keep its changes under `Unreleased`.
+
+- [x] Review the current installation, migration, and release notes for
+  accuracy; the full documentation rewrite is not an RC blocker.
+- [x] Run the full test suite: `pytest tests/ --cov=sonic`.
+- [x] Run lint checks: `ruff check src tests compat/quadsv/src`.
+- [x] Build the documentation without warnings:
+  `sphinx-build -W -b html docs/ docs/_build/`.
+- [x] Add the pending `sonic-spatial` publisher with owner `JiayuSuPKU`,
+  repository `sonic`, workflow `release.yml`, and environment `pypi`.
+- [x] Add the additional `quadsv` publisher with the same identity. Keep the
+  existing QuadSV credential until this release succeeds.
+- [x] Update the compatibility requirement to
+  `sonic-spatial>=1.0.0rc1,<2` and make
+  the compatibility wheel, rather than the SONIC wheel, own the deprecated
+  `quadsv` import namespace.
+- [x] Confirm the new Read the Docs project builds successfully and legacy
+  documentation links remain available or redirect.
+- [x] Add a dated `1.0.0rc1` section below `Unreleased`, leaving a new empty
+  `Unreleased` section for future changes.
+- [ ] Commit the release preparation and create an annotated tag:
+  `git tag -a v1.0.0rc1 -m "SONIC 1.0.0rc1"`.
+- [x] Build both distributions: `python -m build` and
+  `python -m build compat/quadsv --outdir compat-dist`.
+- [x] Verify their metadata:
+  `python -m twine check dist/* compat-dist/*`.
+- [ ] Push `v1.0.0rc1`, then publish its GitHub prerelease to trigger trusted
+  publishing of SONIC followed by the QuadSV compatibility package.
+- [ ] Verify clean installations of `sonic-spatial==1.0.0rc1` and
+  `quadsv==1.0.0rc1` from PyPI, then remove obsolete QuadSV credentials.
+
+## [0.1.0] - 2026-02-02
+
+### Added
+- Initial public release
+- Q-test framework for univariate spatial pattern detection
+- R-test framework for bivariate spatial co-expression
+- Core kernel methods: Gaussian, Matérn, CAR, Graph Laplacian, Moran's I
+- Implicit mode for scalable large-N computation (N > 5000)
+- FFT acceleration for regular grid data (Visium HD)
+- `DetectorIrregular` for AnnData integration (genome-wide SVG detection)
+- `DetectorGrid` for large-scale Visium HD analysis
+- Null approximation methods: CLT, Welch/Satterthwaite, Liu
+- Comprehensive test suite (unit + integration tests)
+- Tutorial test cases demonstrating all major workflows
+- Complete documentation with quickstart and theory sections
+- Support for Python 3.10, 3.11, 3.12
+
+## [0.1.1]
+
+### Fixed
+- Fix type hinting issues in `quadsv.kernels` module

sonic_spatial-1.0.0rc1/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Jiayu Su
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

sonic_spatial-1.0.0rc1/MANIFEST.in

@@ -0,0 +1,9 @@
+# Manifest for package distribution
+include README.md
+include LICENSE
+include pyproject.toml
+recursive-include src/sonic *.py
+recursive-exclude tests *
+recursive-exclude data *
+recursive-exclude figures *
+exclude *.ipynb