circust.synchronizer

circust/synchronizer.py

Etapa 2: Sincronizacion del orden circular.

Objetivo

El ordenamiento circular derivado de CPCA es invariante a rotacion y tiene una direccion arbitraria (sentido horario o antihorario). Esta etapa corrige ambos problemas estableciendo un marco de referencia biologico.

Modalidades

mode="manual" (implementada)

Sincronizacion manual basada en genes ancla conocidos:

  • Un gen de referencia (anchor_gene, por defecto ARNTL) se coloca en π en la escala circular — su pico define el punto de arranque.

  • Un gen de direccion (direction_gene, por defecto DBP) determina la orientacion (CW vs CCW): si su pico cae en la mitad incorrecta se invierte.

  • Un gen de consistencia (consistency_gene, por defecto CRY1) participa en una verificacion de consistencia biologica refinada (Paso 2.2).

Paso 2.1 — Rotacion y determinacion de direccion:

  1. Rotar escala circular: peak(anchor) → π.

  2. Si (direction_peak − anchor_peak + π) mod 2π ≥ π → invertir.

  3. Reparametrizar ajustes FMM de genes core en el nuevo marco.

  4. Clasificar genes core como dia (pico ∈ [0, π)) o noche (pico ∈ [π, 2π)).

Paso 2.2 — Verificacion de consistencia biologica:

Si direction_gene esta demasiado cerca de 0 o π, o menos de la mitad de los genes sin anchor/direction tienen pico en [0, π), y el orden direction < consistency < anchor NO se cumple, entonces invertir.

mode="hybrid" (reservado para implementacion futura)

Sincronizacion hibrida in vivo / post mortem inspirada en el molecular timetable (Ueda et al., 2004; Higashi et al., 2016). Formula la alineacion como un problema de minimizacion en el circulo: busca la rotacion y orientacion que maximizan la concordancia entre los tiempos de pico estimados en el tejido objetivo (post mortem) y los tiempos de referencia procedentes de tejido in vivo con etiqueta temporal. Ver CircularSynchronizer._hybrid_sync() para la API prevista.

Posicion en el pipeline

OutlierRefiner → CircularSynchronizer → (Etapa 3)

class circust.synchronizer.SynchronizationResult(sample_order, circular_scale, expr_ordered, peak_times, r2_fmm, fmm_params, direction_flipped, within_group_indices, core_genes, day_genes=<factory>, night_genes=<factory>, pre_sample_order=<factory>, pre_circular_scale=<factory>, pre_expr_ordered=<factory>, pre_peak_times=<factory>, pre_fmm_params=<factory>, pre_direction_reversed=False)[source]

Bases: object

Salida combinada de la Etapa 2.

Variables:

  • sample_order (np.ndarray de int, forma (n_muestras,)) – Indices finales de muestra en la matriz de expresion limpia. Equivalente en R: basicOrdRefG2[[1]] (= indSin).

  • circular_scale (np.ndarray de float, forma (n_muestras,)) – Eje temporal circular en [0, 2π) tras correccion de direccion. Equivalente en R: basicOrdRefG2[[2]] (= escSincroRefG).

  • expr_ordered (pd.DataFrame, forma (n_genes, n_muestras)) – Matriz de expresion normalizada completa en el orden circular final. Equivalente en R: basicOrdRefG2[[3]] (= matNewNew).

  • peak_times (np.ndarray de float, forma (n_genes_core,)) – Tiempo de pico FMM para cada gen central en el marco de coordenadas final. Equivalente en R: basicOrdRefG2[[4]] (= peaksPreNew).

  • r2_fmm (np.ndarray de float, forma (n_genes_core,)) – R² del ajuste FMM para cada gen central. Equivalente en R: basicOrdRefG2[[5]].

  • fmm_params (np.ndarray de float, forma (n_genes_core, 5)) – Parametros FMM [M, A, α, β, ω] por gen central en el nuevo marco. Equivalente en R: basicOrdRefG2[[6]] (= pars).

  • direction_flipped (bool) – True si la direccion fue invertida (por el Paso 2.1 o 2.2). Equivalente en R: basicOrdRefG2[[7]] (= cambiaOri).

  • within_group_indices (np.ndarray de int, forma (n_muestras,)) – Indices posicionales base 0 dentro del grupo tras posible inversion. Equivalente en R: basicOrdRefG2[[8]] (= indNewNew).

  • core_genes (list[str]) – Simbolos de genes centrales en el orden utilizado.

  • day_genes (list[str]) – Genes centrales (exc. anchor y direction) con pico en [0, π).

  • night_genes (list[str]) – Genes centrales (exc. anchor y direction) con pico en [π, 2π).

  • pre_sample_order (np.ndarray de int) – Orden de muestras del Paso 2.1 (antes de la verificacion del Paso 2.2). Equivalente en R: preOrdRefG2[[1]].

  • pre_circular_scale (np.ndarray de float) – Escala circular del Paso 2.1. Equivalente en R: preOrdRefG2[[2]].

  • pre_expr_ordered (pd.DataFrame) – Matriz de expresion ordenada por el Paso 2.1. Equivalente en R: preOrdRefG2[[3]].

  • pre_peak_times (np.ndarray de float) – Tiempos de pico FMM del Paso 2.1. Equivalente en R: preOrdRefG2[[4]].

  • pre_fmm_params (np.ndarray de float, forma (n_genes_core, 5)) – Parametros FMM del Paso 2.1. Equivalente en R: preOrdRefG2[[6]] (= parCore).

  • pre_direction_reversed (bool) – True si el Paso 2.1 invirtio la direccion (direction_gene en la mitad incorrecta). Equivalente en R: preOrdRefG2[[13]] (= reverse).

Parameters:

  • sample_order (ndarray)

  • circular_scale (ndarray)

  • expr_ordered (DataFrame)

  • peak_times (ndarray)

  • r2_fmm (ndarray)

  • fmm_params (ndarray)

  • direction_flipped (bool)

  • within_group_indices (ndarray)

  • core_genes (list)

  • day_genes (list)

  • night_genes (list)

  • pre_sample_order (ndarray)

  • pre_circular_scale (ndarray)

  • pre_expr_ordered (DataFrame)

  • pre_peak_times (ndarray)

  • pre_fmm_params (ndarray)

  • pre_direction_reversed (bool)

sample_order: ndarray
circular_scale: ndarray
expr_ordered: DataFrame
peak_times: ndarray
r2_fmm: ndarray
fmm_params: ndarray
direction_flipped: bool
within_group_indices: ndarray
core_genes: list
day_genes: list
night_genes: list
pre_sample_order: ndarray
pre_circular_scale: ndarray
pre_expr_ordered: DataFrame
pre_peak_times: ndarray
pre_fmm_params: ndarray
pre_direction_reversed: bool = False
summary()[source]
Return type:

str

class circust.synchronizer.CircularSynchronizer(mode='manual', anchor_gene='ARNTL', direction_gene='DBP', consistency_gene='CRY1', verbose=True)[source]

Bases: object

Etapa 2 de CIRCUST: establece el marco de referencia biologico del ordenamiento circular.

Parameters:

  • mode (str) –

    Modalidad de sincronizacion. Opciones:

    "manual" (defecto)

    Sincronizacion basada en genes ancla con fases biologicamente conocidas. Requiere anchor_gene y direction_gene presentes en los genes core.

    "hybrid" (futuro)

    Sincronizacion hibrida in vivo/post mortem. Requiere reference_peaks en la llamada a run(). No implementada: lanza NotImplementedError.

  • anchor_gene (str) – Gen cuyo pico se coloca en π para definir el punto de arranque del ordenamiento. En el reloj mamifero, ARNTL tiene su pico cerca de la medianoche subjetiva (Zeitgeber 0). Por defecto: "ARNTL".

  • direction_gene (str) – Gen que determina la orientacion CW/CCW del ordenamiento. Se espera que su pico caiga en [0, π) (fase activa) tras la rotacion. Por defecto: "DBP".

  • consistency_gene (str) – Gen auxiliar usado en la verificacion de consistencia biologica del Paso 2.2. Se comprueba el orden direction < consistency < anchor. Por defecto: "CRY1".

  • verbose (bool) – Imprimir mensajes de progreso.

Example

>>> syncer = CircularSynchronizer()
>>> result = syncer.run(refined, core_genes)
>>> print(result.summary())
run(refined, core_genes, reference_peaks=None)[source]

Ejecuta la sincronizacion circular.

Parameters:

  • refined (CPCAResult) – Salida de CPCA.run().

  • core_genes (list[str]) – Lista ordenada de simbolos de genes reloj centrales.

  • reference_peaks (dict[str, float] | None) – Solo necesario para mode="hybrid". Tiempos de pico de referencia in vivo por gen (en [0, 2π)). Ignorado en modo manual.

Return type:

SynchronizationResult