API

API#

Importing InSituPy#

import insitupy as isp

Individual submodules can then be imported like this:

isp.dataclasses
isp.io
isp.plotting

Core Data Objects#

Individual datasets#

InSituData([path, metadata, slide_id, ...])

InSituData class for managing and analyzing spatially resolved transcriptomics data.

Read a saved InSituData object with:

InSituData.read(path)

Read an InSituData object from a specified folder.

Handle multiple datasets#

InSituExperiment([data_type])

A class to manage and analyze multiple spatially resolved single-cell transcriptomics experiments.

Read a saved InSituExperiment project with:

InSituExperiment.read(path[, mode, filter_key])

Read an InSituExperiment object from a specified folder.

To generate a new InSituExperiment object, either from a configurations file or from histological regions, following functions are available:

`InSituExperiment.from_config`(config_path, mode)	Create an InSituExperiment object from a configuration file.
`InSituExperiment.from_regions`(data, region_key)	Creates an `InSituExperiment` object from specified regions in the given `InSituData`.

To concatenate multiple InSituExperiment objects:

InSituExperiment.concat(objs[, new_col_name])

Concatenate multiple InSituExperiment objects.

Working with saved sample filters (experimental):

Warning

This filter workflow is currently experimental and may change in future releases.

from insitupy import InSituExperiment

exp = InSituExperiment.read("path/to/experiment")

exp.filters.create(
    by="sample_id",
    include=["S01", "S02", "S05"],
    key="general_quality",
    note="Samples with overall good quality in total counts and morphology"
)

# overview table with selected/excluded counts and notes
exp.filters.summary()

# programmatic access to raw boolean masks
exp.filters.masks()

# full project save (datasets + metadata + colors + filters)
exp.save()

# dedicated partial-save helpers
exp.save_metadata()
exp.save_colors()
exp.save_images(overwrite=False)

# load later with filter applied
exp2 = InSituExperiment.read("path/to/experiment", filter_key="general_quality")

# detached subset (export workflow): exp_apply.path is None
exp_apply = exp.filters.apply("general_quality")

# linked lightweight view (in-place update workflow)
exp_view = exp.filters.view("general_quality")
exp_view.is_view            # True
exp_view.applied_filters    # ["general_quality"]

# Add another view filter; chain of applied filters is tracked
exp_view2 = exp_view.filters.view("tumor_only")
exp_view2.applied_filters   # ["general_quality", "tumor_only"]

# view.save() updates only selected InSituData objects in-place
# and does not overwrite experiment-level metadata/colors/filters
exp_view2.save()

Notes:

exp.filters.apply(key) returns a detached InSituExperiment subset (safe for saveas() export workflows).
exp.filters.view(key) returns a lightweight linked view (InSituExperimentView) with path linkage preserved.
Dataset identity is tracked via uid in metadata; filtered view indices are view-local and may differ from the parent experiment.

Import data objects#

Import the data objects like this:

from insitupy import InSituData, InSituExperiment

Core Data Classes#

Data classes are used to store the different modalities.

Cellular data#

`dataclasses.CellData`(table, boundaries[, config])	Data object containing an AnnData object and a boundary object which are kept in sync.
`dataclasses.MultiCellData`()	Data object containing multiple CellData objects.
`dataclasses.BoundariesData`(cell_names, ...)	Object to read and load boundaries of cells and nuclei.

Image data#

dataclasses.ImageData([img_files, ...])

Object to read and load images.

Geometric data#

`dataclasses.ShapesData`([files, keys, ...])	Object to store annotations.
`dataclasses.AnnotationsData`([files, keys, ...])
`dataclasses.RegionsData`([files, keys, ...])

The different data classes can be read using following functions:

`dataclasses.read_celldata`(path)	Read CellData from a saved directory.
`dataclasses.read_multicelldata`(path[, ...])
`dataclasses.read_shapesdata`(path, mode[, ...])

Read external data#

Following functions allow reading data from external sources, e.g. from an Xenium In Situ experiment or from QuPath. To read an individual dataset on can use following functions:

`io.read_qupath`(path, pixel_size, ...[, ...])	Load and process QuPath-exported spatial data into an `InSituData` object.
`io.read_xenium`(path[, nuclei_type, ...])	Reads Xenium In Situ data from the specified directory.

To read multiple datasets exported from QuPath into an InSituExperiment object, following functions can be used:

io.read_qupath_project(path[, pixel_size, ...])

Load and process a full QuPath project directory into an InSituExperiment object.

Plotting#

Import the plotting submodule either as isp.plotting or isp.pl.

`plotting.spatial`(data, keys[, cells_layer, ...])	Plot spatial omics data with optional images, annotations, and regions.
`plotting.cellular_composition`(data, ...[, ...])	Plots the composition of cell types for specified regions or annotations.
`plotting.cell_abundance_along_axis`(adata, axis)	Plot cell abundance along a specified axis.
`plotting.cell_expression_along_axis`(adata, ...)	Plot gene expression along a specified axis for selected cell types.
`plotting.volcano`(results[, ...])	Generate multi-panel volcano plots for differential expression results.
`plotting.colorlegend`([viewer, mapping, ...])
`plotting.overview`(data[, cells_layer, ...])	Plots an overview table with metadata and quality control metrics.

API

Contents