### Create aggregation CSV for spaceranger aggr

Source: https://context7.com/10xgenomics/spaceranger/llms.txt

Example of creating an aggregation CSV file required by `spaceranger aggr` to specify multiple samples for aggregation.

```bash
# Create aggregation CSV file first
cat > aggregation.csv << EOF
sample_id,molecule_h5,cloupe_file,spatial_folder
sample1,/path/to/sample1/outs/molecule_info.h5,/path/to/sample1/outs/cloupe.cloupe,/path/to/sample1/outs/spatial
sample2,/path/to/sample2/outs/molecule_info.h5,/path/to/sample2/outs/cloupe.cloupe,/path/to/sample2/outs/spatial
EOF
```

--------------------------------

### Manage FeatureReference metadata

Source: https://context7.com/10xgenomics/spaceranger/llms.txt

Define, query, and persist feature metadata including genes, antibodies, and CRISPR guides.

```python
from cellranger.feature_ref import FeatureReference, FeatureDef

# Create feature definitions
feature_defs = [
    FeatureDef(
        index=0,
        id=b'ENSG00000141510',
        name='TP53',
        feature_type='Gene Expression',
        tags={'genome': 'GRCh38'}
    ),
    FeatureDef(
        index=1,
        id=b'ENSG00000171862',
        name='PTEN',
        feature_type='Gene Expression',
        tags={'genome': 'GRCh38'}
    ),
]

# Create FeatureReference
feature_ref = FeatureReference(
    feature_defs=feature_defs,
    all_tag_keys=['genome']
)

# Query features
gex_indices = feature_ref.get_indices_for_type("Gene Expression")
gex_ids = feature_ref.get_feature_ids_by_type("Gene Expression")
genomes = feature_ref.get_genomes()

# Check for feature type
has_gex = feature_ref.has_feature_type("Gene Expression")
has_antibody = feature_ref.has_feature_type("Antibody Capture")

# Select features
gex_ref = feature_ref.select_features_by_type("Gene Expression")
subset_ref = feature_ref.select_features([0, 1, 5, 10])

# Join two feature references
combined_ref = FeatureReference.join(feature_ref1, feature_ref2)

# Add tags
feature_ref.add_tag("normalized", {"feature_id": "TRUE"}, default_tag_value="FALSE")

# Save/load from HDF5
import h5py
with h5py.File("/path/to/output.h5", "w") as f:
    group = f.create_group("features")
    feature_ref.to_hdf5(group)

with h5py.File("/path/to/matrix.h5", "r") as f:
    loaded_ref = FeatureReference.from_hdf5(f["features"])

# Export to CSV
with open("/path/to/features.csv", "w") as f:
    feature_ref.to_csv(f)
```

--------------------------------

### Get CountMatrix Properties

Source: https://context7.com/10xgenomics/spaceranger/llms.txt

Accessing basic properties of a loaded CountMatrix, such as dimensions, non-zero entries, and shape.

```python
# Get matrix dimensions and properties
print(f"Features: {matrix.features_dim}")
print(f"Barcodes: {matrix.bcs_dim}")
print(f"Non-zero entries: {matrix.get_num_nonzero()}")
print(f"Matrix shape: {matrix.get_shape()}")
```

--------------------------------

### Get Features Per Barcode

Source: https://context7.com/10xgenomics/spaceranger/llms.txt

Calculating the number of features detected per barcode using `get_numfeatures_per_bc`.

```python
# Get number of features detected per barcode
features_per_bc = matrix.get_numfeatures_per_bc()
```

--------------------------------

### Get CountMatrix Counts

Source: https://context7.com/10xgenomics/spaceranger/llms.txt

Obtaining counts per barcode and per feature from a CountMatrix.

```python
# Get counts per barcode and per feature
counts_per_bc = matrix.get_counts_per_bc()
counts_per_feature = matrix.get_counts_per_feature()
```

--------------------------------

### FeatureReference API

Source: https://context7.com/10xgenomics/spaceranger/llms.txt

The FeatureReference API manages metadata for features such as genes, antibodies, and CRISPR guides, supporting querying, selection, and serialization.

```APIDOC
## FeatureReference API

### Description
Manage feature metadata and definitions including indices, IDs, names, and feature types.

### Methods
- get_indices_for_type(feature_type)
- select_features_by_type(feature_type)
- to_hdf5(group)
- to_csv(file_handle)

### Parameters
#### Request Body
- **feature_defs** (list) - Required - List of FeatureDef objects.
- **all_tag_keys** (list) - Required - List of tag keys to include in the reference.
```

--------------------------------

### Run spaceranger mkfastq (Additional Options)

Source: https://context7.com/10xgenomics/spaceranger/llms.txt

Using `spaceranger mkfastq` with additional options for specifying local resources like cores and memory.

```bash
# With additional options
spaceranger mkfastq \
    --id=my_fastqs \
    --run=/path/to/flowcell \
    --samplesheet=/path/to/samplesheet.csv \
    --localcores=24 \
    --localmem=128
```

--------------------------------

### Run spaceranger mkfastq (Basic)

Source: https://context7.com/10xgenomics/spaceranger/llms.txt

Basic usage of `spaceranger mkfastq` to generate FASTQ files from BCL data using a samplesheet.

```bash
# Basic usage
spaceranger mkfastq \
    --id=my_fastqs \
    --run=/path/to/illumina/run \
    --csv=/path/to/samplesheet.csv
```

--------------------------------

### Run spaceranger aggr (With Normalization)

Source: https://context7.com/10xgenomics/spaceranger/llms.txt

Running `spaceranger aggr` to aggregate multiple samples with mapped normalization.

```bash
# Run aggregation
spaceranger aggr \
    --id=aggregated_output \
    --csv=aggregation.csv \
    --normalize=mapped
```

--------------------------------

### Run spaceranger count (Optional Parameters)

Source: https://context7.com/10xgenomics/spaceranger/llms.txt

Usage of `spaceranger count` with optional parameters for more control over the analysis, including sample naming and alignment details.

```bash
# With optional parameters
spaceranger count \
    --id=my_experiment \
    --transcriptome=/path/to/reference \
    --fastqs=/path/to/fastqs \
    --sample=MySample \
    --image=/path/to/image.jpg \
    --slide=V10J25-015 \
    --area=B1 \
    --loupe-alignment=/path/to/alignment.json \
    --nosecondary \
    --r1-length=28 \
    --r2-length=90 \
    --localcores=16 \
    --localmem=64
```

--------------------------------

### Run spaceranger count (Unknown Slide Mode)

Source: https://context7.com/10xgenomics/spaceranger/llms.txt

Using `spaceranger count` in unknown slide mode as a last resort when slide and area information is not available.

```bash
# Unknown slide mode (use as last resort)
spaceranger count \
    --id=unknown_slide_sample \
    --transcriptome=/path/to/reference \
    --fastqs=/path/to/fastqs \
    --image=/path/to/image.tif \
    --unknown-slide
```

--------------------------------

### Run spaceranger count (Basic)

Source: https://context7.com/10xgenomics/spaceranger/llms.txt

Basic usage of the `spaceranger count` command with required arguments for processing spatial gene expression data.

```bash
# Basic usage with required arguments
spaceranger count \
    --id=sample_output \
    --transcriptome=/path/to/refdata-gex-GRCh38-2020-A \
    --fastqs=/path/to/fastq_files \
    --image=/path/to/tissue_image.tif \
    --slide=V10J25-015 \
    --area=A1
```

--------------------------------

### Create CountMatrixView for efficient slicing

Source: https://context7.com/10xgenomics/spaceranger/llms.txt

Create memory-efficient views on matrices to perform slicing, summation, and thresholding without copying underlying data.

```python
from cellranger.matrix import CountMatrix

matrix = CountMatrix.load_h5_file("/path/to/matrix.h5")

# Create a view
view = matrix.view()

# Select features by type in the view
gex_view = view.select_features_by_type("Gene Expression")

# Select barcodes in the view
bc_view = view.select_barcodes([0, 1, 2, 3, 4])

# Compute sums efficiently over views
total_umis = view.sum()  # total UMIs across all barcodes/features
umis_per_bc = view.sum(axis=0)  # UMIs per barcode
umis_per_feature = view.sum(axis=1)  # UMIs per feature

# Count elements above threshold
cells_above_100 = view.count_ge(axis=0, threshold=100)

# Get shape and counts from view
view_shape = view.get_shape()
nnz = view.get_num_nonzero()
```

--------------------------------

### Run spaceranger aggr (No Normalization)

Source: https://context7.com/10xgenomics/spaceranger/llms.txt

Running `spaceranger aggr` without normalization, useful for specific downstream analyses.

```bash
# Without normalization
spaceranger aggr \
    --id=aggregated_no_norm \
    --csv=aggregation.csv \
    --normalize=none
```

--------------------------------

### Perform K-means and Graph-based Clustering

Source: https://context7.com/10xgenomics/spaceranger/llms.txt

Creates clustering objects from labels and manages cluster metadata. Relabeling by size ensures the largest cluster is indexed as 1.

```python
from cellranger.analysis.clustering import (
    CLUSTERING, create_clustering, relabel_by_size,
    format_clustering_key, humanify_clustering_key, save_clustering_csv
)
import numpy as np

# Create a clustering result
cluster_labels = np.array([1, 1, 2, 2, 3, 3, 1, 2, 3, 1])  # 1-based labels
clustering = create_clustering(
    clusters=cluster_labels,
    num_clusters=3,
    cluster_score=0.85,  # Silhouette score or similar metric
    clustering_type="kmeans",
    global_sort_key=3.0,  # For sorting multiple clusterings
    description="K-means with K=3"
)

# Relabel clusters by size (largest cluster becomes cluster 1)
relabeled = relabel_by_size(cluster_labels)

# Format clustering keys
key = format_clustering_key("kmeans", 5)  # "gene_expression_kmeans_5_clusters"
human_readable = humanify_clustering_key(key)  # "Gene Expression K-means (K=5)"

# Save clustering to CSV
barcodes = [b'AAACCTGAG-1', b'AAACCTGCA-1', b'AAACCTGGT-1']
save_clustering_csv("/path/to/output", "gene_expression_kmeans_3_clusters",
                    cluster_labels, barcodes)
```

--------------------------------

### Load CountMatrix from HDF5

Source: https://context7.com/10xgenomics/spaceranger/llms.txt

Loading a feature-barcode matrix from an HDF5 file using the `CountMatrix.load_h5_file` method.

```python
import numpy as np
from cellranger.matrix import CountMatrix

# Load matrix from HDF5 file
matrix = CountMatrix.load_h5_file("/path/to/filtered_feature_bc_matrix.h5")
```

--------------------------------

### Process and transform microscopy images

Source: https://context7.com/10xgenomics/spaceranger/llms.txt

Utilities for reading, normalizing, resizing, and preprocessing tissue images for spatial analysis.

```python
from cellranger.spatial.image_util import (
    normalized_image_from_counts, cv_read_image_standard,
    cv_read_rgb_image, shrink_to_max, preprocess_fl_channel,
    prepare_registration_target_image, get_tiff_pixel_size
)
import numpy as np

# Read images
grayscale_img = cv_read_image_standard("/path/to/tissue_image.tif")
rgb_img = cv_read_rgb_image("/path/to/tissue_image.jpg")

# Create normalized image from count data
counts = np.random.randint(0, 1000, size=(100, 100))
count_image = normalized_image_from_counts(
    counts,
    maxcount=500,
    log1p=True,  # Log transform
    invert=False
)

# Calculate scale factor for resizing
target_size = 2000
scale_factor = shrink_to_max(rgb_img.shape[:2], target_size)

# Preprocess fluorescence channel
fl_channel = np.random.randint(0, 65535, size=(1000, 1000), dtype=np.int16)
processed = preprocess_fl_channel(fl_channel, method="log")

# Prepare registration target image
scalef = prepare_registration_target_image(
    tissue_image_paths=["/path/to/tissue.tif"],
    dark_images=0,  # 0=brightfield, 1=fluorescence channels
    regist_target_im_max_dim=6000,
    save_to_path="/path/to/regist_target.png",
    skip_pages=set(),
    selected_pages=None
)

# Get pixel size from TIFF metadata (OME-compliant)
pixel_size_um = get_tiff_pixel_size("/path/to/microscope_image.tif")
if pixel_size_um:
    print(f"Pixel size: {pixel_size_um} microns")
```

--------------------------------

### Convert sparse matrices to dense CSV

Source: https://context7.com/10xgenomics/spaceranger/llms.txt

Load feature-barcode matrices from H5 or MEX formats and export them to dense CSV files. Note that dense CSVs can be extremely large.

```python
from cellranger.matrix import CountMatrix
from cellranger.mtx_to_matrix_converter import load_mtx, save_dense_csv
import pathlib

# Load from H5
matrix = CountMatrix.load_h5_file("/path/to/filtered_feature_bc_matrix.h5")

# Or load from MEX directory
matrix = load_mtx(pathlib.Path("/path/to/filtered_feature_bc_matrix/"))

# Select specific genome if multi-genome
genomes = matrix.get_genomes()
if len(genomes) > 1:
    matrix = matrix.select_features_by_genome("GRCh38")

# Check matrix size before conversion
num_features = matrix.features_dim
num_bcs = matrix.bcs_dim
dense_size = num_features * num_bcs
print(f"Matrix dimensions: {num_features} x {num_bcs}")
print(f"Dense matrix will have {dense_size:,} elements")

# Save as dense CSV (warning: can be very large!)
save_dense_csv(matrix, pathlib.Path("/path/to/output.csv"))
```

--------------------------------

### Cell Calling - EmptyDrops Algorithm

Source: https://context7.com/10xgenomics/spaceranger/llms.txt

Identify cell-containing barcodes versus empty droplets using the EmptyDrops algorithm.

```APIDOC
## Cell Calling - EmptyDrops Algorithm

### Description
Identify cell-containing barcodes vs empty droplets.

### Method
This is a programmatic interface. Functions like `find_nonambient_barcodes` and `est_background_profile_sgt` are used.

### Endpoint
N/A (Programmatic Interface)

### Parameters
#### Function: `find_nonambient_barcodes`
- **matrix** (CountMatrix) - Required - The raw feature-barcode matrix.
- **background_profile** (dict) - Required - Background noise profile, typically generated by `est_background_profile_sgt`.
- **min_umis** (int) - Optional - Minimum UMI count to be considered a cell.
- **alpha** (float) - Optional - Significance level for calling cells.

#### Function: `est_background_profile_sgt`
- **matrix** (CountMatrix) - Required - The raw feature-barcode matrix.

### Request Example
```python
from cellranger.cell_calling import (
    find_nonambient_barcodes, est_background_profile_sgt,
    NonAmbientBarcodeResult
)
from cellranger.matrix import CountMatrix
import numpy as np

# Load raw matrix
matrix = CountMatrix.load_h5_file("/path/to/raw_feature_bc_matrix.h5")
matrix.tocsc()

# Estimate background profile
background_profile = est_background_profile_sgt(matrix)

# Find non-ambient barcodes (cells)
cell_calling_result = find_nonambient_barcodes(
    matrix,
    background_profile,
    min_umis=1000,
    alpha=0.01
)

# Access results
cell_barcodes = cell_calling_result.cell_barcodes
non_cell_barcodes = cell_calling_result.non_cell_barcodes

# Initial cell calls (e.g., from basic UMI threshold)
umis_per_bc = matrix.get_counts_per_bc()
initial_cell_bcs = matrix.bcs[umis_per_bc > 500]
```

### Response
#### Success Response
- `find_nonambient_barcodes` returns a `NonAmbientBarcodeResult` object containing:
  - **cell_barcodes** (numpy.ndarray) - Barcodes identified as containing cells.
  - **non_cell_barcodes** (numpy.ndarray) - Barcodes identified as empty.
- `est_background_profile_sgt` returns a dictionary representing the background noise profile.
```

--------------------------------

### Select Top Barcodes

Source: https://context7.com/10xgenomics/spaceranger/llms.txt

Selecting the top barcodes based on UMI count using a specified cutoff, and creating a new matrix with these barcodes.

```python
# Select top barcodes by UMI count
top_bc_indices = matrix.get_top_bcs(cutoff=5000)
top_matrix = matrix.select_barcodes(top_bc_indices)
```

--------------------------------

### PCA - Principal Component Analysis

Source: https://context7.com/10xgenomics/spaceranger/llms.txt

Run PCA on feature-barcode matrices for dimensionality reduction. This tool helps in reducing the number of features while retaining important information for downstream analysis.

```APIDOC
## PCA - Principal Component Analysis

### Description
Run PCA on feature-barcode matrices for dimensionality reduction.

### Method
This is a programmatic interface, not a direct API endpoint. The `run_pca` function is used.

### Endpoint
N/A (Programmatic Interface)

### Parameters
#### Function: `run_pca`
- **matrix** (CountMatrix) - Required - The input feature-barcode matrix.
- **pca_features** (int or None) - Optional - Number of top highly variable features to use, or None to use all features.
- **pca_bcs** (int or None) - Optional - Number of barcodes to randomly sample, or None to use all barcodes.
- **n_pca_components** (int) - Optional - Number of principal components to compute. Defaults to 50.
- **random_state** (int) - Optional - Seed for random number generation for reproducibility.
- **min_count_threshold** (int) - Optional - Minimum UMI count threshold for features.

### Request Example
```python
from cellranger.analysis.pca import run_pca, save_pca_h5, save_pca_csv
from cellranger.matrix import CountMatrix

# Load matrix
matrix = CountMatrix.load_h5_file("/path/to/filtered_feature_bc_matrix.h5")

# Run PCA with default parameters
pca_result = run_pca(
    matrix,
    pca_features=None,  # Use all features
    pca_bcs=None,  # Use all barcodes
    n_pca_components=50,
    random_state=42,
    min_count_threshold=2
)
```

### Response
#### Success Response
The `run_pca` function returns a PCA result object containing:
- **transformed_pca_matrix** (numpy.ndarray) - The matrix with barcodes as rows and principal components as columns.
- **components** (numpy.ndarray) - The principal components (eigenvectors).
- **variance_explained** (numpy.ndarray) - The variance explained by each principal component.
- **dispersion** (numpy.ndarray) - Dispersion values for each feature.
- **features_selected** (list) - List of features used in PCA.

#### Response Example
```python
transformed_matrix = pca_result.transformed_pca_matrix  # (n_bcs, n_components)
components = pca_result.components  # (n_components, n_features)
variance_explained = pca_result.variance_explained  # (n_components,)
```

### Saving Results
- `save_pca_h5(pca_map, filename)`: Saves PCA results to an H5 file.
- `save_pca_csv(pca_map, matrix, output_dir)`: Saves PCA results to CSV files in the specified directory.
```

--------------------------------

### MoleculeCounter API

Source: https://context7.com/10xgenomics/spaceranger/llms.txt

The MoleculeCounter API allows for reading and processing molecule-level information from molecule_info.h5 files, including support for lazy loading and chunked processing.

```APIDOC
## MoleculeCounter API

### Description
Access and manipulate molecule-level information stored in molecule_info.h5 files.

### Methods
- open(path, mode)
- nrows()
- get_column_lazy(column_name)
- get_column(column_name)
- get_all_metrics()

### Parameters
#### Path Parameters
- **path** (string) - Required - Path to the molecule_info.h5 file.
- **mode** (string) - Required - File access mode (e.g., 'r').
```

--------------------------------

### Identify non-ambient barcodes with EmptyDrops

Source: https://context7.com/10xgenomics/spaceranger/llms.txt

Use EmptyDrops to identify additional cell barcodes beyond the initial set. Requires a matrix object and initial barcode list.

```python
result = find_nonambient_barcodes(
    matrix,
    orig_cell_bcs=initial_cell_bcs,
    chemistry_description="Single Cell 3' v3",
    num_probe_bcs=None,
    emptydrops_minimum_umis=500,
    num_sims=100000
)

if result is not None:
    # Access results
    eval_bcs = result.eval_bcs  # Evaluated barcode indices
    pvalues = result.pvalues_adj  # Adjusted p-values
    is_cell = result.is_nonambient  # Boolean array of cell calls

    # Get all cell barcodes
    additional_cells = matrix.bcs[eval_bcs[is_cell]]
    all_cells = np.concatenate([initial_cell_bcs, additional_cells])

    print(f"Initial cells: {len(initial_cell_bcs)}")
    print(f"Additional cells from EmptyDrops: {sum(is_cell)}")
```

--------------------------------

### Select Specific Barcodes by Sequence

Source: https://context7.com/10xgenomics/spaceranger/llms.txt

Selecting a subset of the CountMatrix based on a list of specific barcode sequences.

```python
# Select specific barcodes
barcode_seqs = [b'AAACCTGAGAAACCAT-1', b'AAACCTGAGAAACCTA-1']
subset = matrix.select_barcodes_by_seq(barcode_seqs)
```

--------------------------------

### Run PCA on Feature-Barcode Matrices

Source: https://context7.com/10xgenomics/spaceranger/llms.txt

Performs dimensionality reduction on count matrices. Requires a loaded CountMatrix object.

```python
from cellranger.analysis.pca import run_pca, save_pca_h5, save_pca_csv
from cellranger.matrix import CountMatrix

# Load matrix
matrix = CountMatrix.load_h5_file("/path/to/filtered_feature_bc_matrix.h5")

# Run PCA with default parameters
pca_result = run_pca(
    matrix,
    pca_features=None,  # Use all features
    pca_bcs=None,  # Use all barcodes
    n_pca_components=50,
    random_state=42,
    min_count_threshold=2
)

# Access PCA results
transformed_matrix = pca_result.transformed_pca_matrix  # (n_bcs, n_components)
components = pca_result.components  # (n_components, n_features)
variance_explained = pca_result.variance_explained  # (n_components,)
dispersion = pca_result.dispersion  # Feature dispersion values
features_selected = pca_result.features_selected  # Features used in PCA

# Run PCA with feature/barcode subsetting
pca_result = run_pca(
    matrix,
    pca_features=2000,  # Top 2000 highly variable features
    pca_bcs=5000,  # Random sample of 5000 barcodes
    n_pca_components=30,
    random_state=0
)

# Save results
pca_map = {50: pca_result}
save_pca_h5(pca_map, "/path/to/pca.h5")
save_pca_csv(pca_map, matrix, "/path/to/pca_output/")
```

--------------------------------

### Clustering - K-means and Graph-based Clustering

Source: https://context7.com/10xgenomics/spaceranger/llms.txt

Perform clustering analysis on reduced-dimension data. Supports K-means and other methods to group cells.

```APIDOC
## Clustering - K-means and Graph-based Clustering

### Description
Perform clustering analysis on reduced-dimension data.

### Method
This is a programmatic interface. Functions like `create_clustering`, `relabel_by_size`, `format_clustering_key`, `humanify_clustering_key`, and `save_clustering_csv` are used.

### Endpoint
N/A (Programmatic Interface)

### Parameters
#### Function: `create_clustering`
- **clusters** (numpy.ndarray) - Required - Array of cluster labels for each barcode.
- **num_clusters** (int) - Required - The total number of clusters.
- **cluster_score** (float) - Optional - A metric score for the clustering (e.g., silhouette score).
- **clustering_type** (str) - Optional - The type of clustering algorithm used (e.g., 'kmeans').
- **global_sort_key** (float) - Optional - A key for sorting multiple clusterings globally.
- **description** (str) - Optional - A textual description of the clustering.

#### Function: `relabel_by_size`
- **clusters** (numpy.ndarray) - Required - Array of cluster labels.

#### Function: `format_clustering_key`
- **clustering_type** (str) - Required - The type of clustering.
- **num_clusters** (int) - Required - The number of clusters.

#### Function: `humanify_clustering_key`
- **key** (str) - Required - The formatted clustering key.

#### Function: `save_clustering_csv`
- **output_dir** (str) - Required - Directory to save the CSV file.
- **clustering_key** (str) - Required - A unique key identifying the clustering.
- **cluster_labels** (numpy.ndarray) - Required - Array of cluster labels.
- **barcodes** (list) - Required - List of barcode sequences.

### Request Example
```python
from cellranger.analysis.clustering import (
    CLUSTERING, create_clustering, relabel_by_size,
    format_clustering_key, humanify_clustering_key, save_clustering_csv
)
import numpy as np

# Create a clustering result
cluster_labels = np.array([1, 1, 2, 2, 3, 3, 1, 2, 3, 1])  # 1-based labels
clustering = create_clustering(
    clusters=cluster_labels,
    num_clusters=3,
    cluster_score=0.85,  # Silhouette score or similar metric
    clustering_type="kmeans",
    global_sort_key=3.0,  # For sorting multiple clusterings
    description="K-means with K=3"
)

# Relabel clusters by size (largest cluster becomes cluster 1)
relabeled = relabel_by_size(cluster_labels)

# Format clustering keys
key = format_clustering_key("kmeans", 5)  # "gene_expression_kmeans_5_clusters"
human_readable = humanify_clustering_key(key)  # "Gene Expression K-means (K=5)"

# Save clustering to CSV
barcodes = [b'AAACCTGAG-1', b'AAACCTGCA-1', b'AAACCTGGT-1']
save_clustering_csv("/path/to/output", "gene_expression_kmeans_3_clusters",
                    cluster_labels, barcodes)
```

### Response
#### Success Response
- `create_clustering` returns a `CLUSTERING` object.
- `relabel_by_size` returns a numpy array of relabeled cluster IDs.
- `format_clustering_key` and `humanify_clustering_key` return formatted strings.
- `save_clustering_csv` saves a file and returns None.
```

--------------------------------

### Access MoleculeCounter data

Source: https://context7.com/10xgenomics/spaceranger/llms.txt

Read molecule-level information from molecule_info.h5 files, including lazy column access and chunked processing for large datasets.

```python
from cellranger.molecule_counter import MoleculeCounter

# Open for reading
with MoleculeCounter.open("/path/to/molecule_info.h5", "r") as mc:
    # Get basic information
    num_molecules = mc.nrows()
    genomes = mc.get_genomes()
    gem_groups = mc.get_gem_groups()
    library_info = mc.get_library_info()

    # Get filtered barcode count
    num_filtered_bcs = mc.get_num_filtered_barcodes()

    # Access columns lazily (returns h5py.Dataset)
    barcode_idx = mc.get_column_lazy("barcode_idx")
    feature_idx = mc.get_column_lazy("feature_idx")
    umi_counts = mc.get_column_lazy("count")

    # Load full column into memory
    all_umis = mc.get_column("umi")

    # Get barcodes
    barcodes = mc.get_barcodes()

    # Get feature reference
    feature_ref = mc.get_feature_ref()

    # Access metrics
    all_metrics = mc.get_all_metrics()
    chemistry = mc.get_metric("chemistry_description")

    # Check data type
    is_spatial = mc.is_spatial_data()
    is_aggregated = mc.is_aggregated()
    is_targeted = mc.is_targeted()

    # Get read counts per library
    raw_reads = mc.get_raw_read_pairs_per_library()
    usable_reads = mc.get_usable_read_pairs_per_library()

    # Get barcode info
    barcode_info = mc.get_barcode_info()
    filtered_bcs = MoleculeCounter.get_filtered_barcodes(
        barcode_info, library_info, barcodes, genome_idx=0
    )

# Process in chunks for large files
with MoleculeCounter.open("/path/to/molecule_info.h5", "r") as mc:
    for chunk_start, chunk_len in mc.get_chunks(target_chunk_len=1000000):
        bc_chunk = mc.get_column_lazy("barcode_idx")[chunk_start:chunk_start+chunk_len]
        # Process chunk...
```

--------------------------------

### CountMatrix Python API

Source: https://context7.com/10xgenomics/spaceranger/llms.txt

Interface for working with sparse feature-barcode matrices stored in HDF5 or MEX formats.

```APIDOC
## Class: CountMatrix

### Description
The CountMatrix class provides the primary interface for working with sparse feature-barcode matrices.

### Methods
- **load_h5_file(path)** - Load matrix from HDF5 file
- **get_num_nonzero()** - Returns number of non-zero entries
- **get_shape()** - Returns matrix dimensions
- **get_counts_per_bc()** - Returns counts per barcode
- **get_counts_per_feature()** - Returns counts per feature
- **select_barcodes(indices)** - Returns subset of matrix by barcode indices
- **select_features_by_type(type)** - Filters matrix by feature type
- **select_features_by_genome(genome)** - Filters matrix by genome
```

--------------------------------

### Register tissue images for spatial alignment

Source: https://context7.com/10xgenomics/spaceranger/llms.txt

Align microscopy images to CytAssist images using centroid estimation and iterative registration.

```python
from cellranger.spatial.tissue_regist import (
    estimate_tissue_position, get_centroid_alignment_transforms,
    register_from_init_transform, downsample_image, adjust_image_contrast
)
import cv2
import numpy as np

# Load images
target_img = cv2.imread("/path/to/microscope_image.png", cv2.IMREAD_GRAYSCALE)
cytassist_img = cv2.imread("/path/to/cytassist_image.png", cv2.IMREAD_GRAYSCALE)

# Downsample for faster processing
target_down, target_scale = downsample_image(target_img, maxres=2000)
cyta_down, cyta_scale = downsample_image(cytassist_img, maxres=2000)

# Adjust contrast
target_enhanced = adjust_image_contrast(
    target_down,
    method="adaptive",
    clip_limit=0.01,
    invert=True
)

# Estimate tissue position
area, centroid, bbox = estimate_tissue_position(
    target_img,
    qc_image_path="/path/to/qc_tissue_detection.png",
    maxsize=2000
)
print(f"Tissue area: {area}, centroid: {centroid}")

# Get initial alignment transforms
init_transforms = get_centroid_alignment_transforms(
    target_img,
    cytassist_img,
    pixel_size_target_to_cyta_ratio=1.0
)

# Register images
best_metric = np.inf
best_transform = None
for init_mat in init_transforms:
    transform, metric, status = register_from_init_transform(
        target_img,
        cytassist_img,
        np.array(init_mat),
        learning_rate=10.0
    )
    if metric < best_metric:
        best_metric = metric
        best_transform = transform

print(f"Best registration metric: {best_metric}")
print(f"Final transform:\n{best_transform}")
```

--------------------------------

### CountMatrix API

Source: https://context7.com/10xgenomics/spaceranger/llms.txt

The CountMatrix API provides methods for loading, selecting, and saving gene expression matrices, as well as creating memory-efficient views for data analysis.

```APIDOC
## CountMatrix Operations

### Description
Methods for loading matrices, selecting features by ID, and exporting data to HDF5 or MEX formats.

### Methods
- select_features_by_ids(feature_ids)
- save_h5_file(path, sw_version)
- save_mex(path, feature_tsv_func, compress)

### Parameters
#### Request Body
- **feature_ids** (list) - Required - List of byte-encoded feature IDs.
- **path** (string) - Required - File system path for output.
- **sw_version** (string) - Optional - Software version string for HDF5 metadata.
- **compress** (boolean) - Optional - Whether to compress the output MEX files.
```

--------------------------------

### Access CountMatrix Barcodes and Features

Source: https://context7.com/10xgenomics/spaceranger/llms.txt

Retrieving barcode sequences and feature identifiers/names from a CountMatrix object.

```python
# Access barcodes and features
barcodes = matrix.bcs  # numpy array of barcode sequences
feature_ids = [f.id for f in matrix.feature_ref.feature_defs]
feature_names = [f.name for f in matrix.feature_ref.feature_defs]
```

--------------------------------

### Compute Differential Expression with sSeq

Source: https://context7.com/10xgenomics/spaceranger/llms.txt

Calculates differential expression between barcode groups. Requires the matrix to be in CSC format.

```python
from cellranger.analysis.diffexp import (
    compute_sseq_params, sseq_differential_expression,
    run_differential_expression, adjust_pvalue_bh,
    save_differential_expression_csv
)
from cellranger.matrix import CountMatrix
import numpy as np

# Load matrix
matrix = CountMatrix.load_h5_file("/path/to/filtered_feature_bc_matrix.h5")
matrix.tocsc()  # Ensure CSC format

# Compute global sSeq parameters
sseq_params = compute_sseq_params(matrix.m)

# Run pairwise differential expression
cluster1_indices = np.array([0, 1, 2, 3, 4])  # Barcode indices in cluster 1
cluster2_indices = np.array([5, 6, 7, 8, 9])  # Barcode indices in cluster 2

de_result = sseq_differential_expression(
    matrix.m,
    cluster1_indices,
    cluster2_indices,
    sseq_params
)

# Access results
print(de_result.columns)  # ['tested', 'sum_a', 'sum_b', 'common_mean',
                          #  'common_dispersion', 'norm_mean_a', 'norm_mean_b',
                          #  'p_value', 'adjusted_p_value', 'log2_fold_change']

# Filter significant genes
significant = de_result[de_result['adjusted_p_value'] < 0.05]
upregulated = significant[significant['log2_fold_change'] > 1]

# Run DE for all clusters vs rest
clusters = np.array([1, 1, 1, 2, 2, 2, 3, 3, 3, 3])  # 1-based cluster labels
de_all = run_differential_expression(matrix, clusters, sseq_params)

# Save to CSV
save_differential_expression_csv(
    "gene_expression_kmeans_3_clusters",
    de_all,
    matrix,
    "/path/to/output/"
)

# Adjust p-values manually
raw_pvalues = np.array([0.001, 0.05, 0.01, 0.5])
adjusted = adjust_pvalue_bh(raw_pvalues)
```

--------------------------------

### Identify Cells with EmptyDrops

Source: https://context7.com/10xgenomics/spaceranger/llms.txt

Distinguishes cell-containing barcodes from background noise. Requires raw matrix input.

```python
from cellranger.cell_calling import (
    find_nonambient_barcodes, est_background_profile_sgt,
    NonAmbientBarcodeResult
)
from cellranger.matrix import CountMatrix
import numpy as np

# Load raw matrix
matrix = CountMatrix.load_h5_file("/path/to/raw_feature_bc_matrix.h5")
matrix.tocsc()

# Initial cell calls (e.g., from basic UMI threshold)
umis_per_bc = matrix.get_counts_per_bc()
initial_cell_bcs = matrix.bcs[umis_per_bc > 500]
```

--------------------------------

### spaceranger count

Source: https://context7.com/10xgenomics/spaceranger/llms.txt

Processes Visium spatial transcriptomics data by performing image alignment, read alignment, and UMI counting.

```APIDOC
## CLI Command: spaceranger count

### Description
The primary command for processing Visium spatial transcriptomics data. It performs image alignment, read alignment to a reference transcriptome, UMI counting, and generates feature-barcode matrices.

### Parameters
#### Required Arguments
- **--id** (string) - Unique output directory name
- **--transcriptome** (path) - Path to the reference transcriptome
- **--fastqs** (path) - Path to the FASTQ files
- **--image** (path) - Path to the tissue image file
- **--slide** (string) - Visium slide serial number
- **--area** (string) - Visium slide area identifier

#### Optional Arguments
- **--sample** (string) - Sample name
- **--loupe-alignment** (path) - Path to manual alignment JSON
- **--nosecondary** (flag) - Skip secondary analysis
- **--r1-length** (int) - Read 1 length
- **--r2-length** (int) - Read 2 length
- **--localcores** (int) - Number of cores to use
- **--localmem** (int) - Memory in GB to use
- **--unknown-slide** (flag) - Use if slide information is unavailable
```

--------------------------------

### spaceranger aggr

Source: https://context7.com/10xgenomics/spaceranger/llms.txt

Aggregates feature/spot count data from multiple spaceranger count runs into a combined dataset.

```APIDOC
## CLI Command: spaceranger aggr

### Description
Aggregates feature/spot count data from multiple spaceranger count runs into a combined dataset.

### Parameters
#### Required Arguments
- **--id** (string) - Unique output directory name
- **--csv** (path) - Path to the aggregation CSV file containing sample paths

#### Optional Arguments
- **--normalize** (string) - Normalization method (e.g., 'mapped', 'none')
```

--------------------------------

### Differential Expression - sSeq Method

Source: https://context7.com/10xgenomics/spaceranger/llms.txt

Compute differential gene expression between clusters or conditions using the sSeq method.

```APIDOC
## Differential Expression - sSeq Method

### Description
Compute differential gene expression between clusters or conditions.

### Method
This is a programmatic interface. Functions like `compute_sseq_params`, `sseq_differential_expression`, `run_differential_expression`, `adjust_pvalue_bh`, and `save_differential_expression_csv` are used.

### Endpoint
N/A (Programmatic Interface)

### Parameters
#### Function: `compute_sseq_params`
- **m** (scipy.sparse matrix) - Required - The count matrix (genes x barcodes).

#### Function: `sseq_differential_expression`
- **m** (scipy.sparse matrix) - Required - The count matrix (genes x barcodes).
- **cluster1_indices** (numpy.ndarray) - Required - Indices of barcodes in the first cluster.
- **cluster2_indices** (numpy.ndarray) - Required - Indices of barcodes in the second cluster.
- **sseq_params** (dict) - Required - Parameters computed by `compute_sseq_params`.

#### Function: `run_differential_expression`
- **matrix** (CountMatrix) - Required - The input feature-barcode matrix.
- **clusters** (numpy.ndarray) - Required - Array of cluster labels for each barcode.
- **sseq_params** (dict) - Required - Parameters computed by `compute_sseq_params`.

#### Function: `adjust_pvalue_bh`
- **raw_pvalues** (numpy.ndarray) - Required - Array of raw p-values.

#### Function: `save_differential_expression_csv`
- **clustering_key** (str) - Required - A key identifying the clustering.
- **de_result** (pandas.DataFrame) - Required - The differential expression results DataFrame.
- **matrix** (CountMatrix) - Required - The input feature-barcode matrix.
- **output_dir** (str) - Required - Directory to save the CSV file.

### Request Example
```python
from cellranger.analysis.diffexp import (
    compute_sseq_params, sseq_differential_expression,
    run_differential_expression, adjust_pvalue_bh,
    save_differential_expression_csv
)
from cellranger.matrix import CountMatrix
import numpy as np

# Load matrix
matrix = CountMatrix.load_h5_file("/path/to/filtered_feature_bc_matrix.h5")
matrix.tocsc()  # Ensure CSC format

# Compute global sSeq parameters
sseq_params = compute_sseq_params(matrix.m)

# Run pairwise differential expression
cluster1_indices = np.array([0, 1, 2, 3, 4])  # Barcode indices in cluster 1
cluster2_indices = np.array([5, 6, 7, 8, 9])  # Barcode indices in cluster 2

de_result = sseq_differential_expression(
    matrix.m,
    cluster1_indices,
    cluster2_indices,
    sseq_params
)

# Run DE for all clusters vs rest
clusters = np.array([1, 1, 1, 2, 2, 2, 3, 3, 3, 3])  # 1-based cluster labels
de_all = run_differential_expression(matrix, clusters, sseq_params)

# Save to CSV
save_differential_expression_csv(
    "gene_expression_kmeans_3_clusters",
    de_all,
    matrix,
    "/path/to/output/"
)

# Adjust p-values manually
raw_pvalues = np.array([0.001, 0.05, 0.01, 0.5])
adjusted = adjust_pvalue_bh(raw_pvalues)
```

### Response
#### Success Response
- `sseq_differential_expression` and `run_differential_expression` return a pandas DataFrame with differential expression statistics, including:
  - **tested** (str) - Gene name.
  - **sum_a** (float) - Sum of UMIs in cluster A.
  - **sum_b** (float) - Sum of UMIs in cluster B.
  - **common_mean** (float) - Common mean expression.
  - **common_dispersion** (float) - Common dispersion.
  - **norm_mean_a** (float) - Normalized mean expression in cluster A.
  - **norm_mean_b** (float) - Normalized mean expression in cluster B.
  - **p_value** (float) - Raw p-value.
  - **adjusted_p_value** (float) - Benjamini-Hochberg adjusted p-value.
  - **log2_fold_change** (float) - Log2 fold change.
- `adjust_pvalue_bh` returns a numpy array of adjusted p-values.
- `compute_sseq_params` returns a dictionary of parameters.
- `save_differential_expression_csv` saves a file and returns None.
```

--------------------------------

### Filter CountMatrix by Genome

Source: https://context7.com/10xgenomics/spaceranger/llms.txt

Filtering the CountMatrix to include features from a specific genome, useful for multi-genome references.

```python
# Filter by genome (for multi-genome references)
human_matrix = matrix.select_features_by_genome("GRCh38")
```

--------------------------------

### Filter CountMatrix by Feature Type

Source: https://context7.com/10xgenomics/spaceranger/llms.txt

Filtering the CountMatrix to include only features of a specific type, such as 'Gene Expression'.

```python
# Filter by feature type
gex_matrix = matrix.select_features_by_type("Gene Expression")
```

--------------------------------

### Manipulate CountMatrix data

Source: https://context7.com/10xgenomics/spaceranger/llms.txt

Perform feature selection and export operations on a CountMatrix object.

```python
feature_ids = [b'ENSG00000141510', b'ENSG00000171862']
subset = matrix.select_features_by_ids(feature_ids)

# Save to HDF5
matrix.save_h5_file("/path/to/output_matrix.h5", sw_version="spaceranger-3.1")

# Save to MEX format
from cellranger.rna.feature_ref import save_features_tsv
matrix.save_mex("/path/to/mex_output/", save_features_tsv, compress=True)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.