SPAC: Analysis of SPAtial Single Cell Datasets

SPAC is a scalable, automated pipeline, under the Single Cell Spatial Analysis Workflow (SCSAWorkflow) project aiming at analyzing single-cell spatial protein data of multiplexed whole-slide tissue images generated from technologies such as MxIF Codex and Imaging Mass Cytometry (IMC). This Python-based package leverages the anndata framework for easy integration with other single-cell toolkits. It includes a multitude of functional and visualization modules, test utilities, and is capable of running in user-friendly web interfaces. SPAC offers insights into cell interactions within various environments, aiding in studies of the cancer microenvironment, stem cell niches, and drug response effects etc.

This repository is the official home of the SPAC Python package, part of the broader SPAC ecosystem for single-cell spatial analysis.

SPAC Ecosystem

| Component | Description | Repository | |-----------|-------------|------------| | SPAC Python Package | Core analysis library | This repository | | SPAC Shiny | Interactive web application | FNLCR-DMAP/SPAC_Shiny |

Installing SPAC with Conda

Run the following command to establish the Conda environment supporting usage and contribution to spac package: Latest released version is v0.9.0 at 5/23/2025 ```bash cd git checkout address-reviewer-comments

If conda is not activate

conda activate

Adding constumized scimap conda pacakge channel supported by DMAP

conda config --add channels https://fnlcr-dmap.github.io/scimap/

Create the Conda environment from environment.yml

conda env create -f environment.yml

Once environment is established

conda activate spac

Install the SPAC package in development mode

pip install -e . `` The envrionment works for Linux and noarc, if your are working on amd processor (commonly seen for latest Mac users), please replace the - numpy=1.26.4withnumpy>=1.26.4,<2.0.0, and remove the- scimap=2.1.3dmappandas153but add pip- scimap`

If error occurs suggesting SSL certificate not found for our scimap channel, please run the following command before the environment creation: conda config --set ssl_verify false Then set the verification to True after the installation: conda config --set ssl_verify true

Using SPAC with Docker

For a reproducible environment, you can use Docker to run SPAC.

📘 For detailed Docker documentation including development mode with live code mounting, see docker/README.md

Quick commands: - Production: make build → make run - Development: make dev (changes to src/ reflected immediately!) - Help: make help

Build the Docker Image

bash docker build -t spac .

Run Jupyter Notebook Server with Your Data

Mount your working directory to access notebooks and data: ```bash

Stop any existing containers using port 8888 (if needed)

docker stop $(docker ps -q --filter "publish=8888") 2>/dev/null || true

From the project root directory

docker run --rm -p 8888:8888 -v $(pwd)/paper/examples:/workspace spac

Or mount any directory containing your notebooks and data

docker run --rm -p 8888:8888 -v /path/to/your/data:/workspace spac ```

Then open your browser to: http://localhost:8888

Test SPAC Installation

To validate that SPAC works correctly, run the notebook execution test: ```bash

Navigate to the paper directory

cd paper

Run the test script in Docker (mounts examples directory and test script)

docker run --rm -v $(pwd)/examples:/workspace -v $(pwd)/testnotebookexecution.sh:/testscript.sh spac bash /testscript.sh ```

This test will: - ✅ Verify SPAC and scimap installation - ✅ Execute the example lymphnode analysis notebook
- ✅ Create a timestamped output file (e.g., lymphnode_analysis_executed_20231023_134803.ipynb) - 📓 Provide instructions for viewing results in Jupyter

View Executed Notebooks

After running the test, you can view the executed notebook in Jupyter: ```bash

Navigate to paper/examples directory

cd paper/examples

Stop any existing containers using port 8888 (if needed)

docker stop $(docker ps -q --filter "publish=8888") 2>/dev/null || true

Start Jupyter server with your data mounted

docker run --rm -p 8888:8888 -v $(pwd):/workspace spac ```

Then open your browser to: http://localhost:8888 and navigate to the timestamped executed notebook file.

Validate Performance Improvements

To verify the performance speedups implemented in SPAC: ```bash

Navigate to the paper directory

cd paper

Run the performance validation script in Docker (mounts current directory for results)

Note: Ensure Docker has at least 16GB memory allocated for full validation

docker run --rm -v $(pwd):/workspace -v $(pwd)/testperformancevalidation.sh:/testscript.sh spac bash /testscript.sh ```

This test will: - ✅ Run boxplot performance benchmarks (up to 10M cells: boxplot vs boxplot_interactive) - ✅ Run histogram performance benchmarks (up to 10M cells: histogram_old vs histogram)
- ✅ Generate detailed speedup analysis with concrete performance improvements - 📊 Generate detailed speedup analysis and performance reports - � Save results to your local performance_results/ directory

Performance results are saved locally as timestamped files in performance_results/: - boxplot_performance_YYYYMMDD_HHMMSS.txt - histogram_performance_YYYYMMDD_HHMMSS.txt

Interactive Shell Access

For debugging or manual exploration: bash docker run --rm -it spac bash

Mount Local Data

To work with your own data, mount a local directory: ```bash

Stop any existing containers using port 8888 (if needed)

docker stop $(docker ps -q --filter "publish=8888") 2>/dev/null || true

Mount your data directory

docker run --rm -p 8888:8888 -v /path/to/your/data:/data spac ```

Docker Cleanup

If you need to clean up Docker resources: ```bash

Stop all SPAC containers

docker stop $(docker ps -q --filter "ancestor=spac") 2>/dev/null || true

Remove stopped containers (optional)

docker container prune -f

Remove SPAC image (if you want to rebuild from scratch)

docker rmi spac ```

Contirbuting to SPAC:

Review the developer guide

License

spac was created by Fang Liu, Rui He, and George Zaki. It is licensed under the terms of the BSD 3-Clause license.

Credits

spac was created with cookiecutter and the py-pkgs-cookiecutter template.