circust.core_genes

circust/core_genes.py

Modulo de seleccion de genes core (reloj circadiano) para el pipeline CIRCUST.

Responsabilidad

Este modulo resuelve que genes core se usan en la ejecucion y valida que esos genes esten presentes en la matriz de expresion. Es el unico punto del pipeline donde se toma esa decision.

Conjuntos predefinidos

• “circust” Larriba et al. 2023 — 12 genes (defecto de CIRCUST)

• “zhang” Zhang et al. 2014 — 10 genes

• “ruben” Ruben et al. 2018 — 54 genes (lista pendiente de completar)

Uso tipico

>>> from circust.core_genes import CoreGeneSelector
>>> from circust.preprocessing import Preprocessor, load_expression_matrix
>>>
>>> matrix = load_expression_matrix("data/raw/gtex_brain.csv")
>>> prep   = Preprocessor().run(matrix)
>>>
>>> # Preset por nombre
>>> sel    = CoreGeneSelector(preset="circust")
>>> result = sel.select(prep.expr_norm)
>>> result.genes          # lista validada
>>> result.missing        # genes no encontrados en la matriz
>>>
>>> # Lista personalizada
>>> sel    = CoreGeneSelector(custom_genes=["ARNTL", "DBP", "PER1", "PER2"])
>>> result = sel.select(prep.expr_norm)

Posicion en el pipeline

Preprocessor -> CoreGeneSelector -> CPCA -> …

class circust.core_genes.CoreGeneResult(genes, genes_requested, missing=<factory>, preset='circust')

Bases: object

Resultado de la seleccion de genes core.

Variables:

• genes (list[str]) – Genes seleccionados y validados (presentes en la matriz de expresion). Es el valor que consume CPCA y el resto del pipeline.

• genes_requested (list[str]) – Genes solicitados originalmente, antes de validar contra la matriz.

• missing (list[str]) – Genes solicitados que no se encontraron en la matriz de expresion. Puede ser una lista vacia si todos los genes estaban presentes.

• preset (str) – Nombre del preset utilizado ("circust", "zhang", "ruben") o "custom" si el usuario paso una lista explicita.

Parameters:

• genes (list[str])

• genes_requested (list[str])

• missing (list[str])

• preset (str)

genes: list[str]

genes_requested: list[str]

missing: list[str]

preset: str = 'circust'

summary()

Return type:

str

class circust.core_genes.CoreGeneSelector(preset='circust', custom_genes=None, verbose=True)

Bases: object

Selecciona y valida los genes core del reloj circadiano.

Parameters:

• preset (str | None) – Nombre del conjunto predefinido: “circust”, “zhang”, “ruben”. Se ignora si se pasa custom_genes. Si ambos son None se usa “circust” por defecto.

• custom_genes (list[str] | None) – Lista explicita de simbolos genicos. Tiene prioridad sobre “preset”.

• verbose (bool) – Si True, imprime el resumen de seleccion al llamar a select().

Raises:

ValueError – Si preset no es un nombre reconocido y no se paso custom_genes.

PRESETS = {'circust': ['PER1', 'PER2', 'PER3', 'CRY1', 'CRY2', 'ARNTL', 'CLOCK', 'NR1D1', 'RORA', 'DBP', 'TEF', 'STAT3'], 'ruben': [], 'zhang': ['ARNTL', 'DBP', 'NR1D1', 'NR1D2', 'PER1', 'PER2', 'PER3', 'USP2', 'TSC22D3', 'TSPAN4']}

select(expr_norm)

Valida los genes solicitados contra la matriz de expresion.

Parameters:

expr_norm (DataFrame) – Matriz de expresion normalizada, genes x muestras. Tipicamente PreprocessingResult.expr_norm.

Returns:

result.genes contiene la lista validada lista para CPCA.

Return type:

CoreGeneResult

Raises:

ValueError – Si ningun gen solicitado esta presente en la matriz.

classmethod from_string(raw, verbose=True)

Construye un CoreGeneSelector desde un argumento de linea de comandos.

Acepta tres formas: - None → preset por defecto ("circust") - "circust" → preset con ese nombre - "PER1,PER2,..." → lista separada por comas

Parameters:

• raw (str | None) – Valor del argumento --core-genes de la CLI.

• verbose (bool) – Propagado al constructor.

Return type:

CoreGeneSelector

Raises:

ValueError – Si la lista personalizada tiene menos de 2 genes.