circust.visualization¶

CPCA plots¶

circust/visualization/cpca_plots.py¶

Visualizaciones para la etapa CPCA del pipeline CIRCUST.

Dos gráficos, equivalentes a la salida de obtainCPCA12/13 (printing=TRUE) en R:

plot_pc_scatter(result)
Dispersión PC1 vs PC2 con resaltado de outliers y círculos de umbral. Equivalente a la primera ventana x11() en obtainCPCA12/13 de R.

plot_gene_panels(result)
Cuadrícula de trazas de expresión de genes reloj ordenadas por fase circular, más paneles de eigengenes PC1/PC2/PC3 al final. Equivalente a la segunda ventana x11() en obtainCPCA12/13 de R.

Ambas funciones devuelven una Figure de matplotlib para que el llamador pueda guardarlas, mostrarlas o integrarlas según necesite. Ninguna función llama a plt.show() — eso es responsabilidad del llamador.

Uso¶

from circust.cpca import CPCA from circust.plots.cpca_plots import plot_pc_scatter, plot_gene_panels

result = CPCA().run(expr_norm)

fig1 = plot_pc_scatter(result, title=”BA46 glutamatergic”) fig1.savefig(“cpca_scatter.png”, dpi=150, bbox_inches=”tight”)

fig2 = plot_gene_panels(result) fig2.savefig(“cpca_genes.png”, dpi=150, bbox_inches=”tight”)

circust.visualization.cpca_plots.plot_pc_scatter(result, title='', figsize=(7, 7), point_size=18, show_loose_circle=True)[source]¶

Diagrama de dispersión PC1 vs PC2 (un punto por muestra).

Características¶

Círculos umbral concéntricos discontinuos en r=0.10, 0.15, 0.20 (y 0.30 / 0.40 cuando los datos se extienden hasta ahí).
Candidatos a outlier marcados con cuadrados abiertos de colores distintos.
Los outliers confirmados llevan un marcador relleno encima.
El círculo de radio activo (ajustado=0.10, o holgado=0.15 si rojo8) se dibuja en rojo; el resto en gris.
Los límites de los ejes son simétricos y determinados por el rango de datos.
La varianza explicada se muestra en las etiquetas de los ejes.

Parámetros¶

resultCPCAResult: Salida de CPCA.run().
titlestr: Etiqueta de dataset/tejido mostrada en el título.
figsizetuple: Tamaño de la figura en pulgadas (ancho, alto).
point_sizefloat: Área del marcador para muestras normales (parámetro s de matplotlib).
show_loose_circlebool: Si se deben dibujar ambos círculos umbral aunque solo se usara el ajustado.

rtype:: Figure

Parameters:

title (str)
figsize (tuple[float, float])
point_size (float)
show_loose_circle (bool)

Return type:

Figure

circust.visualization.cpca_plots.plot_gene_panels(result, title='', figsize=None)[source]¶

Cuadrícula de trazas de expresión por gen reloj core, ordenadas por phi.

Disposición¶

Un subgráfico por gen core (expresión vs fase circular).
Tres subgráficos adicionales al final: trazas de eigengenes PC1, PC2, PC3.
Las muestras outlier se marcan con cuadrados abiertos coloreados en cada panel.
El tamaño de la cuadrícula es el cuadrado más pequeño que cabe todos los paneles.

Parámetros¶

resultCPCAResult: Debe haber sido producido por una instancia de CPCA que almacenó core_matrix (store_core_matrix=True, que es el valor por defecto).
titlestr: Etiqueta del suptítulo.
figsizetuple, opcional: Tamaño de la figura. Se calcula automáticamente de las dimensiones de la cuadrícula si no se proporciona.

rtype:: Figure
raises ValueError:: Si result.core_norm_final es None.

Parameters:

title (str)
figsize (tuple[float, float] | None)

Return type:

Figure

Order plots¶

circust/visualization/order_plots.py¶

Visualizaciones para la etapa de ordenación preliminar (Etapa 2).

Cuatro tipos de gráficos:

plot_circular_peaks(result)
Gráfico polar de los tiempos de pico FMM para cada gen reloj principal en un reloj de 24 horas. La visualización más emblemática de CIRCUST — muestra el programa temporal del reloj circadiano. Equivalente en R: peaksFMMCoresAfter_*.png, 12PeaksPre_*.png.

plot_ordered_profiles(result, expr)
Cuadrícula de perfiles de expresión de genes principales en el orden biológico final, con la curva del modelo FMM superpuesta. Muestra la forma de onda de cada gen tras el anclaje de ARNTL y la corrección de dirección. Equivalente en R: 12CorePre_*.png.

plot_r2_comparison(result)
Gráfico de barras horizontales del R² FMM para cada gen principal, codificado por color según la clasificación día/noche. Muestra rápidamente qué genes tienen ajustes rítmicos fuertes vs débiles.

plot_day_night_diagram(result)
Diagrama circular de sectores que divide el ciclo de 24 horas en día [0, π) y noche [π, 2π), con los nombres de los genes situados en sus posiciones de pico. Proporciona un resumen intuitivo de qué genes alcanzan su pico en cada fase biológica.

Todas las funciones devuelven una Figure de matplotlib. Ninguna llama a plt.show().

circust.visualization.order_plots.plot_circular_peaks(result, title='', figsize=(6, 6), show_ct_labels=True)[source]¶

Gráfico polar de los tiempos de pico FMM para cada gen reloj core.

Los genes se sitúan alrededor de un círculo en su fase de pico estimada. ARNTL está anclado en π (CT0/amanecer), y DBP aparece en la primera mitad [0, π) si la dirección es correcta.

Parámetros¶

resultSynchronizationResult: Salida de CircularSynchronizer.run().
titlestr: Etiqueta del título del gráfico.
figsizetuple: Tamaño de la figura en pulgadas.
show_ct_labelsbool: Si es True, mostrar etiquetas de tiempo circadiano (CT0, CT6, …) alrededor del anillo exterior.

rtype:: Figure

Parameters:

result (SynchronizationResult)
title (str)
figsize (tuple[float, float])
show_ct_labels (bool)

Return type:

Figure

circust.visualization.order_plots.plot_ordered_profiles(result, title='', figsize=None)[source]¶

Cuadrícula de perfiles de expresión de genes core en el orden biológico final.

Cada panel muestra los valores de expresión (puntos grises) vs fase circular, con la curva del modelo FMM (línea roja) superpuesta y el tiempo de pico marcado con una línea vertical discontinua.

Parámetros¶

resultSynchronizationResult: Salida de CircularSynchronizer.run().
titlestr: Etiqueta del titulo de la figura.
figsizetuple, opcional: Tamano de la figura en pulgadas (ancho, alto).

rtype:: Figure

Parameters:

result (SynchronizationResult)
title (str)
figsize (tuple[float, float] | None)

Return type:

Figure

circust.visualization.order_plots.plot_r2_comparison(result, title='', figsize=(7, 4))[source]¶

Gráfico de barras horizontal del R² FMM para cada gen core.

Las barras se codifican por color según la clasificación día/noche. Una línea vertical discontinua en R²=0.5 marca el umbral convencional para un ajuste rítmico “bueno”.

Parámetros¶

result : SynchronizationResult title : str figsize : tuple

rtype:: Figure

Parameters:

result (SynchronizationResult)
title (str)
figsize (tuple[float, float])

Return type:

Figure

circust.visualization.order_plots.plot_day_night_diagram(result, title='', figsize=(5.5, 5.5))[source]¶

Diagrama de sectores circulares con mitades día [0, π) y noche [π, 2π).

Los nombres de los genes se sitúan en su posición de fase de pico en un anillo, con los genes de día en naranja cálido y los de noche en morado intenso. ARNTL y DBP se resaltan como los genes de anclaje y dirección.

Propósito: resumen visual rápido del programa circadiano — qué genes se co-expresan y la separación temporal entre activadores y represores.

Parámetros¶

result : SynchronizationResult title : str figsize : tuple

rtype:: Figure

Parameters:

result (SynchronizationResult)
title (str)
figsize (tuple[float, float])

Return type:

Figure

Outlier plots¶

circust/visualization/outlier_plots.py¶

Visualizaciones para la etapa de refinamiento de outliers (Etapa 1.2).

Tres tipos de gráficos:

plot_core_gene_fits(result)
Cuadrícula de trazas de expresión de genes core con ajustes FMM y Cosinor superpuestos. Muestra la calidad de cada modelo en cada gen core y los tres eigengenes (PC1/PC2/PC3). Equivalente en R: outPar_*.png en giveMatIniNP_v3_cores.

plot_residual_strips(result)
Diagrama de tiras horizontal por gen de residuos FMM estandarizados con líneas umbral de ±3 (multivariante) y ±4 (univariante). Las muestras outlier se resaltan. Equivalente en R: resOutPar_*.png.

plot_residual_heatmap(result)
Mapa de calor de |residuos FMM estandarizados| a través de genes × muestras, con cortes de color en los dos umbrales de outliers. Proporciona una vista global de qué muestras son problemáticas en los distintos genes.

Todas las funciones devuelven una Figure de matplotlib. Ninguna llama a plt.show().

circust.visualization.outlier_plots.plot_core_gene_fits(result, title='', figsize=None, show_eigengenes=True)[source]¶

Cuadrícula de expresión de genes core con superposición de modelos FMM y Cosinor.

Cada panel muestra la expresión observada (puntos grises) ordenada por fase circular, con el ajuste FMM (rojo) y el ajuste Cosinor (azul) superpuestos. Se anotan los valores R² de ambos modelos.

Parámetros¶

resultCPCAResult: Salida de CPCA.run(). Los ajustes iniciales y residuos se almacenan en los campos de diagnostico fmm_fits_initial, cosinor_fits_initial y std_residuals_fmm.
titlestr: Etiqueta del suptítulo.
figsizetuple, opcional: Tamaño de la figura. Se calcula automáticamente si es None.
show_eigengenesbool: Si es True, incluir paneles PC1/PC2/PC3 al final.

rtype:: Figure

Parameters:

result (CPCAResult)
title (str)
figsize (tuple[float, float] | None)
show_eigengenes (bool)

Return type:

Figure

circust.visualization.outlier_plots.plot_residual_strips(result, title='', figsize=None)[source]¶

Diagrama de tiras horizontal de residuos FMM estandarizados por gen.

Cada fila es un gen core (+ eigengenes). Las muestras individuales se grafican como puntos; las que superan el umbral multivariante (|3|) o el umbral univariante (|4|) se codifican por color. Lineas verticales discontinuas marcan los umbrales.

Propósito: identificar visualmente qué muestras impulsan la detección de outliers y en qué genes.

Parámetros¶

result : CPCAResult title : str figsize : tuple, opcional

rtype:: Figure

Parameters:

result (CPCAResult)
title (str)
figsize (tuple[float, float] | None)

Return type:

Figure

circust.visualization.outlier_plots.plot_residual_heatmap(result, title='', figsize=None)[source]¶

Mapa de calor de |residuos FMM estandarizados| (genes x muestras ordenadas).

La escala de color usa tres regiones:

|res| < 3: blanco a azul claro (normal)
3 <= |res| < 4: amarillo a naranja (senal multivariante)
|res| >= 4: rojo a rojo oscuro (senal univariante)

Propósito: vista global de patrones de residuos — útil para detectar problemas a nivel de muestra (bandas verticales) o de gen (filas).

Parámetros¶

result : CPCAResult title : str figsize : tuple, opcional

rtype:: Figure

Parameters:

result (CPCAResult)
title (str)
figsize (tuple[float, float] | None)

Return type:

Figure

Pipeline summary¶

circust/visualization/pipeline_summary.py¶

Figura resumen de extremo a extremo del pipeline CIRCUST (Etapas 1-2).

plot_pipeline_summary(cpca, outlier, order)
Figura única multipanel con cuatro vistas diagnósticas clave:

Dispersión PC1 vs PC2 (etapa CPCA) — muestra estructura circular

Heatmap de residuos (etapa outlier) — muestra calidad de muestras

Diagrama circular de picos (ordenación) — muestra programa temporal

Gráfico de barras R² (ordenación) — muestra calidad del ajuste

Diseñada para informes de tesis y presentaciones.

plot_variance_explained(cpca)
Gráfico de barras tipo scree de la varianza explicada por las primeras componentes principales, con línea acumulada superpuesta.

plot_expression_overview(expr_norm, core_genes, circular_scale, n_top)
Heatmap de expresión normalizada para los n genes más rítmicos, ordenados por fase circular. Los genes core se resaltan. Proporciona una visión global de la señal circadiana a nivel genómico.

Todas las funciones devuelven un matplotlib Figure. Ninguna llama a plt.show().

circust.visualization.pipeline_summary.plot_pipeline_summary(cpca_result, order_result, title='', figsize=(14, 10))[source]¶

Resumen compuesto de cuatro paneles del pipeline CIRCUST.

Disposición:

┌──────────────┬──────────────┐
│ A. PC scatter │ B. Residuals │
├──────────────┼──────────────┤
│ C. Peaks     │ D. R² bars   │
└──────────────┴──────────────┘

Parámetros¶

cpca_resultCPCAResult: Salida de CPCA.run() (incluye CPCA + deteccion de outliers).
order_resultSynchronizationResult: Salida de CircularSynchronizer.
titlestr: Titulo global de la figura.
figsizetuple: Tamano de la figura en pulgadas (ancho, alto).

rtype:: Figure

Parameters:

cpca_result (CPCAResult)
order_result (SynchronizationResult)
title (str)
figsize (tuple[float, float])

Return type:

Figure

circust.visualization.pipeline_summary.plot_variance_explained(cpca_result, n_components=10, title='', figsize=(6, 4))[source]¶

Gráfico de barras tipo scree de la varianza explicada por cada CP.

Muestra las primeras n_components barras con una línea acumulada superpuesta. PC1 y PC2 (usados por CPCA) se resaltan; se marcan los umbrales mínimos para PC2 (10%) y PC1+PC2 total (40%).

Parámetros¶

cpca_resultCPCAResult: Debe tener variance_explained con al menos 3 entradas.
n_componentsint: Numero de CPs a mostrar.
titlestr: Titulo de la figura.
figsizetuple: Tamano de la figura en pulgadas.

rtype:: Figure

Parameters:

cpca_result (CPCAResult)
n_components (int)
title (str)
figsize (tuple[float, float])

Return type:

Figure

circust.visualization.pipeline_summary.plot_expression_overview(expr_ordered, core_genes, circular_scale, n_top=50, title='', figsize=None)[source]¶

Heatmap de expresión normalizada para los genes más rítmicos.

Muestra un mapa de calor (genes × muestras en orden circular) donde el color representa el nivel de expresión [-1, +1]. Los genes reloj core se resaltan con una barra de color lateral.

Propósito: proporciona una instantánea a nivel genómico de la señal circadiana — los genes rítmicos muestran bandas sinusoidales limpias.

Parámetros¶

expr_orderedpd.DataFrame: Matriz de expresión ya ordenada por fase circular (p. ej., SynchronizationResult.expr_ordered).
core_geneslist[str]: Símbolos de genes reloj core para resaltar.
circular_scalenp.ndarray: Eje de tiempo circular para el eje x.
n_topint: Numero de genes top a mostrar (por varianza de fila).
titlestr: Titulo de la figura.
figsizetuple, opcional: Tamano de la figura en pulgadas.

rtype:: Figure

Parameters:

expr_ordered (DataFrame)
core_genes (list[str])
circular_scale (ndarray)
n_top (int)
title (str)
figsize (tuple[float, float] | None)

Return type:

Figure