circust.top_genes

circust/top_genes.py

Etapa 3: Determinacion de genes TOP ritmicos especificos del tejido.

Implementa la seleccion de genes TOP segun la Seccion 3 de CIRCUST:

  1. Ajuste ORI: para cada gen, ajustar regresion isotonica circular unimodal (PAVA) y calcular R2_ORI = 1 - MSE_unimodal / MSE_plano.

  2. Filtro ORI: descartar genes con R2_ORI < 0.5 (ritmicidad no parametrica insuficiente).

  3. Filtro FMM: ajustar el modelo FMM a los supervivientes y seleccionar aquellos que sean (i) no puntiagudos (omega > 0.1), (ii) altamente ritmicos (R2_FMM > 0.5), (iii) picos (t_U) distribuidos en los 4 cuadrantes de [0, 2pi).

  4. Genes semilla forzados: los 12 genes reloj centrales se incluyen siempre; si alguno no paso los filtros, se fuerza su inclusion.

Posicion en el pipeline

CircularSynchronizer -> TopGeneSelector -> RandomSelector

-> RobustEstimator

circust.top_genes.circular_median(angles)[source]

Mediana circular: el angulo theta que minimiza sum d(theta, theta_i) donde d es la distancia geodesica en el circulo unitario.

Parameters:

angles (ndarray)

Return type:

float

circust.top_genes.assign_sectors(peaks, reference, n_sectors=8)[source]

Asigna cada angulo de pico a uno de n_sectors sectores equiespaciados centrados en reference.

Los sectores se numeran 1 … n_sectors.

Parameters:

  • peaks (ndarray)

  • reference (float)

  • n_sectors (int)

Return type:

ndarray

circust.top_genes.sector_boundaries(reference, n_sectors=8)[source]

Devuelve los n_sectors puntos centrales de sector.

Parameters:

  • reference (float)

  • n_sectors (int)

Return type:

ndarray

class circust.top_genes.TopGeneResult(gene_names=<factory>, fmm_peaks=<factory>, r2_par=<factory>, sector_labels=<factory>, sector_centres=<factory>, candidate_matrix=<factory>, cosinor_peaks=<factory>, circular_scale=<factory>, added_genes=<factory>, sample_order=<factory>, omega=<factory>, r2_ori=<factory>, n_total_genes=0, n_after_ori=0, n_after_fmm=0)[source]

Bases: object

Salida de TopGeneSelector.

Los campos principales son compatibles por duck-typing con ReferenceSetResult, de modo que RandomSelector puede consumir este resultado directamente.

Atributos — pipeline

gene_nameslist[str]

Simbolos de los genes TOP seleccionados.

fmm_peaksnp.ndarray (n_top,)

Tiempos de pico FMM (t_U) por gen.

r2_parnp.ndarray (n_top,)

R2 parametrico (FMM) por gen.

sector_labelsnp.ndarray int (n_top,)

Cuadrante asignado (1–4) por gen.

sector_centresnp.ndarray (n_sectors,)

Centros de los cuadrantes en [0, 2pi).

candidate_matrixpd.DataFrame (n_top, n_muestras)

Matriz de expresion de los genes TOP (en el orden circular preliminar). Equivale a [X_TOP] del paper.

cosinor_peaksnp.ndarray (n_top,)

Acrofases Cosinor de cada gen TOP.

circular_scalenp.ndarray (n_muestras,)

Eje temporal circular del ordenamiento preliminar.

added_geneslist[str]

Genes semilla que fueron forzados (no pasaron los filtros por si solos). Se excluyen del pool de muestreo aleatorio en RandomSelector.

sample_ordernp.ndarray int (n_muestras,)

Orden de muestras del sincronizado preliminar.

Atributos — diagnostico

omeganp.ndarray (n_top,)

Parametro omega de FMM por gen.

r2_orinp.ndarray (n_top,)

R2 ORI (no parametrico) de cada gen TOP.

n_total_genesint

Numero total de genes antes de cualquier filtro.

n_after_oriint

Genes que superaron el filtro R2_ORI >= umbral.

n_after_fmmint

Genes que superaron los filtros FMM (omega + R2_FMM) antes de forzar genes semilla.

gene_names: list
fmm_peaks: ndarray
r2_par: ndarray
sector_labels: ndarray
sector_centres: ndarray
candidate_matrix: DataFrame
cosinor_peaks: ndarray
circular_scale: ndarray
added_genes: list
sample_order: ndarray
omega: ndarray
r2_ori: ndarray
n_total_genes: int = 0
n_after_ori: int = 0
n_after_fmm: int = 0
summary()[source]
Return type:

str

Parameters:

  • gene_names (list)

  • fmm_peaks (ndarray)

  • r2_par (ndarray)

  • sector_labels (ndarray)

  • sector_centres (ndarray)

  • candidate_matrix (DataFrame)

  • cosinor_peaks (ndarray)

  • circular_scale (ndarray)

  • added_genes (list)

  • sample_order (ndarray)

  • omega (ndarray)

  • r2_ori (ndarray)

  • n_total_genes (int)

  • n_after_ori (int)

  • n_after_fmm (int)

class circust.top_genes.TopGeneSelector(r2_ori_threshold=0.5, r2_fmm_threshold=0.5, omega_min=0.1, n_sectors=4, fmm_length_alpha_grid=48, fmm_length_omega_grid=24, fmm_num_reps=3, n_jobs=-1, verbose=True)[source]

Bases: object

Selecciona los genes TOP ritmicos especificos del tejido.

Algoritmo (Seccion 3 del paper CIRCUST)

  1. Ajustar ORI a cada gen y calcular R2_ORI.

  2. Descartar genes con R2_ORI < r2_ori_threshold (0.5).

  3. Ajustar FMM a los supervivientes.

  4. Filtrar: omega > omega_min (0.1) Y R2_FMM > r2_fmm_threshold (0.5).

  5. Asignar picos FMM a n_sectors cuadrantes y verificar cobertura.

  6. Forzar inclusion de los genes core si no estan presentes.

  7. Construir la matriz TOP ([X_TOP] en el paper).

param r2_ori_threshold:

Umbral minimo de R2 ORI para el pre-filtro no parametrico. Paper: 0.5.

type r2_ori_threshold:

float

param r2_fmm_threshold:

Umbral minimo de R2 FMM para la ritmicidad parametrica. Paper: 0.5.

type r2_fmm_threshold:

float

param omega_min:

omega minimo de FMM; rechaza ajustes puntiagudos. Paper: 0.1.

type omega_min:

float

param n_sectors:

Numero de sectores circulares para verificar cobertura de picos. Paper: 4 (cuadrantes).

type n_sectors:

int

param fmm_length_alpha_grid:

Parametros de la rejilla de ajuste FMM.

type fmm_length_alpha_grid:

int

param fmm_length_omega_grid:

Parametros de la rejilla de ajuste FMM.

type fmm_length_omega_grid:

int

param fmm_num_reps:

Parametros de la rejilla de ajuste FMM.

type fmm_num_reps:

int

param n_jobs:

Numero de procesos para el ajuste en paralelo (ORI y FMM). -1 usa todos los nucleos disponibles.

type n_jobs:

int

param verbose:

Imprimir mensajes de progreso.

type verbose:

bool

run(expr_norm, circular_scale, seed_genes, sample_order=None)[source]

Selecciona los genes TOP.

Internamente ajusta ORI (regresion isotonica circular unimodal) a cada gen para calcular R2_ORI, aplica los filtros y construye el conjunto TOP.

Parameters:

  • expr_norm (DataFrame) – Matriz de expresion normalizada completa, ya ordenada por el tiempo circular preliminar.

  • circular_scale (ndarray) – Eje temporal circular del ordenamiento preliminar.

  • seed_genes (list[str]) – Genes core del pipeline (los mismos seleccionados por CoreGeneSelector). Se fuerzan en el conjunto TOP si no superan los filtros.

  • sample_order (ndarray | None) – Indices de muestra del ordenamiento preliminar. Si es None se asume identidad.

Return type:

TopGeneResult

Parameters:

  • r2_ori_threshold (float)

  • r2_fmm_threshold (float)

  • omega_min (float)

  • n_sectors (int)

  • fmm_length_alpha_grid (int)

  • fmm_length_omega_grid (int)

  • fmm_num_reps (int)

  • n_jobs (int)

  • verbose (bool)