Differential Centrifugation (DC) Workflow#

grassp is a Python package that facilitates the analysis of subcellular proteomics data (with an emphasis on graph-based analyses).
In this tutorial, we analyze subcellular proteomics data produced by differential centrifugation (DC). Starting from a MaxQuant output table, we walk through reading the data, preprocessing and quality control, computing subcellular enrichment profiles, dimensionality reduction, and finally annotating the subcellular compartment of each protein.

If you have not installed grassp yet, please follow the installation instructions.

# grassp for the subcellular proteomics steps, scanpy for the shared single-cell toolkit
import grassp as gr
import scanpy as sc

# Data visualization
import seaborn as sns
import matplotlib.pyplot as plt

# Numerical computing and statistics
import numpy as np
/Users/mfrank/code/grassp/.venv-dev/lib/python3.12/site-packages/tqdm/auto.py:21: TqdmWarning: IProgress not found. Please update jupyter and ipywidgets. See https://ipywidgets.readthedocs.io/en/stable/user_install.html
  from .autonotebook import tqdm as notebook_tqdm

Reading files#

We’ll load the count matrix into an AnnData object, a data structure that provides multiple compartments for storing annotations and various data representations.
For a comprehensive AnnData tutorial, refer to the Getting Started with AnnData guide.

# Grassp provides methods to read from common proteomics formats in the io module.
# Here we read a MaxQuant output file.
dc = gr.io.read_maxquant(
    "https://public.czbiohub.org/proteinxlocation/internal/proteinGroups.txt",
    intensity_column_prefixes=["LFQ intensity ", "MS/MS count "],
)

dc.var["subcellular_enrichment"] = dc.var_names.str.split("_").str[-1]
dc.var["subcellular_enrichment"] = dc.var["subcellular_enrichment"].replace(
    "cyt", "Cyt"
)

dc.var["biological_replicate"] = dc.var_names.str.split("_").str[0].str[-1]

The centrifugation data in this tutorial comes from the Leonetti and Elias labs at CZ Biohub SF (unpublished).
Centrifugation-based subcellular fractionation experiments separate cellular components by spinning samples at increasing speeds (1K, 3K, 5K, 12K, 24K, 80K × g) to partition organelles and subcellular structures based on their density and size, with the cytoplasmic fraction (Cyt) representing the final supernatant.

This approach differs from immunoprecipitation (IP) pull-downs, which use antibodies to specifically capture target proteins and their interacting partners.

Although we are loading in the data from our online data repository, grassp comes with several example datasets.
The commented-out lines below show how to load in these data, including arguments specifying raw or enriched data.

# example_load_raw = gr.datasets.hek_dc_2025(enrichment="raw")
# example_load_enr = gr.datasets.hek_dc_2025(enrichment="enriched")
# print information about the loaded dataset
dc
AnnData object with n_obs × n_vars = 10224 × 42
    obs: 'Protein IDs', 'Majority protein IDs', 'Peptide counts (all)', 'Peptide counts (razor+unique)', 'Peptide counts (unique)', 'Protein names', 'Gene names', 'Fasta headers', 'Number of proteins', 'Peptides', 'Razor + unique peptides', 'Unique peptides', 'Sequence coverage [%]', 'Unique + razor sequence coverage [%]', 'Unique sequence coverage [%]', 'Mol. weight [kDa]', 'Sequence length', 'Sequence lengths', 'Fraction average', 'Fraction 1', 'Fraction 2', 'Fraction 3', 'Q-value', 'Score', 'Intensity', 'iBAQ', 'MS/MS count', 'Only identified by site', 'Reverse', 'Potential contaminant', 'id', 'Peptide IDs', 'Peptide is razor', 'Mod. peptide IDs', 'Evidence IDs', 'MS/MS IDs', 'Best MS/MS', 'Oxidation (M) site IDs', 'Oxidation (M) site positions'
    var: 'subcellular_enrichment', 'biological_replicate'
    uns: 'RawInfo'
    layers: 'MS_MS count'

Let’s go through the information printed above:

n_obs is the number of observations (i.e. proteins in this tutorial)
n_vars is the number of variables (i.e. spin-fractions/pulldowns in this tutorial)
Please note that in single-cell RNA-seq datasets, observations correspond to individual cells, and variables correspond to genes (or transcripts).

Under obs we find the metadata for the proteins, where each entry is a column in a pandas DataFrame. Reading a MaxQuant file carries over every protein-level column of proteinGroups.txt, so you will find identifiers (Protein IDs, Gene names, Protein names), search-engine statistics (Score, Q-value, peptide counts, sequence coverage) and the decoy/contaminant flags (Only identified by site, Reverse, Potential contaminant) that we use for filtering below.

Under var we find the metadata for the fractions/pulldowns, which so far holds the two columns we derived from the sample names above: subcellular_enrichment and biological_replicate.

Preprocessing#

Adding Compartment Annotations#

We add ground-truth subcellular compartment annotations.

gr.pp.add_markers(dc, species="hsap")

# add_markers adds one column per published marker set available for the species.
# Show a slice of just those columns to see what was added.
dc.obs.filter(like="marker_").iloc[20:30]
Added marker_lilley annotations for 333/10224 proteins (3.3%)
Added marker_christopher annotations for 658/10224 proteins (6.4%)
Added marker_geladaki annotations for 277/10224 proteins (2.7%)
Added marker_itzhak annotations for 429/10224 proteins (4.2%)
Added marker_villaneuva annotations for 289/10224 proteins (2.8%)
Added marker_hein2025 annotations for 2682/10224 proteins (26.2%)
Added marker_hein2025_gt annotations for 861/10224 proteins (8.4%)
marker_lilley marker_christopher marker_geladaki marker_itzhak marker_villaneuva marker_hein2025 marker_hein2025_gt
Protein IDs
A0PJZ3 NaN NaN NaN NaN NaN NaN NaN
A0PK00 NaN NaN NaN NaN NaN ER NaN
A1A4S6 NaN NaN NaN NaN NaN Recycling endosome NaN
A1A5B4-3;A1A5B4 NaN NaN NaN NaN NaN NaN NaN
A1A5C7;A1A5C7-4;A1A5C7-3;A1A5C7-2 NaN NaN NaN NaN NaN NaN NaN
A1KXE4-2;A1KXE4 NaN NaN NaN NaN NaN NaN NaN
A1L020 NaN NaN NaN NaN NaN Stress granule NaN
A1L0T0 NaN ER NaN NaN NaN ER ER
A1L170;A1L170-2 NaN NaN NaN NaN NaN NaN NaN
A1L188 NaN NaN NaN NaN NaN NaN NaN

Adding QC metrics to the metadata#

Before performing filtering and transformations, let’s compute quality control metrics for the raw data and add them to the metadata, which we can plot later on.

gr.pp.calculate_qc_metrics(dc)

Filtering#

# make a copy of the original data
dc_filtered = dc.copy()

grassp.pp provides filtering functions to remove low-quality proteins (pp stands for preprocessing).
Here, we filter out proteins that were annotated as contaminants by MaxQuant and then remove proteins that were not at least detected in 2/6 fractions for 4/6 replicates.

print("Protein count before filtering: ", dc_filtered.shape[0])

contaminant_cols = ["Only identified by site", "Reverse", "Potential contaminant"]
gr.pp.remove_contaminants(dc_filtered, filter_columns=contaminant_cols, filter_value="+")
dc_filtered.obs.drop(
    columns=contaminant_cols,
    inplace=True,
)
print("Protein count after contaminant filtering: ", dc_filtered.shape[0])

gr.pp.filter_proteins_per_replicate(
    dc_filtered,
    grouping_columns="subcellular_enrichment",
    min_replicates=4,
    min_samples=2,
)
print("Protein count after replicate filtering: ", dc_filtered.shape[0])
Protein count before filtering:  10224
Protein count after contaminant filtering:  9605
Protein count after replicate filtering:  8599

Transformations#

Normalization (log1p transformation)#

Methods like PCA work best when features are on comparable scales and extreme skew/outliers are reduced. Because protein count/abundance data are typically right-skewed with variance that increases with the mean, we apply a log1p transformation (log(1 + x)) to compress the dynamic range, reduce skewness, and stabilize variance before PCA and downstream visualization.

dc_filtered.layers["raw_intensities"] = dc_filtered.X.copy()
print(f"DC data before log transforming {dc_filtered.X[:10, :5]}")

dc_filtered.X = np.log1p(dc_filtered.X)
print(f"DC data after log transforming {dc_filtered.X[:10, :5]}")
dc_filtered.layers["log_intensities"] = dc_filtered.X.copy()
DC data before log transforming [[7.4430e+07 6.2590e+08 2.6638e+08 1.0273e+07 0.0000e+00]
 [6.6941e+09 3.1782e+10 1.3537e+10 1.6039e+09 1.3146e+08]
 [9.1884e+07 8.7600e+08 3.3295e+08 4.0916e+07 0.0000e+00]
 [8.7687e+07 1.2499e+08 6.8571e+07 2.1352e+08 5.4010e+08]
 [1.7278e+08 5.0152e+07 3.2616e+07 3.2176e+07 5.8874e+07]
 [1.1557e+08 7.7588e+08 3.3768e+08 0.0000e+00 0.0000e+00]
 [3.0980e+07 3.7040e+07 0.0000e+00 2.3960e+07 0.0000e+00]
 [3.4632e+07 0.0000e+00 1.4594e+07 1.4703e+08 3.2308e+08]
 [2.2813e+08 1.8855e+08 2.8589e+08 5.1585e+08 8.2965e+08]
 [0.0000e+00 2.0237e+07 5.8801e+07 5.3140e+07 2.3226e+07]]
DC data after log transforming [[18.12537  20.254702 19.400434 16.14503   0.      ]
 [22.624493 24.182165 23.328693 21.195704 18.694214]
 [18.336037 20.590878 19.623503 17.52703   0.      ]
 [18.289284 18.643744 18.04338  19.179241 20.107265]
 [18.96753  17.73057  17.300314 17.286732 17.89091 ]
 [18.565388 20.46951  19.63761   0.        0.      ]
 [17.248852 17.42751   0.       16.991896  0.      ]
 [17.360289  0.       16.49612  18.806147 19.59341 ]
 [19.245426 19.054874 19.471117 20.061327 20.536514]
 [ 0.       16.823023 17.88967  17.78844  16.960783]]

Imputing#

Mass spectrometry data often contain missing values because proteins with low abundance can fall below the instrument’s detection/identification threshold and therefore are not quantified in some runs.

Imputation mitigates this technical missingness by replacing absent entries with plausible values, enabling downstream analyses that require complete matrices (e.g., PCA, clustering, differential testing). In this workflow, grassp uses a left-shifted Gaussian approach (i.e., sampling small values from a distribution shifted toward low intensities) to reflect values likely below the detection limit, though alternative imputation methods can be selected depending on the dataset and assumptions.

gr.pp.impute_gaussian(dc_filtered, distance=1.8)
print(f"DC data after imputation {dc_filtered.X[:10, :5]}")
DC data after imputation [[18.12537  20.254702 19.400434 16.14503  17.036026]
 [22.624493 24.182165 23.328693 21.195704 18.694214]
 [18.336037 20.590878 19.623503 17.52703  15.066371]
 [18.289284 18.643744 18.04338  19.179241 20.107265]
 [18.96753  17.73057  17.300314 17.286732 17.89091 ]
 [18.565388 20.46951  19.63761  15.883985 15.151039]
 [17.248852 17.42751  16.670912 16.991896 15.297741]
 [17.360289 16.816336 16.49612  18.806147 19.59341 ]
 [19.245426 19.054874 19.471117 20.061327 20.536514]
 [16.216951 16.823023 17.88967  17.78844  16.960783]]

Plotting histogram of data distribution before vs. after imputation

plt.hist(
    dc_filtered.layers["log_intensities"].flatten(),  # .flatten() gives a 1D array
    bins=100,
    alpha=0.5,
    label="Before imputation",
)
plt.hist(dc_filtered.X.flatten(), bins=100, alpha=0.5, label="After imputation")
plt.xlabel("log1p intensity")
plt.ylabel("Number of values")
plt.title("Intensity distribution before vs. after imputation")
plt.legend()
plt.show()
../../_images/ea81651359f1ef53c8878ee14ef956433a65e9be189d1826d53541354af18d26.png

QC plotting#

Plotting transposed PCA to check sample clustering#

In subcellular proteomics, PCA is often performed with proteins as observations to study protein–protein relationships and subcellular structure. For quality control, however, we want to assess relationships between samples (runs/conditions/replicates).

Running PCA on the transposed matrix (tPCA) treats samples as observations and proteins as features, allowing us to visualize sample-to-sample similarity and confirm that biological replicates cluster together (and that any batch effects or outliers are identifiable).

dc_T = dc_filtered.T.copy()
dc_T.X = dc_filtered.layers["log_intensities"].T

sc.pp.pca(dc_T)
sc.pl.pca(dc_T, color="subcellular_enrichment", palette="cividis")
../../_images/97385dfa67188ae939ecc8c762ef41cace44454447f5c8cdd53399efb66cd85f.png

Violin plots of Log Intensities per Sample#

Plotting the distribution of protein intensities across each sample helps to identify any samples with unusual patterns or technical issues.
As expected, the later fractions and cytosolic supernatant have fewer proteins.

plot_df = dc_filtered.to_df(layer="log_intensities")

plt.figure(figsize=(20, 4))
sns.violinplot(plot_df, inner=None)
plt.xticks(rotation=90)
plt.title(label="Log1p Intensities per Sample")
plt.tight_layout()
plt.show()
../../_images/652962354ad75caae13f25ed1e12a270686469cf1b1526115f3b7d970643d944.png

Violin plot of QC metrics per Fraction#

In addition to sample-level qc, we can examine quality control metrics at the fraction level, revealing how protein detection rates, total intensities, and dropout percentages vary across different centrifugation speeds and compartments.

fig, axs = plt.subplots(1, 3, figsize=(28, 6))
for key, ax in zip(
    ["n_proteins_by_intensity", "log1p_total_intensity", "pct_dropout_by_intensity"],
    axs,
):
    sc.pl.violin(
        dc_T,
        key,
        groupby="subcellular_enrichment",
        size=4,
        rotation=90,
        ax=ax,
        show=False,
    )
../../_images/5b8c4dfae706d1f4d6a058628fb205c5b4336d2e7d8e208e844247b37d9c6358.png

Enrichment (Log fold change)#

Grassp provides functions to calculate enrichments. Grassp enrichment function offers two enrichment calculation methods:

  1. Log fold change (lfc) computes the difference between median intensities of the target sample versus all other samples in the same condition, providing a measure of how many times higher or lower protein levels are in the enriched fraction

  2. Proportion calculates the relative abundance as a fraction of total intensity across target and control samples, indicating what percentage of the protein’s total signal comes from the enriched condition

Here we chose the lfc transformation over proportions, because it produces a distribution of values that is closer to a normal distribution.

dc_filtered_enr = gr.pp.calculate_enrichment_vs_all(
    dc_filtered,
    subcellular_enrichment_column="subcellular_enrichment",
    covariates=["biological_replicate"],
    enrichment_method="lfc",
)

dc_filtered_enr = gr.pp.aggregate_samples(
    dc_filtered_enr, grouping_columns="subcellular_enrichment", agg_func=np.median
)

dc_filtered_enr
AnnData object with n_obs × n_vars = 8599 × 7
    obs: 'Protein IDs', 'Majority protein IDs', 'Peptide counts (all)', 'Peptide counts (razor+unique)', 'Peptide counts (unique)', 'Protein names', 'Gene names', 'Fasta headers', 'Number of proteins', 'Peptides', 'Razor + unique peptides', 'Unique peptides', 'Sequence coverage [%]', 'Unique + razor sequence coverage [%]', 'Unique sequence coverage [%]', 'Mol. weight [kDa]', 'Sequence length', 'Sequence lengths', 'Fraction average', 'Fraction 1', 'Fraction 2', 'Fraction 3', 'Q-value', 'Score', 'Intensity', 'iBAQ', 'MS/MS count', 'id', 'Peptide IDs', 'Peptide is razor', 'Mod. peptide IDs', 'Evidence IDs', 'MS/MS IDs', 'Best MS/MS', 'Oxidation (M) site IDs', 'Oxidation (M) site positions', 'marker_lilley', 'marker_christopher', 'marker_geladaki', 'marker_itzhak', 'marker_villaneuva', 'marker_hein2025', 'marker_hein2025_gt', 'n_samples_by_intensity', 'mean_intensity', 'log1p_mean_intensity', 'pct_dropout_by_intensity', 'total_intensity', 'log1p_total_intensity', 'n_imputed'
    var: 'subcellular_enrichment', 'n_merged_samples'
    uns: 'RawInfo', 'marker_lilley_colors', 'marker_christopher_colors', 'marker_geladaki_colors', 'marker_itzhak_colors', 'marker_villaneuva_colors', 'marker_hein2025_colors', 'marker_hein2025_gt_colors'
    layers: 'MS_MS count', 'raw_intensities', 'log_intensities', 'original_intensities', 'pvals'

Dimensionality Reduction#

PCA plots#

After filtering, transformation, and computing enrichment, we can move onto visualization and interpretation!
The following plots show how proteins cluster in reduced dimensional space based on their intensity patterns across samples, revealing groups of co-localized proteins and identifying potential subcellular localization signatures.

We first z-score the fractions with sc.pp.scale, so that fractions with a wide spread of enrichment values do not dominate the principal components purely because of their scale.

sc.pp.scale(dc_filtered_enr)
sc.pp.pca(dc_filtered_enr)
sc.pl.pca(
    dc_filtered_enr,
    color="marker_hein2025_gt",
    title="PCA plot with DC hein 2024 ground truth",
)
sc.pl.pca(
    dc_filtered_enr, color="marker_hein2025", 
    title="PCA plot with DC hein 2024 consensus annotation"
)
../../_images/8c65a1620f71aced423100af424d32fa0cc93af7345c960635985a57ad4ef52c.png ../../_images/b2ed85cd5270722a6013fff7a25bc63280ef01bd0661b97b6c208e2a104a1ad5.png

UMAPs#

While PCA provides a linear dimensionality reduction, UMAP offers a non-linear approach that can better preserve local neighborhood structures and reveal more complex patterns in protein localization data that might be missed by linear methods.

sc.pp.neighbors(dc_filtered_enr, use_rep="X", n_neighbors=20)
sc.tl.umap(dc_filtered_enr)
sc.pl.umap(
    dc_filtered_enr,
    color="marker_hein2025_gt",
    title="UMAP with DC hein 2024 ground truth",
)
sc.pl.umap(
    dc_filtered_enr, color="marker_hein2025", 
    title="UMAP with DC hein 2024 consensus annotation"
)
../../_images/fea2437de66255e07d305c39382bed0ea9a9af1d5706321623a5a2499695651e.png ../../_images/f6c4569cebf774a830a205978202409c78cbc9fda8b389a2c1f47577b6f8ac4d.png

Compartment Annotation#

A central goal of subcellular proteomics is to infer the cellular compartment (localization) of each observed protein. One common strategy is to start from a set of marker proteins with known localization and then transfer those labels to proteins with similar subcellular profiles.

In grassp, the competitive_diffusion function implements this approach by propagating compartment labels from marker proteins to nearby proteins in the protein–protein neighbor graph

gr.tl.competitive_diffusion(
    dc_filtered_enr, gt_col="marker_hein2025_gt", key_added="competitive_diffusion"
)

sc.pl.umap(dc_filtered_enr, color="competitive_diffusion", title="KNN Annotation")
../../_images/99714119ea320aea0c68abf7904149ef36a99a7e9fca79e8de603a93e73c1679.png

After these steps, the results of every analysis step are stored in the different AnnData slots. Note that n_vars has dropped from the 42 samples we started with to the 7 fractions of the map, because aggregate_samples collapsed the biological replicates of each fraction into a single median profile.

  • .obs — protein-level annotations: the propagated compartment label (competitive_diffusion) next to the marker columns and the QC metrics we computed earlier

  • .obsm — matrices with one row per protein: the PCA and UMAP coordinates (X_pca, X_umap) and the full compartment probabilities produced by competitive_diffusion

  • .obsp — protein–protein relationships: the distances and connectivities of the neighbor graph

  • .layers — alternative versions of the data matrix, such as the raw_intensities and log_intensities we stored while transforming

  • .uns — unstructured metadata: information about the file we read (RawInfo), the parameters of each step, and the colour palettes used for plotting

Print the object to see exactly which keys were added.

# print the resulting Anndata object
dc_filtered_enr
AnnData object with n_obs × n_vars = 8599 × 7
    obs: 'Protein IDs', 'Majority protein IDs', 'Peptide counts (all)', 'Peptide counts (razor+unique)', 'Peptide counts (unique)', 'Protein names', 'Gene names', 'Fasta headers', 'Number of proteins', 'Peptides', 'Razor + unique peptides', 'Unique peptides', 'Sequence coverage [%]', 'Unique + razor sequence coverage [%]', 'Unique sequence coverage [%]', 'Mol. weight [kDa]', 'Sequence length', 'Sequence lengths', 'Fraction average', 'Fraction 1', 'Fraction 2', 'Fraction 3', 'Q-value', 'Score', 'Intensity', 'iBAQ', 'MS/MS count', 'id', 'Peptide IDs', 'Peptide is razor', 'Mod. peptide IDs', 'Evidence IDs', 'MS/MS IDs', 'Best MS/MS', 'Oxidation (M) site IDs', 'Oxidation (M) site positions', 'marker_lilley', 'marker_christopher', 'marker_geladaki', 'marker_itzhak', 'marker_villaneuva', 'marker_hein2025', 'marker_hein2025_gt', 'n_samples_by_intensity', 'mean_intensity', 'log1p_mean_intensity', 'pct_dropout_by_intensity', 'total_intensity', 'log1p_total_intensity', 'n_imputed', 'competitive_diffusion', 'competitive_diffusion_probability'
    var: 'subcellular_enrichment', 'n_merged_samples', 'mean', 'std'
    uns: 'RawInfo', 'marker_lilley_colors', 'marker_christopher_colors', 'marker_geladaki_colors', 'marker_itzhak_colors', 'marker_villaneuva_colors', 'marker_hein2025_colors', 'marker_hein2025_gt_colors', 'pca', 'neighbors', 'umap', 'competitive_diffusion_params', 'competitive_diffusion_colors'
    obsm: 'X_pca', 'X_umap', 'competitive_diffusion_probabilities', 'competitive_diffusion_one_hot_labels'
    varm: 'PCs'
    layers: 'MS_MS count', 'raw_intensities', 'log_intensities', 'original_intensities', 'pvals'
    obsp: 'distances', 'connectivities'