circust.preprocessing

circust.preprocessing.load_expression_matrix(path, gene_column=None, chunk_size=None)[source]

Carga una matriz de expresion genica desde disco en un DataFrame de pandas.

Forma esperada tras la carga

  • Filas = genes (indice de fila = simbolos genicos, ej. “ARNTL”, “PER1”)

  • Columnas = muestras (cada columna = un individuo/muestra)

  • Valores = conteos de expresion brutos (float); ceros y NaN permitidos

Formatos soportados

.csv Valores separados por comas .tsv / .txt Valores separados por tabuladores .xlsx / .xls Libro Excel (se lee la primera hoja) .parquet Apache Parquet — recomendado para conjuntos grandes

param path:

Ruta al archivo. El formato se detecta por la extension.

type path:

str

param gene_column:

Nombre de la columna que contiene los simbolos genicos. Especificar explicitamente si el archivo tiene un layout no estandar, ej. gene_column=”gene_id”.

type gene_column:

Optional[str]

param chunk_size:

Solo para archivos .parquet. Numero de row-groups a leer por vez. Util cuando el archivo es mas grande que la RAM disponible. Si None (defecto), se carga el archivo completo de una vez. Ignorado para CSV/TSV/Excel.

type chunk_size:

Optional[int]

returns:

Matriz con simbolos genicos como indice de fila (index.name = “gene_symbol”) e IDs de muestra como nombres de columna. Todos los valores son float64. Celdas que no se pudieron parsear como numeros se establecen a NaN.

rtype:

DataFrame

raises FileNotFoundError:

Si no existe archivo en path.

raises ValueError:

Si la extension del archivo no esta en la lista soportada.

raises ImportError:

Si se lee un .parquet y pyarrow no esta instalado.

Example

Cargar un CSV estandar:

>>> df = load_expression_matrix("data/raw/gtex_brain.csv")
>>> df.shape
(56200, 479)
>>> df.index[:3].tolist()
['ARNTL', 'PER1', 'CRY1']

Cargar un parquet grande con lectura por bloques:

>>> df = load_expression_matrix(
...     "data/raw/gtex_brain.parquet",
...     chunk_size=10_000,
... )
Parameters:

  • path (str)

  • gene_column (str | None)

  • chunk_size (int | None)

Return type:

DataFrame

class circust.preprocessing.PreprocessingResult(expr_norm, expr_raw, dropped_sparse=<factory>, dropped_duplicates=<factory>, n_genes_in=0, n_genes_out=0, n_samples=0)[source]

Bases: object

Todos los resultados producidos por Preprocessor.

Variables:

  • expr_norm (pd.DataFrame) – Matriz de expresion normalizada, genes x muestras, valores en [-1, 1]. Es la matriz que consume cada paso (CPCA, FMM).

  • expr_raw (pd.DataFrame) – Matriz bruta filtrada despues de eliminar genes malos pero antes de normalizar. Util para depuracion y validacion.

  • dropped_sparse (List[str]) – Simbolos genicos eliminados porque > zero_threshold de muestras eran cero o NaN.

  • dropped_duplicates (List[str]) – Simbolos genicos eliminados durante la resolucion de duplicados (filas con menor MAD).

  • n_genes_in (int) – Numero de genes que entraron al preprocesador.

  • n_genes_out (int) – Numero de genes que sobrevivieron a todos los pasos de filtrado.

  • n_samples (int) – Numero de muestras. No cambia nunca durante el preprocesamiento.

Parameters:

  • expr_norm (DataFrame)

  • expr_raw (DataFrame)

  • dropped_sparse (list[str])

  • dropped_duplicates (list[str])

  • n_genes_in (int)

  • n_genes_out (int)

  • n_samples (int)

expr_norm: DataFrame
expr_raw: DataFrame
dropped_sparse: list[str]
dropped_duplicates: list[str]
n_genes_in: int = 0
n_genes_out: int = 0
n_samples: int = 0
summary()[source]

Devuelve un resumen legible de lo ocurrido durante el preprocesamiento.

Return type:

str

circust.preprocessing.normalise_matrix(mat, norm_min=-1.0, norm_max=1.0)[source]

Normaliza min-max cada fila de mat al intervalo [norm_min, norm_max].

Filas constantes (min == max) se mapean a todos ceros.

Parameters:

  • mat (DataFrame) – Matriz genes × muestras. Valores pueden ser float o int.

  • norm_min (float) – Extremos del rango de salida. Por defecto [-1, 1].

  • norm_max (float) – Extremos del rango de salida. Por defecto [-1, 1].

Return type:

DataFrame

class circust.preprocessing.Preprocessor(sparse_threshold=0.3, zero_threshold=None, nan_threshold=None, norm_min=-1.0, norm_max=1.0, verbose=True)[source]

Bases: object

Limpia y normaliza una matriz de expresion genica bruta.

  1. Eliminar genes sin nombre (NA rownames en R)

  2. Eliminar genes sparse (> sparse_threshold de muestras son cero O NaN)

  3. Resolver nombres de genes duplicados — conservar la fila con mayor MAD

  4. Normalizar cada gen a [-1, 1]

Parameters:

  • sparse_threshold (float) – Fraccion de muestras que pueden ser cero o NaN antes de que un gen se elimine. La comparacion es estricta (>), asi que un gen exactamente en el umbral se conserva.

  • zero_threshold (Optional[float]) – Override para el umbral solo de ceros. Si None (defecto), usa sparse_threshold para ceros.

  • nan_threshold (Optional[float]) – Override para el umbral solo de NaN. Si None (defecto), usa sparse_threshold para NaN.

  • verbose (bool) – Si True, imprime mensajes de progreso tras cada paso.

  • norm_min (float)

  • norm_max (float)

Example

>>> import pandas as pd
>>> import numpy as np
>>>
>>> rng = np.random.default_rng(0)
>>> mat = pd.DataFrame(
...     rng.poisson(10, size=(200, 60)).astype(float),
...     index=[f"GENE_{i}" for i in range(200)],
...     columns=[f"sample_{j}" for j in range(60)],
... )
>>>
>>> result = Preprocessor().run(mat)
>>> result.expr_norm.values.min() >= -1.0
True
>>> result.expr_norm.values.max() <= 1.0
True
run(matrix)[source]

Ejecuta los cuatro pasos de preprocesamiento en orden.

Parameters:

matrix (DataFrame) – Matriz de expresion bruta cargada por load_expression_matrix(). Filas = genes, columnas = muestras. Puede contener ceros y NaN.

Return type:

PreprocessingResult