Skip to content

1. Quickstart Guide

Jump to bottom
Eliezyer edited this page Mar 29, 2026 · 11 revisions

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

Clone this wiki locally