💻 spatools
🚧 Under construction! Currently experimenting and planning! 🚧
Developed by Pedro Videira Pinho at the National Cancer Institute (Brazil) (c) 2024
spatools is a Python package built to speed up the analysis of spatial transcriptomics data. It started as a Scientific Initiation project at the National Cancer Institute (INCA, Brazil) and focuses on practical tooling for preprocessing, analysis and visualization of multi-sample spatial experiments — with a particular emphasis on colocalization: which clusters end up next to each other in the tissue, and whether that holds across samples.
🧬 Repository
github.com/pedrovp161/spatools
🧬 Modules
| module | alias | what it does |
|---|---|---|
reading |
st.read |
one entry point that detects the format and reads .h5ad, Visium folders, or a directory of samples |
processing |
st.pp |
Preprocessing (QC pipelines) and Processing (normalization, PCA/UMAP, clustering) |
tools |
st.tl |
neighborhood distances, colocalization z-scores, Spearman on deconvolution, cluster merging, spot removal, interactive selection |
plotting |
st.pl |
spatial maps, stacked bars, QC violins, colocalization heatmaps |
constants |
st.con |
ready-made color palettes |
Everything is reachable from the top-level namespace:
import spatools as st
st.read(...) # reading
st.pp.Preprocessing.run(...) # preprocessing
st.tl.correlate_distances(...)
st.pl.spatial_plot(...)
st.con.COLORS_23_HEX
Installation
pip install spatools
From source:
git clone https://github.com/pedrovp161/spatools
cd spatools
pip install -e .
Requires Python 3.9+.
Quick start
Reading
st.read() inspects the path and picks the reader for you:
import spatools as st
adata = st.read("path/to/sample.h5ad") # AnnData
adata = st.read("path/to/visium_sample/") # AnnData (folder containing spatial/)
adatas = st.read("path/to/all_samples/") # dict[str, AnnData]
Quality control
import spatools as st
adatas = st.read("data/raw")
# See every available pipeline and what it filters
st.pp.PipelineType.help()
filtered = st.pp.Preprocessing.run(
name=st.pp.PipelineType.MAD_COMBINED_WITH_MT,
adatas_dict=adatas,
k=4,
save_files=True,
output_dir="data/filtered",
)
# Per-sample stats land in uns["preprocessing_stats_<sample>"]
st.pl.preprocessing_quality_metrics(filtered)
Outlier detection uses the MAD (median absolute deviation) rather than mean ± standard deviation, since the median and MAD are not dragged around by the very outliers being detected.
Clustering
adata = st.pp.Processing.run("pearson_PCA", adata, n_pcs=30, resolution=0.5)
# or the classic path:
adata = st.pp.Processing.run("lognorm", adata, n_hvg=3000, subset_hvg=True)
Colocalization
adata = st.tl.correlate_distances(
adata, is_concatenated=True, cluster_col="clusters_0.6", batch_key="batch"
)
adata = st.tl.z_score(adata)
st.pl.z_score_matrixplot(adata, title="Cluster colocalization")
st.pl.boxplot_cluster_correlations(adata, cluster_col="clusters_0.6", subset=True, value=9)
Positive z-score means two clusters are neighbors more often than chance would predict; negative means they exclude each other.
📚 Tutorials
| notebook | covers |
|---|---|
| Pre-processing | the MAD criterion step by step, then Preprocessing across many samples, preprocessing_quality_metrics, outlier_quality |
| processing | Processing pipelines (lognorm, pearson_PCA), merge_clusters, remove_spots, translate_anndata_genes, SelectionTool |
| ploting | spatial_plot in every mode, bar, clusters_quality_violin_boxplot, color palettes |
| clustering_correlation_analysis | correlate_distances, z_score, z_score_matrixplot, boxplot_cluster_correlations, Spearman on cell2location output |
Building and publishing
Metadata lives entirely in pyproject.toml (PEP 621) — there is no setup.py:
pip install --upgrade build twine
python -m build
twine check dist/*
twine upload dist/*
Licence
1 maintainer
Metadata
1 maintainer
Release files for spatools 0.41.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| spatools-0.41.3.tar.gz | 43.3 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| spatools-0.41.3-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 87.1 kB
Release files / spatools-0.41.3.tar.gz
| Download URL | spatools-0.41.3.tar.gz |
|---|---|
| Size | 43.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6aa041a8e4b3a4e806df7058e9b2e05795234889b117d442c798677e0ee2c26f
|
|
BLAKE2b-256 checksum How to use checksums |
5180bea10b32f1d116b197bff152348e9cc0202d29f83f5cb80b0c5628346fd6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.16
|
Release files / spatools-0.41.3-py3-none-any.whl
| Download URL | spatools-0.41.3-py3-none-any.whl |
|---|---|
| Size | 43.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2d4c2c53b62c535ffc8ddc073ecdd2ee5e7ebc767c8a70de300d7ae31f50c470
|
|
BLAKE2b-256 checksum How to use checksums |
dfdded786dfc2a096db1c7254f8e255be352d5dfd9705a5696c6bf836fde0ac7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.16
|
