Package 'SpaceTrooper'

Description

.getActiveGeometryName

Usage

.getActiveGeometryName(sf)

Arguments

Value

character with the name of the active geometry

Examples

example(readPolygonsCosmx)
.getActiveGeometryName(polygons)

Description

renames the 'from' to 'to' geometry of the 'sf' object. If 'activate' is 'TRUE' it set as the active geometry the new geometry name. Default behaviour is to check if the renamed geometry is already active and leave it as active with the new name.

Usage

.renameGeometry(sf, from, to, activate = FALSE)

Arguments

Value

an sf object

Examples

example(readPolygonsCosmx)
.renameGeometry(polygons, "global", "global1")

Description

.setActiveGeometry

Usage

.setActiveGeometry(sf, name)

Arguments

Value

an sf object

Examples

example(readPolygonsCosmx)
.setActiveGeometry(polygons, "local")

Description

This function adds polygon data to a 'SpatialExperiment' object.

Usage

addPolygonsToSPE(spe, polygons, polygonsCol = "polygons")

Arguments

Value

The 'SpatialExperiment' object with polygons added to the 'colData'.

Examples

example(readCosmxSPE)
polygons <- readPolygonsCosmx(metadata(spe)$polygons)
spe <- addPolygonsToSPE(spe, polygons)
spe$polygons

Description

Checks if computed outliers meet the minimum numerical requirement, being at least 0.1 If the requirement is not met, the variable is removed from the formula.

Usage

checkOutliers(spe, verbose = FALSE)

Arguments

Details

The function checks if computed outliers for each metric meet the minimum number to get the metric included in the QC score formula. If verbose is TRUE, it also prints how many outliers were found for each metric.

Value

The 'SpatialExperiment' object with added QCScore metric variables in the 'metadata'.

Examples

example(computeOutliersQCScore)
spe <- checkOutliers(spe, verbose = TRUE)
metadata(spe)$formula_variables

Description

This function computes the area from polygon data.

Usage

computeAreaFromPolygons(polygons)

Arguments

Value

A 'numeric' vector with the area information.

Examples

example(readPolygonsMerfish)
area <- computeAreaFromPolygons(polygons)
area

Description

This function computes the aspect ratio (width / height) from polygon data.

Usage

computeAspectRatioFromPolygons(polygons)

Arguments

Value

A 'numeric' vector with the aspect ratio information.

Examples

example(readPolygonsMerfish)
ar <- computeAspectRatioFromPolygons(polygons)
ar

Description

This function computes the center coordinates on x and y axis from polygon data and adds it to the 'colData'. It is necessary only for Merfish.

Usage

computeCenterFromPolygons(polygons, coldata)

Arguments

Value

A 'DataFrame' with the added center information.

Examples

example(readPolygonsMerfish)
coldata <- computeCenterFromPolygons(polygons, colData(spe))
colData(spe) <- coldata

Description

Compute Optimal Ridge Regularization Parameter $\lambda$ via Cross-Validation

computeLambda performs ridge (L2) logistic regression with cross-validation to identify the optimal regularization parameter $\lambda$ for a binary response.

Usage

computeLambda(trainDF, modelFormula)

Arguments

Details

Internally, the function: Constructs the design matrix via model.matrix(), Runs ridge logistic regression cross-validation using 'cv.glmnet' with 'alpha = 0', Extracts and returns 'ridge_cv$lambda.min'.

Value

'numeric' The value of $\lambda$ (i.e., 'lambda.min') from 'cv.glmnet' that minimizes the cross-validation error.

Examples

example(computeTrainDF)
modform <- getModelFormula(metadata(spe)$formula_variables)
best_lambda <- computeLambda(df_train, modform)
print(best_lambda)

Description

'computeMissingMetricsMerfish()' takes cell metadata and boundary polygons, calculates per‐cell area and aspect‐ratio, and optionally appends the raw polygon geometries.

Usage

computeMissingMetricsMerfish(
  polFile,
  coldata,
  boundariesType = c("parquet", "HDF5"),
  keepPolygons = FALSE,
  polygonsCol = "polygons",
  useVolume = TRUE
)

Arguments

Details

'computeMissingMetricsMerfish()' reads polygon geometries via 'readPolygonsMerfish(polFile, type=boundariesType)' where 'polFile' is a Parquet file (parquet) or a folder of HDF5 files (HDF5). It expects 'coldata' to contain at least 'cell_id'.

Behavior: - If 'useVolume=TRUE' and 'coldata' contains a 'volume' column, the returned 'Area_um' is set to 'volume'. Otherwise 'Area_um' is computed from the polygons using 'computeAreaFromPolygons()'. - 'AspectRatio' is computed from polygons using 'computeAspectRatioFromPolygons()'. - If 'keepPolygons=TRUE', geometries are attached to the returned 'DataFrame' under the name given by 'polygonsCol'.

Important: polygons must align (in order or by matching logic) with the rows of 'coldata'; otherwise area/aspect values may be assigned incorrectly.

Value

A 'DataFrame' (or 'data.frame') with: - all columns of 'coldata' - 'Area_um': area/volume of each cell’s polygon - 'AspectRatio': width/height aspect ratio - (optionally) the polygon geometries

Examples

example(readMerfishSPE)
cd <- computeMissingMetricsMerfish(metadata(spe)$polygons, colData(spe),
    boundariesType="parquet")
colData(spe) <- cd
cd

Description

Compute Missing Metrics for Xenium Data

This function computes missing metrics, such as the aspect ratio, from polygon data in a Xenium dataset and optionally appends the polygon data to the resulting 'colData'.

Usage

computeMissingMetricsXenium(
  polFile,
  colData,
  keepPolygons = FALSE,
  polygonsCol = "polygons"
)

Arguments

Details

The function reads the polygon data from the specified file, computes the aspect ratio for each polygon, and merges these metrics with the provided 'colData'. Optionally, the polygon data can be kept in the returned 'colData'.

Value

A 'DataFrame' containing the updated 'colData' with computed metrics. If 'keepPolygons' is 'TRUE', the polygon data is also included.

Examples

example(readXeniumSPE)
colData(spe) <- computeMissingMetricsXenium(metadata(spe)$polygons,
    colData(spe), keepPolygons=TRUE)

Description

Compute outlier cells for each metric that can be used in QC score formula for SpatialExperiment.

This function calculates outlier cells for each variable specified in 'metricList' for a 'SpatialExperiment'. log2SignalDensity must be present in the 'colData' of the 'SpatialExperiment' object as a minimum requirement. The user can choose which metrics to include among the following: Area_um, log2Ctrl_total_ratio, log2AspectRatio. For Xenium and Merfish datasets, log2AspectRatio is automatically removed from the formula.

Usage

computeOutliersQCScore(
  spe,
  metricList = c("log2SignalDensity", "Area_um", "log2AspectRatio",
    "log2Ctrl_total_ratio")
)

Arguments

Details

The function computes outliers for each specified metric after automatically choosing the appropriate method according to the skewness of the distribution. Internally the function:

1. Calls .checkSkw() to choose the proper outlier detection method according to the variable skewness,

2. Calls computeSpatialOutlier() on each included metric to get fences,

3. Labels cells as “LOW”/“HIGH” outliers or “NO”

Value

The 'SpatialExperiment' object with added outlier variables in 'colData' and the temporary QCScore metric variables that in the 'metadata'.

Examples

example(readCosmxSPE)
spe <- spatialPerCellQC(spe)
spe <- computeOutliersQCScore(spe)
table(spe$log2SignalDensity_outlier_train)

Description

Compute QC score and automatically define weights for QC score through glm training. This function computes QC score with a formula defined on the metrics as "log2SignalDensity", "Area_um", "log2AspectRatio", "log2Ctrl_total_ratio", as computed from the 'spatialPerCellQC' function. It automatically computes the number of available outliers for each available metric, as they are needed for the glm training. See Details for further information.

Usage

computeQCScore(spe, bestLambda = NULL, verbose = FALSE)

Arguments

Details

For all the techologies, the QC Score formula depends on the follow metrics:

QC score ~ count density - aspect ratio - control-total ratio - size

Where count density is the total counts-to-size ratio, aspect ratio represents the ratio between the width and the height of the cell (computed from the provided polygons if not already present in the experiment metadata) and control-total ratio is the aspecific signal; size is the area for CosMx and Xenium, while it is the volume for Merfish. For each couple of variables interaction terms are computed.

Additionally, for CosMx datasets, the distance from the border of the FOV is also included in the formula as a metric to take into account . For Xenium and Merscope datasets, QC score cannot depend on FoV border effect, as no FOV border effect was captured through this metric.

Note that the function is responsible for automatically including/excluding metrics in the formula based on their availability in the 'colData' of the 'SpatialExperiment' object.

Inclusion of metrics in the formula depends also on the number of available outliers. If the number of outliers for each metric is < 0.1 entire dataset, the metric will be excluded from the QC score formula.

- Model fitting: ridge (L2) logistic regression is fitted (via 'glmnet') on the balanced training set. The function uses 'trainModel()' for fitting and 'computeLambda()' (cross‑validation) to select lambda unless 'bestLambda' is supplied.

- Lambda details: because of the randomness in the training set selection, results may vary so that it is possible to set a fixed lambda value previously computed with 'computeLambda' preceeded by 'computeTrainDF' and 'getModelFormula'. This is useful for reproducibility across different runs. Otherwise, an easier way is to let be lambda computed internally, just set a seed with 'set.seed()' before running 'computeQCScore'.

Value

The 'SpatialExperiment' object with added QC score in 'colData'.

Examples

example(spatialPerCellQC)
set.seed(1998)
spe <- computeQCScore(spe)
summary(spe$QC_score)

Description

Compute flagged cells based on a manually chosen threshold on quality score

This function Compute flagged cells based on a manually chosen threshold on quality score stored in 'SpatialExperiment' object.

Usage

computeQCScoreFlags(spe, qsThreshold = 0.5, useQSQuantiles = FALSE)

Arguments

Value

The 'SpatialExperiment' object with added filter flags in 'colData'.

Examples

example(computeQCScore)
spe <- computeQCScoreFlags(spe)
table(spe$low_qcscore)
# if fixed filters are defined we have an additional column
spe <- computeThresholdFlags(spe)
spe <- computeQCScoreFlags(spe)
table(spe$low_threshold_qcscore)

Description

Computes outliers based on the Area (in micron) of the experiment. It gives the possibility to choose between the medcouple (mc method argument) and the MADs (scuttle method argument).

Usage

computeSpatialOutlier(
  spe,
  computeBy = NULL,
  method = c("mc", "scuttle", "both"),
  mcDoScale = FALSE,
  scuttleType = c("both", "lower", "higher")
)

Arguments

Details

The medcouple method is a measure for the skeweness of univariate distribution as described in Hubert M. et al. (2008). In particular, the computed medcouple value must be in a range between -0.6 and 0.6 to computed adjusted boxplots and perform the outlier detection. For median absolute deviations (MADs) method we just wrap the isOutlier function in the scuttle package. Please see McCarthy DJ et al (2017) for further details.

Value

a SpatialExperiment object with additional column(s) (named as the column name indicated in 'column_by' followed by the outlier_sc/mc nomenclature) with the outlier detection as 'outlier.filter' logical class object. This allows to store the thresholds as attributes of the column. use attr(,"thresholds") to retrieve them.

Examples

example(spatialPerCellQC)
spe <- computeSpatialOutlier(spe, computeBy="log2SignalDensity", method="both")
table(spe$log2SignalDensity_outlier_mc)
table(spe$log2SignalDensity_outlier_sc)

Description

Compute Flagged cells using fixed thresholds for SpatialExperiment.

This function calculates flagged cells only for total counts and control on total probe counts ratio using fixed thresholds for a 'SpatialExperiment' object.

Usage

computeThresholdFlags(spe, totalThreshold = 0, ctrlTotRatioThreshold = 0.1)

Arguments

Details

The function flags cells basing on zero counts and control-to-total ratio to identify junk cells. It also combines these flags into a single filter flag.

Value

The 'SpatialExperiment' object with added filter flags in 'colData'.

Examples

example(readCosmxSPE)
spe <- spatialPerCellQC(spe)
spe <- computeThresholdFlags(spe)
table(spe$threshold_flags)

Description

Build a Balanced Training Data Frame from a SpatialExperiment

computeTrainDF takes a SpatialExperiment object and assembles a balanced training set of “good” vs “bad” cells for subsequent model fitting.

Usage

computeTrainDF(colData, formulaVars, tech, verbose = FALSE)

Arguments

Details

The function builds a training set using the variables specified in the 'metadata' of the 'SpatialExperiment' object.

Value

A data.frame with one row per cell, including: qcscore_train (0/1) indicating “bad” vs “good”, relevant colData columns used for modeling. Deduplicates and down-samples “good” cells to match the number of “bad” cells.

Examples

example(spatialPerCellQC)
spe <- computeOutliersQCScore(spe)
spe <- checkOutliers(spe)
df_train <- computeTrainDF(colData(spe), metadata(spe)$formula_variables,
    metadata(spe)$technology)
table(df_train$qcscore_train)

Description

Retrieve Threshold (Fence) Values from a SpatialExperiment Object

This function extracts the threshold values, also known as fences, from a specified column in the 'colData' of a 'SpatialExperiment' object.

Usage

getFencesOutlier(
  spe,
  fencesOf,
  highLow = c("both", "lower", "higher"),
  decimalRound = NULL
)

Arguments

Value

A numeric vector containing the lower and upper threshold values extracted from the specified column.

Examples

example(computeSpatialOutlier)
getFencesOutlier(spe, fencesOf="log2SignalDensity_outlier_mc")

Description

Returns the right‐hand side of a model formula string based on formula variables found in the 'metadata' of a 'SpatialExperiment' object.

Usage

getModelFormula(formulaVars, verbose = FALSE)

Arguments

Value

'character' A one‐sided formula as a string (e.g. "~ log2SignalDensity + ...").

Examples

example(checkOutliers)
getModelFormula(metadata(spe)$formula_variables)

Description

Plot cell centroids in FoVs, creating a map of the whole experiment, where cells are plotted as points and FoV boundaries and numbers are overlaid.

Usage

plotCellsFovs(
  spe,
  sampleId = unique(spe$sample_id),
  pointCol = "firebrick",
  numbersCol = "black",
  alphaNumbers = 0.8,
  fovDim = metadata(spe)$fov_dim,
  size = 0.05,
  alpha = 0.8,
  scaleBar = TRUE,
  micronConvFact = 0.12
)

Arguments

Details

The function expects spe (a SpatialExperiment) to include field-of-view metadata in metadata(spe): - 'metadata(spe)$fov_positions': a matrix or data.frame (or list with named elements) containing at minimum 'x_global_px', 'y_global_px', and 'fov'. Values 'x_global_px'/'y_global_px' are in pixels and represent the origin (top-left) of each FoV. - 'metadata(spe)$fov_dim' (or the 'fovDim' argument): a named numeric with 'xdim' and 'ydim' giving FoV width/height in pixels.

For each FoV the rectangle is drawn as: - 'xmin' = 'x_global_px', - 'xmax' = 'x_global_px' + 'xdim', - 'ymin' = 'y_global_px', - 'ymax' = 'y_global_px' + 'ydim'.

'sampleId': if 'NULL' no plot title is added; if a vector of length > 1 is provided the first element is used. Prefer passing a single sample identifier string. 'micronConvFact' is the conversion factor from pixels to micrometers (µm/pixel). It is forwarded to '.plotScaleBar()' and controls how the scale bar is labeled (useful for technologies where coordinates are in pixels but the scale should display µm). The function uses the coordinates returned by 'spatialCoords(spe)' and the names from 'spatialCoordsNames(spe)'. It performs basic input checks but assumes the described metadata structures are present; if they are missing or malformed the function will raise an informative error.

Value

A 'ggplot' object showing cell centroids and FoV boundaries.

Examples

example(readCosmxSPE)
g <- plotCellsFovs(spe)
print(g)

Description

Plot Spatial Coordinates for a SpatialExperiment Object This function generates a ggplot of spatial coordinates from a 'SpatialExperiment' object, optionally coloring the points by a specified column in 'colData'.

Usage

plotCentroids(
  spe,
  colourBy = NULL,
  colourLog = FALSE,
  sampleId = unique(spe$sample_id),
  isNegativeProbe = FALSE,
  palette = NULL,
  pointCol = "darkmagenta",
  size = 0.05,
  alpha = 0.8,
  aspectRatio = 1,
  scaleBar = TRUE,
  micronConvFact = 0.12
)

Arguments

Details

This function plots cell centroids from a 'SpatialExperiment' object using coordinates returned by 'spatialCoords(spe)' and the coordinate names from 'spatialCoordsNames(spe)' (the function expects at least two spatial coordinate dimensions). If 'colourBy' is 'NULL' all points are drawn using 'pointCol'; otherwise the function colors points using the specified 'colData' column or a provided palette.

Requirements and inputs: - 'spe' must be a 'SpatialExperiment' with valid spatial coordinates. - If 'colourBy' is provided and is the name of a 'colData' column, that column must exist and be suitable for plotting (factor/logical for discrete palettes, numeric for continuous palettes). - 'palette' may be either (a) a vector of color values (used directly) or (b) the name of a column in 'colData(spe)' from which a palette will be built via 'createPaletteFromColData()'. The function detects which mode to use at runtime.

Value

A 'ggplot' object representing the spatial coordinates plot of polygon centroids.

Examples

example(readCosmxSPE)
g <- plotCentroids(spe, colourBy="Mean.DAPI")
print(g)

Description

Plot a Histogram for a Given Metric in a SpatialExperiment Object

This function generates a histogram for a specified metric in a 'SpatialExperiment' object.

Usage

plotMetricHist(
  spe,
  metric,
  fillColor = "#c0c8cf",
  useFences = NULL,
  fencesColors = c(lower = "purple4", higher = "tomato"),
  bins = 30,
  binWidth = NULL
)

Arguments

Value

A 'ggplot' object representing the histogram of the specified metric.

Examples

example(readCosmxSPE)
g <- plotMetricHist(spe, metric="Mean.DAPI")
print(g)

Description

Plot polygons from a 'SpatialExperiment' object using ggplot2.

Usage

plotPolygons(
  spe,
  colourBy = "darkgrey",
  colourLog = FALSE,
  polyColumn = "polygons.global",
  sampleId = unique(spe$sample_id),
  bgColor = "white",
  fillAlpha = 1,
  palette = NULL,
  borderCol = NA,
  borderAlpha = 1,
  borderLineWidth = 0.1,
  drawBorders = TRUE,
  scaleBar = TRUE,
  micronConvFact = 0.12
)

Arguments

Details

Renders polygon geometries stored in 'colData' of a 'SpatialExperiment' object using 'ggplot2::geom_sf()' and provides options for fill, borders and an optional scale bar.

Input expectations: - 'spe' must be a 'SpatialExperiment' and 'polyColumn' must name a column in 'colData(spe)' that contains polygon geometries ('sfc'/'sf' or a list of geometry objects) suitable for 'geom_sf()'. - 'colourBy' supports two modes: (a) the name of a 'colData' column to map fill to data values, or (b) a literal colour name (e.g. '"darkgrey"') used as a constant fill.

Colour / palette behaviour: - If 'colourBy' refers to a 'colData' column and 'colourLog = TRUE', the function computes 'log1p()' of that column in the local plotting data frame (it does not mutate 'spe'). - 'palette' may be a vector of colour values (used for discrete scales). Numeric 'colourBy' values use a continuous Viridis-like scale by default.

Scale bar and units: - If 'scaleBar = TRUE' the function calls '.plotScaleBar()' to add a length scale. 'micronConvFact' is the conversion factor (µm per pixel) used by '.plotScaleBar()' to label the bar in micrometres when appropriate.

Robustness notes: - If 'colourBy' is neither a 'colData' column nor a valid colour name the function issues a warning and falls back to the default fill.

Value

A 'ggplot' object representing the polygon plot of the spatial data.

Examples

example(readAndAddPolygonsToSPE)
plotPolygons(spe, colourBy="Mean.DAPI")

Description

Plots the individual terms that combine into the quality score formula, allowing assessment of each term's impact on the final score.

Usage

plotQScoreTerms(
  spe,
  sampleId = unique(spe$sample_id),
  size = 0.05,
  alpha = 0.8,
  aspectRatio = 1,
  custom = FALSE
)

Arguments

Value

A combined plot (via 'cowplot::plot_grid') showing spatial maps of each QS term.

Examples

example(readAndAddPolygonsToSPE)
example(spatialPerCellQC)
p <- plotQScoreTerms(spe)
print(p)

Description

Plot Zoomed-in FOVs with Map and Polygons

This function generates a plot that shows a map of all fields of view (FOVs) within a 'SpatialExperiment' object, alongside a zoomed-in view of the specified FOVs with an overlay of polygons and optional coloring.

Usage

plotZoomFovsMap(
  spe,
  fovs = NULL,
  title = NULL,
  mapPointCol = "darkmagenta",
  mapNumbersCol = "black",
  mapAlphaNumbers = 0.8,
  csize = 0.05,
  calpha = 0.8,
  scaleBars = NULL,
  scaleBarMap = TRUE,
  scaleBarPol = TRUE,
  ...
)

Arguments

Details

The function first filters the 'SpatialExperiment' object to the specified FOVs, generates a plot of the cells for the entire map, then creates a detailed polygon plot of the selected FOVs, and finally combines these into a single side-by-side visualization. If 'title' is not 'NULL', it adds a title to the combined plot.

Value

A combined plot showing a map of all FOVs with zoomed-in views of the specified FOVs and their associated polygons.

Examples

example(readAndAddPolygonsToSPE)
plotZoomFovsMap(spe, fovs=16, title="FOV 16")

Description

Plots the flagged cells identified with first filter, based on control count on total count ratio, area in um and DAPI signal.

This function generates a plot that shows selected (FOVs) within a 'SpatialExperiment' object, with cells flagged in different colors over a light or dark layout chosen by the user.

Usage

qcFlagPlots(
  spe,
  fov = unique(spe$fov),
  theme = c("light", "dark"),
  custom = FALSE
)

Arguments

Value

A panel with multiple plots showing flagged cells for different variables.

Examples

example(readAndAddPolygonsToSPE)
spe <- spatialPerCellQC(spe)
spe <- computeThresholdFlags(spe)
p <- qcFlagPlots(spe, fov=16, theme="dark")
print(p)

Description

Read and Add Polygons to a SpatialExperiment Object

This function reads polygon boundary data based on the technology associated with the provided SpatialExperiment (SPE) object and adds the polygons to the SPE.

Usage

readAndAddPolygonsToSPE(
  spe,
  polygonsCol = "polygons",
  keepMultiPol = TRUE,
  boundariesType = c("csv", "HDF5", "parquet")
)

Arguments

Details

The function first checks the technology specified in the SPE's metadata. Based on the technology, it reads the appropriate polygon data using the corresponding reading function: - For "Nanostring_CosMx" or "Nanostring_CosMx_Protein", it uses 'readPolygonsCosmx()'. - For "Vizgen_MERFISH", it uses 'readPolygonsMerfish()'. - For "10X_Xenium", it uses 'readPolygonsXenium()'. After reading the polygons, it adds them to the SPE using 'addPolygonsToSPE()'.

Value

A SpatialExperiment object with the added polygon data.

Examples

example(readCosmxSPE)
spe <- readAndAddPolygonsToSPE(spe)
colData(spe)

Description

Read and Construct a SpatialExperiment Object from CosMx Data

This function reads in data from Nanostring CosMx files and constructs a 'SpatialExperiment' object, optionally including polygons data.

Usage

readCosmxSPE(
  dirName,
  sampleName = "sample01",
  coordNames = c("CenterX_global_px", "CenterY_global_px"),
  countMatFPattern = "exprMat_file.csv",
  metadataFPattern = "metadata_file.csv",
  polygonsFPattern = "polygons.csv",
  fovPosFPattern = "fov_positions_file.csv",
  fovdims = c(xdim = 4256, ydim = 4256),
  keepPolygons = FALSE,
  polygonsCol = "polygons"
)

Arguments

Details

The function firstly relies on readCosmxSXE to read in the specified files for count matrices, metadata, and FOV positions constructing a 'SpatialExperiment' object. Then it harmonizes the object to have the same metadata as for the other technologies, setting the colData names as required in further QC analysis.

Optionally, polygons data can be read and added to the object by seeting the 'keepPolygons' argument to 'TRUE', otherwise it only stores the polygons file path into the object metadata.

readCosmxProteinSPE is a wrapper of readCosmxSPE, it changes the technology metadata in Nanostring_CosMx_Protein.

Value

A 'SpatialExperiment' object containing the read CosMx data, including count matrices, metadata, and optionally polygons.

Author(s)

Dario Righelli, Benedetta Banzi

Examples

cospath <- system.file(file.path("extdata", "CosMx_DBKero_Tiny"),
   package="SpaceTrooper")
spe <- readCosmxSPE(cospath, sampleName="DBKero_Tiny")

Description

'readMerfishSPE()' imports MERFISH/Merscore outputs (counts, metadata, and optionally cell boundary polygons) from a directory and builds a SpatialExperiment object.

Usage

readMerfishSPE(
  dirName,
  sampleName = "sample01",
  computeMissingMetrics = TRUE,
  keepPolygons = FALSE,
  boundariesType = c("parquet", "HDF5"),
  countmatFPattern = "cell_by_gene.csv",
  metadataFPattern = "cell_metadata.csv",
  polygonsFPattern = "cell_boundaries.parquet",
  coordNames = c("center_x", "center_y"),
  polygonsCol = "polygons",
  useVolume = TRUE
)

Arguments

Details

The function searches 'dirName' for three resources using the provided filename patterns: the count matrix ('countmatFPattern'), the cell metadata ('metadataFPattern'), and the polygon resource ('polygonsFPattern'). The count matrix and metadata are expected to contain a 'cell_id' column (aliases 'V1', 'cell', or 'EntityID' are renamed). If 'computeMissingMetrics' is TRUE, 'computeMissingMetricsMerfish()' is invoked and receives 'useVolume'.

The returned 'SpatialExperiment' contains: - 'assays$counts': gene × cell count matrix (rows = genes, cols = 'cell_id'); - 'colData': per-cell metadata (may be reordered by the function); - spatial coordinates named by 'coordNames'; - 'metadata$polygons': path(s) matched by 'polygonsFPattern'; - 'metadata$technology': '"Vizgen_MERFISH"'.

Side effects: the function may reorder 'colData' columns, attach polygon file paths to 'metadata(spe)$polygons', and (when requested) append 'Area_um' and 'AspectRatio' to 'colData'.

Value

A 'SpatialExperiment' object with: - 'assays$counts': gene × cell count matrix - 'colData': per‐cell metadata (including computed metrics) - spatial coordinates named by 'coordNames' - 'metadata$polygons': path to the boundaries file - 'metadata$technology': '"Vizgen_MERFISH"'.

Author(s)

Dario Righelli, Benedetta Banzi

Examples

path <- system.file("extdata", "Merfish_Tiny",
                    package = "SpaceTrooper")
spe <- readMerfishSPE(
  dirName = path,
  sampleName = "Patient2",
  keepPolygons = TRUE,
  boundariesType = "parquet"
)
spe

Description

Read and Validate Polygons from a File

This function reads polygon data from a specified file, validates the polygons, and returns them as an 'sf' object. It supports multiple file formats and can handle both global and local coordinates.

Usage

readPolygons(
  polygonsFile,
  type = c("csv", "parquet", "h5"),
  x = c("x_global_px", "vertex_x"),
  y = c("y_global_px", "vertex_y"),
  xloc = "x_local_px",
  yloc = "y_local_px",
  keepMultiPol = TRUE,
  verbose = FALSE
)

Arguments

Details

The function reads polygon data from the specified file and formats. It validates the polygons and handles both global and local coordinates if provided. If the file type is '"h5"', the function currently does not handle the data, as this part of the code is not implemented.

Value

An 'sf' object with the loaded and validated polygons.

Examples

example(readCosmxSPE)
polygons <- readPolygons(metadata(spe)$polygons)
polygons

Description

This function reads polygon data specific to CosMx technology.

Usage

readPolygonsCosmx(
  polygonsFile,
  type = c("csv", "parquet"),
  x = "x_global_px",
  y = "y_global_px",
  xloc = "x_local_px",
  yloc = "y_local_px",
  keepMultiPol = TRUE,
  verbose = FALSE
)

Arguments

Value

An 'sf' object containing the CosMx polygon data.

Examples

example(readCosmxSPE)
polygons <- readPolygonsCosmx(metadata(spe)$polygons)
polygons

Description

This function reads polygon data specific to MERFISH technology.

Usage

readPolygonsMerfish(
  polygons,
  type = c("parquet", "HDF5"),
  keepMultiPol = TRUE,
  hdf5pattern = "hdf5",
  zLev = 3L,
  zcolumn = "ZIndex",
  geometry = "Geometry",
  verbose = FALSE
)

Arguments

Value

An 'sf' object containing the MERFISH polygon data.

Examples

example(readMerfishSPE)
polygons <- readPolygonsMerfish(metadata(spe)$polygons, type="parquet")
polygons

Description

This function reads polygon data specific to Xenium technology.

Usage

readPolygonsXenium(
  polygonsFile,
  type = c("parquet", "csv"),
  x = "vertex_x",
  y = "vertex_y",
  keepMultiPol = TRUE,
  verbose = FALSE
)

Arguments

Value

An 'sf' object containing the Xenium polygon data.

Examples

example(readXeniumSPE)
polygons <- readPolygonsXenium(metadata(spe)$polygons, type="parquet")
polygons

Description

Creates a ['SpatialExperiment'] from an unzipped Xenium Output Bundle directory containing spatial gene expression data.

Usage

readXeniumSPE(
  dirName,
  sampleName = "sample01",
  type = c("HDF5", "sparse"),
  coordNames = c("x_centroid", "y_centroid"),
  boundariesType = c("parquet", "csv"),
  computeMissingMetrics = TRUE,
  keepPolygons = FALSE,
  countsFilePattern = "cell_feature_matrix",
  metadataFPattern = "cells.csv.gz",
  polygonsFPattern = "cell_boundaries",
  polygonsCol = "polygons",
  txPattern = "transcripts",
  addFOVs = FALSE
)

Arguments

Details

readXeniumSPE

Expects the unzipped bundle to contain an 'outs/' folder with: - 'cell_feature_matrix.h5' or 'cell_feature_matrix/' - 'cells.csv.gz'

Value

A ['SpatialExperiment'] object with assays, 'colData', spatial coordinates, and 'metadata$polygons' & 'metadata$technology'.

Author(s)

Dario Righelli, Benedetta Banzi

Examples

xepath <- system.file(
  "extdata", "Xenium_small", package = "SpaceTrooper"
)
(spe <- readXeniumSPE(
  dirName = xepath,
  keepPolygons = TRUE
))

Description

Computes quality‐control metrics for each cell and adds them to 'colData'.

Usage

spatialPerCellQC(
  spe,
  micronConvFact = 0.12,
  rmZeros = TRUE,
  negProbList = c("NegPrb", "Negative", "SystemControl", "Ms IgG1", "Rb IgG", "BLANK_",
    "NegControlProbe", "NegControlCodeword", "UnassignedCodeword", "Blank"),
  use_altexps = NULL
)

Arguments

Details

The function computes and appends per‑cell QC metrics to 'colData(spe)' and may subset the returned SpatialExperiment.

Key behaviours and expectations: - Feature detection: negative‑probe patterns supplied in 'negProbList' are used to build 'subsets_*' groups passed to 'scater::addPerCellQC()' (via 'use_altexps' when requested). 'addPerCellQC()' must be able to find matching feature names ('rownames' of spe) and will create 'subsets_*_sum' and 'subsets_*_detected' columns used below. - Required columns: the function expects 'sum', 'detected' and 'total' (from 'addPerCellQC()' and the SPE assays) to be present; these are used to compute 'control_sum', 'control_detected', 'target_sum' and 'target_detected.' - Control metrics: 'control_sum' and 'control_detected' are computed by summing matching 'subsets_*' columns; 'target_*' metrics are computed as the complement vs sum / detected. - Ratios and logs: 'ctrl_total_ratio' ('control' / 9) and its stabilized log2 transform 'log2Ctrl_total_ratio' are added. - Coordinate and area handling: - For CosMx technologies (Nanostring_CosMx and Nanostring_CosMx_Protein) spatial coordinates are converted from pixels to microns using 'micronConvFact' and appended to 'colData' (column names have px -> um). - For CosMx, 'Area_um' is derived from an existing Area column scaled by micronConvFact^2 and '.computeBorderDistanceCosMx()' is invoked to compute 'dist_border'. - For Nanostring_CosMx_Protein, a legacy 'Area.um2' column (if present) is renamed to 'Area_um' to standardize naming. - For Xenium (10X_Xenium), if 'Area_um' is missing the function will attempt to use 'cell_area' as a fallback and issue a warning. - Aspect ratio: if 'AspectRatio' exists it is logged ('log2AspectRatio'); if missing a warning is emitted. - Signal density: 'SignalDensity' is computed as 'sum' / 'Area_um' for most technologies; for Nanostring_CosMx_Protein it is set to total. A log transform 'log2SignalDensity' is also added. - Zero‑count removal: when 'rmZeros = TRUE' cells with 'sum == 0' are removed from the returned SpatialExperiment (message printed). - Side effects: the function modifies 'colData(spe)' (adds multiple new columns), may add spatial coordinates into 'colData' if missing, and may subset the SPE to remove zero‑count cells. It issues warnings when expected inputs (e.g. area, aspect ratio, polygon‑derived fields) are missing or when fallbacks are used.

Use this information to ensure the input SpatialExperiment contains the necessary assays and fields (feature names, 'sum'/'detected'/'total', 'Area'/'cell_area' when available) so metrics are computed and assigned correctly.

Value

A 'SpatialExperiment' object with added QC metrics in 'colData'.

Examples

example(readCosmxSPE)
spe <- spatialPerCellQC(spe)

Description

Fit a Ridge Logistic Regression Model

trainModel fits an L2-regularized (ridge) logistic regression using glmnet, given a design matrix and a training data frame.

Usage

trainModel(modelMatrix, trainDF)

Arguments

Value

A glmnet model object fitted with family="binomial", alpha=0 (ridge), and a sequence of $\lambda$ values.

Examples

example(computeTrainDF)
model_formula <- getModelFormula(metadata(spe)$formula_variables)
model_matrix <- model.matrix(as.formula(model_formula), data=df_train)
fit <- trainModel(model_matrix, df_train)
coef(fit, s = 0.01)

Description

Update a SpatialExperiment object corresponding to Nanostring CosMx Protein data by adding metadata identifying the technology and optionally passing through file-location parameters.

Usage

updateCosmxProteinSPE(
  spe,
  dirName,
  sampleName = "sample01",
  coordNames = c("CenterX_global_px", "CenterY_global_px"),
  countMatFPattern = "exprMat_file.csv",
  metadataFPattern = "metadata_file.csv",
  polygonsFPattern = "polygons.csv",
  fovPosFPattern = "fov_positions_file.csv",
  fovdims = c(xdim = 4256, ydim = 4256),
  keepPolygons = FALSE,
  polygonsCol = "polygons"
)

Arguments

Details

This function sets metadata(spe)$technology <- "Nanostring_CosMx_Protein". It does not modify other assay or metadata components.

Value

SpatialExperiment object with updated technology metadata.

See Also

readCosmxProteinSPE, readCosmxSPE

Examples

protfolder <- system.file( "extdata", "S01_prot", package="SpaceTrooper")
spe <- SpatialExperimentIO::readCosmxSXE(dirName=protfolder,
    addParquetPaths=FALSE)
spe <- updateCosmxProteinSPE(spe, protfolder, sampleName="cosmx_prots")

Description

Update a SpatialExperiment object derived from CosMx data by adding polygons, FOV dimensions, standardized column names, and metadata.

Usage

updateCosmxSPE(
  spe,
  dirName,
  sampleName = "sample01",
  polygonsFPattern = "polygons.csv",
  fovdims = c(xdim = 4256, ydim = 4256),
  keepPolygons = FALSE,
  polygonsCol = "polygons"
)

Arguments

Details

The function standardizes CosMx SPE structure by: - creating unique cell names of the form f<fov>_c<cell_ID>; - ensuring consistent cell identifiers and sample metadata; - recording FOV dimensions, polygon paths, and technology type in metadata(spe).

Value

A SpatialExperiment object with updated metadata and column names.

See Also

readCosmxSPE, readCosmxProteinSPE

Examples

cospath <- system.file(file.path("extdata", "CosMx_DBKero_Tiny"),
    package="SpaceTrooper")
spe <- SpatialExperimentIO::readCosmxSXE(dirName=cospath,
    addParquetPaths=FALSE)
spe <- updateCosmxSPE(spe, dirName=cospath, sampleName="DBKero_Tiny")

Description

Update a SpatialExperiment created from 10x Genomics Xenium outputs by wiring polygons/boundaries, computing optional QC metrics, and standardizing metadata and column names. This is a thin wrapper that delegates to the internal helper '.setupXeniumSPE()'.

Usage

updateXeniumSPE(
  spe,
  dirName,
  sampleName = "sample01",
  boundariesType = c("parquet", "csv"),
  computeMissingMetrics = TRUE,
  keepPolygons = FALSE,
  polygonsFPattern = "cell_boundaries",
  polygonsCol = "polygons",
  txPattern = "transcripts",
  addFOVs = FALSE
)

Arguments

Details

This function performs input checks and then calls '.setupXeniumSPE()', which does the heavy lifting (I/O, renaming, metadata updates, metrics).

Value

Updated SpatialExperiment object.

Examples

xepath <- system.file("extdata", "Xenium_small", package="SpaceTrooper")
(spe <- SpatialExperimentIO::readXeniumSXE(dirName=xepath))
spe <- updateXeniumSPE(spe, dirName=xepath, boundariesType="parquet",
    computeMissingMetrics=TRUE, keepPolygons=TRUE)