Usage Guide

Python Usage

Importing and Initializing gcPCA

To use gcPCA in Python, import the class and initialize the model:

from contrastive_methods import gcPCA
gcPCA_model = gcPCA(method='v4', normalize_flag=True)

• method options: 'v1', 'v2', 'v3', 'v4' (versions ending in .1, e.g. 'v4.1', return orthogonal components).
• normalize_flag: True → Automatically normalizes data (z-scoring and L2 normalization). False → Use this if you want to apply custom normalization.

Fitting the Model

Once initialized, fit the model to your datasets using:

gcPCA_model.fit(Ra, Rb)

Input Data Format

Ra (ma × p) and Rb (mb × p):
    Rows (ma, mb) → Samples from each condition.
    Columns (p) → Shared features (e.g., neurons, channels, RNA counts).

Output Attributes

After fitting, the following attributes will be available:

gcPCA_model.loadings_
gcPCA_model.gcPCA_values_
gcPCA_model.Ra_scores_
gcPCA_model.Rb_scores_
gcPCA_model.objective_values_

Description of Outputs

Attribute	Description
loadings_	Loadings for each gcPC. (Matrix: features × gcPCs)
gcPCA_values_	Objective values for each gcPC (vector).
Ra_scores_	Scores for dataset Ra in gcPC space (Matrix: ma × k).
Rb_scores_	Scores for dataset Rb in gcPC space (Matrix: mb × k).
objective_values_	Optimization values per gcPC (vector).

MATLAB Usage

Running gcPCA in MATLAB

The MATLAB implementation does not require any additional dependencies. To fit the model, use:

[B, S, X] = gcPCA(Ra, Rb, gcPCAversion)

Input Arguments

    Ra, Rb: The same matrices as used in Python.
    gcPCAversion: Can take values from 1 to 4 (.1 versions return orthogonal gcPCs).

Outputs

    B: Loadings for gcPCs.
    S: Scores for Ra and Rb.
    X: Additional model outputs.

📌 For further details, run:

help gcPCA

R Usage

Running gcPCA in R

To use gcPCA in R, load the package and fit the model:

library(gcpca)

fit <- gcPCA(Ra, Rb, method = "v4", Ncalc = 3)
pred <- predict(fit, Ra = Ra, Rb = Rb)

Input Arguments

• Ra, Rb — Numeric matrices with rows as samples and columns as shared features
• method — gcPCA version to use ("v1", "v2", "v3", "v4")
• Ncalc — Number of components to compute

Outputs

The fitted object fit stores the model parameters, and predict() returns the projected scores:

pred$Ra_scores
pred$Rb_scores

Common outputs include:

• pred$Ra_scores — Scores for dataset Ra in gcPC space
• pred$Rb_scores — Scores for dataset Rb in gcPC space

Helpful Functions

coef(fit)
summary(fit)

• coef(fit) — Extract gcPCA loadings
• summary(fit) — Display a summary of the fitted model

Example

library(gcpca)

set.seed(1)
Ra <- matrix(rnorm(40 * 5), ncol = 5)
Rb <- matrix(rnorm(35 * 5), ncol = 5)

fit <- gcPCA(Ra, Rb, method = "v4", Ncalc = 3)
pred <- predict(fit, Ra = Ra, Rb = Rb)

pred$Ra_scores
pred$Rb_scores

Notes

The Python, MATLAB, and R versions implement the same core algorithm but may have slight differences in numerical precision.

---

Links to Other Pages

2. Installation
3. Conceptual Overview
4. Mathematical Formulation
5. Code Reference
6. Input Data Guidelines
7. Interpreting Results