Usage Guide

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

Notes

The Python and MATLAB versions implement the same core algorithm but may have slight differences in numerical precision.
The R implementation is under development and will be available soon.