circust.cpca

circust/cpca.py

Etapas 1.1 + 1.2: Ordenamiento circular (CPCA) y deteccion de outliers.

Que es CPCA

PCA sobre los 12(o mas) genes core del reloj. Los loadings de PC1 y PC2 de cada muestra se tratan como coordenadas (x, y) en el plano, el angulo(phi) se obtiene:

phi = atan2(PC2, PC1) en [0, 2pi)

Y su norma(LEi):

norm12 = sqrt(PC1² + PC2²)

da un ordenamiento circular que refleja el ritmo circadiano subyacente. Muestras cercanas al origen tienen norma pequena y son potenciales outliers.

Deteccion de outliers (Seccion 3.3 del paper suplementario de CIRCUST)

Dos criterios en logica OR una muestra se elimina si viola cualquiera:

  1. Radial CPCA: LEi < tight_radius (0.10) Muestras con distancia al origen en espacio PC1-PC2 muy pequena disrumpen la estructura circular y reflejan desalineaciones individuales.

  2. Residuos FMM: |ri| > fmm_threshold (3.0) para cualquier gen core Detecta errores de medicion u otras anomalias comunes entre genes.

Si se detectan outliers, se eliminan, se renormaliza la matriz core y se re-ejecuta CPCA para obtener el ordenamiento final limpio.

Posicion en el pipeline

Preprocessor -> CPCA -> CircularSynchronizer -> …

class circust.cpca.CPCAResult(sample_order, circular_scale, core_genes_found, variance_explained, expr_norm_final, core_norm_final, fmm_fits_final, fmm_peak_times_final, samples_dropped=<factory>, fmm_outliers=<factory>, pc1=<factory>, pc2=<factory>, pc3=<factory>, std_residuals_fmm=None, fmm_fits_initial=<factory>, cosinor_fits_initial=<factory>, pc1_initial=<factory>, pc2_initial=<factory>)[source]

Bases: object

Salida de CPCA — incluye el ordenamiento circular final y la deteccion de outliers (Etapas 1.1 + 1.2 del pipeline).

Campos del pipeline (usados por etapas posteriores)

sample_ordernp.ndarray de int, forma (n_muestras,)

Indices que ordenan las muestras por fase circular final.

circular_scalenp.ndarray de float, forma (n_muestras,)

Valores de phi ordenados en [0, 2pi). Eje temporal para ajustes.

core_genes_foundlist[str]

Genes centrales presentes en la matriz y usados para CPCA.

variance_explainednp.ndarray de float, forma (3,)

Fraccion de varianza explicada por PC1, PC2, PC3 (CPCA final).

expr_norm_finalpd.DataFrame, forma (n_genes, n_muestras_limpias)

Matriz de expresion completa con muestras outlier eliminadas, reordenada por fase circular y renormalizada.

core_norm_finalpd.DataFrame, forma (n_genes_core, n_muestras_limpias)

Submatriz core normalizada, sin outliers, ordenada por fase.

fmm_fits_finaldict[str, FitResult]

Ajustes FMM sobre genes core usando el ordenamiento final.

fmm_peak_times_finaldict[str, float]

Tiempos de pico FMM (via compUU) para cada gen core (final).

samples_droppedlist[int]

Indices originales de columna de las muestras eliminadas.

fmm_outlierslist[int]

Subconjunto de samples_dropped detectados exclusivamente por el criterio de residuos FMM (|ri| > fmm_threshold).

Campos de diagnostico (para visualizacion)

pc1, pc2, pc3np.ndarray

Loadings de PC1/PC2/PC3 del CPCA final (un valor por muestra).

std_residuals_fmmpd.DataFrame o None

Residuos FMM estandarizados (genes+PCs x muestras, orden inicial).

fmm_fits_initialdict[str, FitResult]

Ajustes FMM sobre genes core + PC1/PC2/PC3 en orden CPCA inicial.

cosinor_fits_initialdict[str, FitResult]

Ajustes Cosinor sobre genes core + PC1/PC2/PC3 en orden inicial.

sample_order: ndarray
circular_scale: ndarray
core_genes_found: list[str]
variance_explained: ndarray
expr_norm_final: DataFrame
core_norm_final: DataFrame
fmm_fits_final: dict
fmm_peak_times_final: dict
samples_dropped: list[int]
fmm_outliers: list[int]
pc1: ndarray
pc2: ndarray
pc3: ndarray
std_residuals_fmm: DataFrame | None = None
fmm_fits_initial: dict
cosinor_fits_initial: dict
pc1_initial: ndarray
pc2_initial: ndarray
summary()[source]
Return type:

str

Parameters:

  • sample_order (ndarray)

  • circular_scale (ndarray)

  • core_genes_found (list[str])

  • variance_explained (ndarray)

  • expr_norm_final (DataFrame)

  • core_norm_final (DataFrame)

  • fmm_fits_final (dict)

  • fmm_peak_times_final (dict)

  • samples_dropped (list[int])

  • fmm_outliers (list[int])

  • pc1 (ndarray)

  • pc2 (ndarray)

  • pc3 (ndarray)

  • std_residuals_fmm (DataFrame | None)

  • fmm_fits_initial (dict)

  • cosinor_fits_initial (dict)

  • pc1_initial (ndarray)

  • pc2_initial (ndarray)

class circust.cpca.CPCA(core_genes=None, n_outlier_candidates=8, tight_radius=0.1, loose_radius=0.15, fmm_threshold=3.0, max_outlier_fraction=0.05, fmm_length_alpha_grid=48, fmm_length_omega_grid=24, fmm_num_reps=3, verbose=True)[source]

Bases: object

Etapas 1.1 y 1.2: ordenamiento circular de muestras y deteccion de outliers residuales, segun la Seccion 3.3 del suplementario de CIRCUST.

Parametros — CPCA

core_geneslist[str], opcional

Genes ancla circadianos. Por defecto los 12 del articulo CIRCUST.

n_outlier_candidatesint

Muestras a examinar como candidatas a outlier (menor norma PC1-PC2). Por defecto: 8.

tight_radiusfloat

Umbral radial primario. Muestras con LEi <= tight_radius se confirman como outliers CPCA. Por defecto: 0.10.

loose_radiusfloat

Umbral de respaldo cuando ninguna muestra califica con tight_radius. Por defecto: 0.15.

Parametros — deteccion de outliers FMM

fmm_thresholdfloat

Umbral de residuo FMM estandarizado. Muestras con |ri| > fmm_threshold en cualquier gen core se declaran outliers. Por defecto: 3.0.

max_outlier_fractionfloat

Limite maximo de muestras eliminables: ceil(fraccion x n_muestras). Por defecto: 0.05.

Parametros — ajuste FMM

fmm_length_alpha_gridint

Resolucion de rejilla para el parametro alfa de FMM. Por defecto: 48.

fmm_length_omega_gridint

Resolucion de rejilla para el parametro omega de FMM. Por defecto: 24.

fmm_num_repsint

Iteraciones de refinamiento FMM. Por defecto: 3.

verbosebool

Imprimir mensajes de progreso.

Example

>>> from circust.preprocessing import load_expression_matrix, Preprocessor
>>> from circust.cpca import CPCA
>>>
>>> matrix = load_expression_matrix("data/raw/expression.csv")
>>> prep   = Preprocessor().run(matrix)
>>> result = CPCA().run(prep.expr_norm)
>>> print(result.summary())
run(expr_norm)[source]

Ejecuta CPCA + deteccion de outliers sobre la matriz completa.

Parameters:

expr_norm (DataFrame) – Matriz de expresion normalizada completa (valores en [-1, 1]). Es PreprocessingResult.expr_norm.

Return type:

CPCAResult

Parameters:

  • core_genes (list[str])

  • n_outlier_candidates (int)

  • tight_radius (float)

  • loose_radius (float)

  • fmm_threshold (float)

  • max_outlier_fraction (float)

  • fmm_length_alpha_grid (int)

  • fmm_length_omega_grid (int)

  • fmm_num_reps (int)

  • verbose (bool)