Troutpy v0.2.0

Added

• Test suite (tests/) covering the public pp, tl, and pl APIs against a
  synthetic SpatialData fixture (tests/conftest.py), including
  pytest.mark.xfail/skip markers documenting known spatialdata-0.4.0
  incompatibilities and pl/plotting.py legacy-pipeline drift.
• Spillover/decontamination tools for transcripts that land inside a
  neighbouring cell's segmentation mask: tl.flag_intracellular_spillover,
  tl.decontaminate_cell_expression, tl.credit_spillover_to_source, and a new
  tl.decontamination module with tl.subtract_local_urna_background,
  tl.generalized_source_score, tl.apply_soft_decontamination and
  tl.iterative_soft_decontamination.
• tl.assess_diffusion: new max_kde_points argument (default 5000). The
  KDE likelihood behind lr_stat is computed on a seeded subsample for genes
  with more transcripts, rescaled to the full count; previously it scaled
  quadratically and took hours for abundant genes on full Xenium sections.
• tl.compute_target_score: vectorized the per-transcript scoring loop (identical
  results; minutes instead of hours on a full Xenium section).
• tl.quantify_overexpression: new extracellular_key argument; only
  extracellular (uRNA) transcripts are counted when that column is present.
• docs/api/index.md landing page; API pages reorganized by topic, following
  scverse conventions.
• Basic_tutorial.ipynb: new section on spillover correction, data download and
  install instructions.

Changed

• tl.adaptative_source_score_optimized renamed to tl.urna_source_score (the
  source-score implementation used in the manuscript). Its default lmbda is now
  0.5, the value selected by the lambda sensitivity analysis. The old name is
  kept as a deprecated alias.
• Default distance decay is also 0.5 in tl.compute_target_score (lambda_decay)
  and tl.generalized_source_score (lmbda), matching the source score.
• tl.quantify_overexpression: codeword_key and control_codewords now
  default to "control_probe" and [True, "True"].
• pp.define_urna: method now defaults to "sainsc" (the previous default,
  "segmentation_free", was not a supported method and always raised).
• Basic_tutorial.ipynb updated to the current API (pp.define_urna(prob_threshold=...),
  tl.density_similarity + tl.urna_source_score instead of the
  removed tl.compute_source_score, distance_to_source) and re-executed.

Fixed

• pl.logfoldratio_over_noise, pl.diffusion_results, pl.top_bottom_probes and
  pp.filter_urna(min_logfoldratio_over_noise=...) now read the
  logfoldchange_over_noise / is_control columns written by
  tl.quantify_overexpression (previously KeyError).
• tl.decontaminate_cell_expression / tl.credit_spillover_to_source: group with
  observed=True (categorical columns previously expanded to every
  cell x gene combination) and accept categorical cell-type labels.
• tl.generalized_source_score (and so tl.iterative_soft_decontamination): no longer
  crashes when the transcripts' gene column is categorical.
• Tests for the new spillover/decontamination functions (tests/tl/test_decontamination.py);
  removed xfail markers for the naming-drift issues fixed above.
• pl.gene_distribution_from_source: no longer crashes (FitDataError) on
  transcripts without a source cell in range (distance 0).
• tl.cell_contacts_with_urna_sources now works with the source_score table
  written by tl.adaptative_source_score(_optimized) (predicted_parent
  instead of the removed closest_cell column).
• pl.urna_vs_source_score: fixed groupby(...).mean("sum_source_score"), which passed the
  column name as numeric_only and raises under pandas 3.
• pl.spatial_transcripts_source no longer converts sdata["source_score"].obs.index to
  integers in place (this silently emptied tl.cell_contacts_with_urna_sources' uRNA
  contacts when run afterwards).
• pl.spatial_transcripts_source: cell and halo colors are now read from
  .uns[f"{key}_colors"] independently for cell_color_key and extra_color_key.
• tl.adaptative_source_score_optimized: AttributeError: 'numpy.ndarray' object has no attribute 'tocsr' when sdata["table"].X
  is a dense array — now converts via csr_matrix(...) instead of calling
  .tocsr().
• pl.global_distribution_from_source: fixed the default cluster_key
  ("kmeans_from_distribution" → "kmeans_distribution") to match the
  column actually written by tl.cluster_distribution_from_source and used
  by pl.distributions_by_cluster.
• pp.filter_urna/pp.aggregate_urna: fixed dask/spatialdata compatibility
  issues — boolean-indexing the transcripts points dataframe no longer drops
  required .attrs, and an unnecessary .compute() that broke on newer
  dask is removed.
• tl.calculate_target_cells: fixed gene alignment (reindex instead of a
  join that broke under pandas 2.3.x with a CategoricalIndex).
• Added troutpy[spatial-stats] to the test extra so the test suite's
  optional dependencies (sainsc, squidpy) are installed in CI.
• docs/notebooks/Basic_tutorial.ipynb: fixed cells with stray leading
  whitespace (caused ruff/pre-commit parse failures), an unused numpy
  import, and two calls using troutpy.pl.... instead of the notebook's
  tp alias.
• Excluded anndata==0.13.0rc1 (anndata!=0.13.0rc1): this release
  candidate makes AnnData(X=...) populate adata.layers with a None
  key, which crashes spatialdata's TableModel.parse validation
  (AttributeError: 'NoneType' object has no attribute 'lower') and broke
  the PRE-RELEASE DEPENDENCIES CI job.
• Pinned setuptools<81 in the doc extra: setuptools>=81 removed
  pkg_resources, which xarray_schema (a spatialdata dependency) still
  imports at module load, crashing import troutpy and, with it, the
  ReadTheDocs build (sphinx.errors.ExtensionError: ... no module named troutpy.pl).
• Fixed ~170 nitpicky Sphinx warnings that made the ReadTheDocs build fail
  under fail_on_warning: true:
  • Added seaborn and squidpy to intersphinx_mapping so their type
    cross-references resolve.
  • Extended nitpick_ignore for napoleon's "type, optional"/"... or
    iterable" parameter descriptions, typing.Union, and runtime-derived
    qualnames that don't match their public, intersphinx-mapped names
    (pandas.core.frame.DataFrame, SpatialData,
    seaborn.axisgrid.JointGrid, seaborn.matrix.ClusterGrid) or have no
    hosted inventory (mpl_chord_diagram.chord_diagram,
    sainsc.LazyKDE*).
  • pl.basic/pl.metric_analysis/pl.scatter/pl.factor_analysis:
    fixed :func: refs pointing at troutpy.pl.colors.get_palette/
    get_colormap to troutpy.pl.get_palette/get_colormap, matching how
    they're documented in docs/api/plotting.md.
  • tl.source_cell: removed a :func: cross-reference to the private,
    undocumented _core_scoring_engine_chunk helper.