# API Reference

This page lists the public stGrads 2.0 functions. Arguments shown here are
the most important user-facing arguments; run `?function_name` in R for the
complete help page and defaults.

## Spatial pseudo-cells and transcriptomic aggregation

| Function | Main arguments | Returns | Description |
|---|---|---|---|
| `stg_spatial_pseudocells()` | `object`, `group_cols`, `cell_type_col`, `cell_types`, `assay`, `layer`, `grid_size`, `target_cells`, `min_cells`, `max_cells`, `seed`, `as_seurat` | List with `counts`, `metadata`, `cell_map`, `n_cells`, and optionally `object` | Aggregates spatially adjacent segmented units into pseudo-cells while preserving segment-level provenance. |
| `stg_pseudobulk()` | `object`, `group_cols`, `assay`, `layer`, `min_cells` | List with sparse counts and grouped metadata | Aggregates counts by metadata groups without using spatial coordinates. |
| `stg_normalize_counts()` | `counts`, `scale_factor`, `log1p` | Normalized matrix | Performs sparse-friendly library-size normalization. |
| `stg_marker_programs()` | `expression`, `gene_sets`, `min_genes` | Cell-by-program score matrix | Scores deterministic marker programs from one or more gene sets. |
| `stg_program_overlap()` | `program_a`, `program_b`, `method` | Numeric overlap score | Combines two marker-program scores, including the minimum fuzzy intersection. |

### `stg_spatial_pseudocells()` mapping output

The `cell_map` table has one row per retained original segment and includes:

| Column | Meaning |
|---|---|
| `CellID` | Original segmented-unit identifier. |
| `pseudocell_id` | Pseudo-cell receiving the segment. |
| `grid_id` | Sample-specific spatial grid identifier. |
| `grid_x`, `grid_y` | Integer spatial-grid coordinates. |
| `x`, `y` | Original segment centroid. |
| `group_cols` | Original sample or replicate identifiers. |
| `cell_type_col` | Original cell-type annotation, when supplied. |

The pseudo-cell-level `metadata` table contains `n_segments`,
`x_centroid`, `y_centroid`, `grid_x`, and `grid_y`. This makes it possible to
assign a CAF or NicheNet-related label to a pseudo-cell and project that label
back to every original segment.

## Spatial coordinates and gradients

| Function | Main arguments | Returns | Description |
|---|---|---|---|
| `stg_get_coordinates()` | `object`, `image`, `x_col`, `y_col`, `scale` | `CellID`, `x`, `y` data frame | Extracts coordinates from metadata, Seurat images, or segmentation boundaries. |
| `stg_coordinates()` | `coordinates`, `object`, `x_col`, `y_col` | Coordinate matrix | Standardizes coordinate input for spatial calculations. |
| `stg_spatial_gradient()` | `object`, `query`, `reference`, `radius`, `decay` | Cell-level gradient table | Computes spatial distance or decayed reference strength. |
| `stg_gradient_test()` | `gradient`, `expression`, `group`, `method` | Feature-level test table | Tests transcriptomic association with a spatial gradient. |
| `stg_decay()` | `distance`, `scale`, `model` | Numeric weights | Applies an exponential or user-defined spatial decay. |
| `stg_spatial_neighborhood()` | `object`, `cell_type_col`, `radius`, `group_cols` | Neighborhood counts and proportions | Quantifies local cell-type composition. |
| `stg_tumor_interface()` | `object`, `tumor_col`, `radius` | Interface distance table | Quantifies distance to a tumor or epithelial interface. |
| `stg_stromal_barrier()` | `object`, `stromal_col`, `radius` | Barrier proxy table | Summarizes stromal obstruction between spatial populations. |

## Morphology and segmentation

| Function | Main arguments | Returns | Description |
|---|---|---|---|
| `stg_morphology()` | `polygons`, `centroids`, `object` | Morphology table | Computes cell-area and shape descriptors from segmentation polygons. |
| `stg_add_morphology()` | `object`, `polygons`, `centroids` | Updated object or metadata | Adds morphology features to a spatial object. |
| `stg_combine_cell_nucleus()` | `cell_features`, `nucleus_features` | Combined morphology table | Combines cell and nuclear measurements. |
| `stg_morphology_qc()` | `morphology`, `thresholds` | QC table | Flags implausible or low-quality morphology. |
| `stg_morphology_atypia()` | `morphology`, `group_cols` | Atypia score table | Summarizes morphology deviations within a reference group. |
| `stg_prepare_hd_morphology()` | `object`, `polygons`, `nuclei` | Prepared morphology object | Standardizes polygon and nucleus inputs for Visium HD analysis. |

## RCTD mixed units and refinement

| Function | Main arguments | Returns | Description |
|---|---|---|---|
| `stg_annotate_rctd()` | `metadata`, `spot_class`, `first_type`, `second_type` | Normalized annotations | Standardizes RCTD singlet and mixed-unit labels. |
| `stg_canonical_pair()` | `type_a`, `type_b` | Canonical pair labels | Treats mixed pairs as undirected. |
| `stg_doublet_spatial_support()` | `metadata`, `coordinates`, `radius` | Support table | Tests whether both constituent singlet types occur nearby. |
| `stg_add_spatial_support()` | `object`, `metadata`, `coordinates`, `radius` | Updated metadata/object | Adds local support evidence to an object. |
| `stg_doublet_expression_residual()` | `counts`, `metadata`, `gene_sets` | Residual score table | Measures expression beyond expected constituent signals. |
| `stg_refine_doublets()` | `metadata`, `evidence`, `weights` | Ranked refinement table | Integrates spatial, morphology, and transcriptomic evidence. |
| `stg_classify_pair_display()` | `pair`, `observed`, `expected` | Display class | Labels enriched, depleted, zero-observed, or non-estimable pairs. |

## Pair enrichment

| Function | Main arguments | Returns | Description |
|---|---|---|---|
| `stg_pair_enrichment()` | `metadata`, `sample_col`, `condition_col`, `min_singlet_cells`, `min_expected` | ROI-level and condition-level tables | Computes conditional heterotypic observed-to-expected pair enrichment. |
| `stg_plot_pair_triangle()` | `enrichment`, `condition`, `value`, `show_counts` | ggplot object | Displays undirected pair enrichment as a triangular heatmap. |

The primary effect size is the unregularized ratio (O/E). The display-only
value for an observed zero may use a finite pseudocount so that the heatmap
can be colored, but the exact zero remains recorded in the output.

## Publication-oriented plotting

| Function | Main arguments | Returns | Description |
|---|---|---|---|
| `stg_theme_publication()` | `base_size`, `base_family` | ggplot theme | Provides a consistent publication-oriented theme. |
| `stg_plot_hd_he()` | `demo`, `image_path`, `alpha` | ggplot object | Displays cropped H&E context. |
| `stg_plot_polygon_class()` | `metadata`, `polygons`, `class_col` | ggplot object | Plots segmentation polygons by class. |
| `stg_plot_polygon_feature()` | `metadata`, `polygons`, `feature` | ggplot object | Maps a continuous feature onto polygons. |
| `stg_plot_doublet_map()` | `metadata`, `coordinates`, `pair` | ggplot object | Displays mixed units and spatial support. |
| `stg_plot_spatial_feature()` | `object`, `feature`, `coordinates` | ggplot object | Maps a feature across spatial coordinates. |

## Compatibility and data helpers

| Function | Main arguments | Returns | Description |
|---|---|---|---|
| `stg_layer_data()` | `object`, `assay`, `layer` | Matrix | Reads Seurat v5 layers or Seurat v4 slots. |
| `stg_upgrade_object()` | `object` | Updated object | Applies compatibility updates to older stGrads/Seurat objects. |
| `stg_format_hd_cell_id()` | `cell_ids`, `sample` | Character vector | Standardizes HD cell identifiers. |
| `stg_demo_image_path()` | `demo` | File path | Returns the packaged demo H&E image path. |
| `stg_read_hd_scalefactors()` | `path` | List | Reads HD scale-factor metadata. |

## Legacy API

The original stGrads 0.1.x functions remain available for old scripts and RDS
workflows. New analyses should use the `stg_*` functions above whenever an
equivalent function exists.

`FindPrimSpot()`, `CalcNearDis()`, `CalcNearDis_HD()`, `PlotNearDis()`,
`PlotStrengthDis()`, `PlotStrengthExpr()`, `PlotDisExpr()`, `PlotDisProp()`,
`CalcDRG()`, `PlotDRGs()`, `SeuLocation_StConvert()`, and
`calculate_distance()` are retained for backward compatibility.