circust.robust_order

circust/robust_order.py

Etapa 4: Estimacion robusta del orden circular mediante K repeticiones aleatorias y seleccion/agregacion del orden final.

  1. Genera K subconjuntos aleatorios de genes TOP (tamaño configurable, por defecto 2/3 del total) con restricciones de cobertura circular y calidad parametrica.

  2. Para cada subconjunto k=1..K ejecuta:

    1. CPCA sobre la submatriz de genes seleccionada.

    2. Sincronizacion biologica (rotacion + orientacion).

    3. Re-ajuste FMM / Cosinor / NP a cada gen del TOP para obtener la tabla de estadisticos de 25 columnas.

  3. Selecciona el orden final mediante uno de dos metodos:

    • best_k: elige la repeticion k* que maximiza la mediana de R² (FMM) sobre un conjunto de evaluacion (genes core o genes de Ruben et al. 2018).

    • aggregate: agregacion circular de rangos segun Barragan et al. (2021) — combina enfoques TSP y Hodge para fusionar los K ordenes en un consenso.

Referencia

Barragan, S., Fernandez, M.A., Rueda, C. (2021). Circular rank aggregation: pairwise (TSP) and triplewise (Hodge) approaches. Journal of Statistical Planning and Inference, 213, 56-75.

Posicion en el pipeline

TopGeneSelector → RobustOrderEstimator → (Etapa 5)

class circust.robust_order.RobustOrderResult(sample_order, circular_scale, method_used, selected_rep=None, selection_score=None, sample_orders=<factory>, circular_scales=<factory>, direction_flipped=<factory>, stats_table=<factory>, per_rep_fmm_fit=<factory>, per_rep_cos_fit=<factory>, per_rep_np_fit=<factory>, median_r2_per_rep=<factory>, selection_names=<factory>, n_attempts=0, fallback_used=False, top_gene_names=<factory>)[source]

Bases: object

Salida de RobustOrderEstimator.

Atributos — orden final

sample_ordernp.ndarray int, forma (n_muestras,)

Orden de muestras final seleccionado (por best_k o agregacion).

circular_scalenp.ndarray, forma (n_muestras,)

Escala circular del orden final.

method_usedstr

“best_k” o “aggregate”.

selected_repint o None

Indice de la repeticion seleccionada (solo para best_k). None si method=”aggregate”.

selection_scorefloat o None

Mediana R² de la repeticion seleccionada (solo para best_k). None si method=”aggregate”.

Atributos — por repeticion

sample_ordersnp.ndarray int, forma (K, n_muestras)

Ordenes de muestras por repeticion.

circular_scalesnp.ndarray, forma (K, n_muestras)

Escalas circulares por repeticion.

direction_flippednp.ndarray bool, forma (K,)

Bandera de inversion de orientacion por repeticion.

stats_tablenp.ndarray, forma (K * n_top, 25)

Tabla apilada de estadisticos por gen y repeticion.

per_rep_fmm_fitlist de pd.DataFrame

Matrices FMM ajustadas por repeticion.

per_rep_cos_fitlist de pd.DataFrame

Matrices Cosinor ajustadas por repeticion.

per_rep_np_fitlist de pd.DataFrame

Matrices NP ajustadas por repeticion.

median_r2_per_repnp.ndarray, forma (K,)

Mediana R² sobre genes de evaluacion por repeticion.

Atributos — seleccion aleatoria

selection_namesnp.ndarray object, forma (K, tam)

Nombres de gen por extraccion.

n_attemptsint

Intentos totales de muestreo.

fallback_usedbool

True si se agoto el limite de intentos.

top_gene_nameslist[str]

Genes del TOP usados.

sample_order: ndarray
circular_scale: ndarray
method_used: str
selected_rep: int | None = None
selection_score: float | None = None
sample_orders: ndarray
circular_scales: ndarray
direction_flipped: ndarray
stats_table: ndarray
per_rep_fmm_fit: list
per_rep_cos_fit: list
per_rep_np_fit: list
median_r2_per_rep: ndarray
selection_names: ndarray
n_attempts: int = 0
fallback_used: bool = False
top_gene_names: list
summary()[source]
Return type:

str

Parameters:

  • sample_order (ndarray)

  • circular_scale (ndarray)

  • method_used (str)

  • selected_rep (int | None)

  • selection_score (float | None)

  • sample_orders (ndarray)

  • circular_scales (ndarray)

  • direction_flipped (ndarray)

  • stats_table (ndarray)

  • per_rep_fmm_fit (list)

  • per_rep_cos_fit (list)

  • per_rep_np_fit (list)

  • median_r2_per_rep (ndarray)

  • selection_names (ndarray)

  • n_attempts (int)

  • fallback_used (bool)

  • top_gene_names (list)

class circust.robust_order.RobustOrderEstimator(n_reps=5, sample_size_fraction=0.6666666666666666, method='best_k', r2_min=0.5, max_attempts=5000, anchor_gene='ARNTL', direction_gene='DBP', consistency_gene='CRY1', fmm_length_alpha_grid=48, fmm_length_omega_grid=24, fmm_num_reps=3, n_jobs=1, seed=None, verbose=True)[source]

Bases: object

Etapa 4 de CIRCUST: estimacion robusta del orden circular.

Unifica la seleccion aleatoria controlada de subconjuntos de genes TOP, la ejecucion de CPCA + sincronizacion por repeticion, y la seleccion del orden final.

Parameters:

  • n_reps (int) – Numero K de repeticiones aleatorias. Por defecto: 5.

  • sample_size_fraction (float) – Fraccion de genes TOP por extraccion. Por defecto: 2/3.

  • method (str) – Metodo de seleccion del orden final: - "best_k": elige la repeticion con mayor mediana R². - "aggregate": agregacion circular de rangos (Barragan et al.) (MEdiana circular de los ordenes).

  • r2_min (float) – R² parametrico minimo en cada extraccion. Por defecto: 0.5.

  • max_attempts (int) – Limite de intentos de muestreo. Por defecto: 5000.

  • anchor_gene (str) – Genes ancla para sincronizacion.

  • direction_gene (str) – Genes ancla para sincronizacion.

  • consistency_gene (str) – Genes ancla para sincronizacion.

  • fmm_length_alpha_grid (int) – Hiperparametros FMM.

  • fmm_length_omega_grid (int) – Hiperparametros FMM.

  • fmm_num_reps (int) – Hiperparametros FMM.

  • n_jobs (int) – Procesos CPU para ajuste paralelo de genes. -1 = todos.

  • seed (int | None) – Semilla para reproducibilidad.

  • verbose (bool) – Mensajes de progreso.

run(top_result, expr_full_norm, core_genes, eval_genes=None)[source]

Ejecuta la estimacion robusta completa.

Parameters:

  • top_result (TopGeneResult) – Salida de TopGeneSelector.run(). Debe tener los campos gene_names, fmm_peaks, r2_par, sector_labels, cosinor_peaks, circular_scale, added_genes, candidate_matrix.

  • expr_full_norm (DataFrame) – Matriz normalizada completa en el orden circular preliminar.

  • core_genes (list[str]) – Genes reloj centrales.

  • eval_genes (list[str] | None) – Genes de evaluacion para calcular mediana R² por repeticion. Si None, se usan los core_genes.

Return type:

RobustOrderResult