CATranS 0.1.0__py3-none-any.whl

catrans/__init__.py

@@ -0,0 +1,14 @@
+from catrans.core import (
+    correlation_based_feature_selection,
+    run_catrans,
+    _diffExpAnalysis # recordar quitar esto antes de subir el paquete, que esto es solo para validaciones #TODO
+    )
+from catrans.data import CatransClasses, CatransResult
+
+__all__ = [
+    'correlation_based_feature_selection',
+    'run_catrans',
+    '_diffExpAnalysis', # recordar quitar esto antes de subir el paquete, que esto es solo para validaciones #TODO
+    'CatransClasses',
+    'CatransResult',
+    ]

catrans/_logging.py

@@ -0,0 +1,38 @@
+import logging
+import sys
+
+logger = logging.getLogger(__name__)
+logger.propagate = False
+
+class CustomFormatter(logging.Formatter):
+    info_format = "[%(asctime)s] | %(levelname)-8s | %(message)s"
+    debug_format = "[%(asctime)s] | %(levelname)-8s | STEP: %(funcName)s | %(message)s"
+
+    def format(self, record: logging.LogRecord) -> str:
+        orig_levelname = record.levelname
+        record.levelname = orig_levelname.center(8)
+       
+        if record.levelno == logging.DEBUG:
+            self._style._fmt = self.debug_format
+        else:
+            self._style._fmt = self.info_format
+        return super().format(record)
+
+def _get_logger() -> logging.Logger:
+    return logging.getLogger(name=__name__)
+
+def _setup_internal_logger(verbose: bool) -> None:
+    # Si no hay handlers, creamos uno con el CustomFormatter
+    if not logger.handlers:
+        handler = logging.StreamHandler(sys.stdout)
+        handler.setFormatter(CustomFormatter(datefmt='%y-%m-%d %H:%M:%S'))
+        logger.addHandler(handler)
+    
+    # Si el usuario activa verbose, bajamos a INFO
+    # Si tú desde fuera pusiste DEBUG, esto no lo sobrescribe (porque DEBUG < INFO)
+    if verbose:
+        # if logger.level > logging.INFO or logger.level == logging.NOTSET:
+        logger.setLevel(logging.INFO)
+    else:
+        if logger.level == logging.NOTSET or logger.level == logging.INFO:
+            logger.setLevel(logging.WARNING)

catrans/core.py

@@ -0,0 +1,575 @@
+# Load dependencies
+import pandas as pd 
+from scipy import stats
+import numpy as np
+from statsmodels.stats.multitest import multipletests
+from pydeseq2.dds import DeseqDataSet
+from pydeseq2.default_inference import DefaultInference
+from pydeseq2.ds import DeseqStats
+import igraph as ig
+from inmoose.pycombat import pycombat_seq
+from typing import Any, cast
+import logging
+
+from catrans.data import _CatransInput, CatransResult, CatransClasses
+from catrans._logging import _get_logger, _setup_internal_logger
+
+logger = _get_logger()
+
+# Functions
+# Using instructions in: https://pydeseq2.readthedocs.io/en/stable/auto_examples/plot_step_by_step.html#sphx-glr-auto-examples-plot-step-by-step-py
+def _diffExpAnalysis(
+    data: pd.DataFrame,
+    classification: pd.DataFrame,
+    classes: CatransClasses,
+    n_cpus: int = 8,
+    verbose: bool = False,
+    design: str = '~class'
+    ) -> tuple[int, pd.DataFrame]:
+    """
+    Run differential expression analysis using DESeq2-like workflow.
+
+    This function wraps pydeseq2's `DeseqDataSet` and `DeseqStats` to compute
+    differential expression between groups in `classification`.
+
+    Parameters:
+        data: Gene-expression counts matrix (genes x samples).
+        classification: DataFrame with at least columns ['sample', 'class'] describing
+            group assignments for samples. Samples with NA class are ignored.
+        classes: CatransClasses object defining positive and negative labels.
+        n_cpus: Number of parallel workers to use for inference.
+        verbose: If True, prints progress messages from pydeseq2 internals.
+        design: Formula string for DESeq2 design (e.g. '~class').
+
+    Returns:
+        tuple:
+            - degs (int): Number of differentially expressed genes (padj < 0.05).
+            - dea_res (DataFrame): Full results table from pydeseq2.
+    """
+
+    # Filter classification to only include non-NA classes
+    non_na_classification = classification.loc[classification['class'].notna(), :].copy()
+
+    # Verify that we have 2 unique classes to run differential expression analysis
+    unique_classes = non_na_classification['class'].unique()
+    if len(unique_classes) != 2:
+        logger.warning(f"Fewer than 2 unique classes present ({list(unique_classes)}). Cannot perform differential expression.")
+        return 0, pd.DataFrame()
+
+    # Convert the class column to categorical with levels [negative, positive] to fix Wald contrast direction
+    non_na_classification['class'] = pd.Categorical(
+        non_na_classification['class'],
+        categories=[classes.negative, classes.positive]
+    )
+
+    logger.info("Loading data...")
+    logger.info(f"The dimensions of data are: {data.shape}.")
+        
+    try:
+        dat_c = data.loc[:, non_na_classification["sample"]]
+    except Exception:
+        raise ValueError('Classification must be a dataframe with a column sample and class')
+
+    logger.info(f"The dimensions of classified data are: {dat_c.shape}.")
+    
+    logger.info("Running Differential Expression Analysis")
+
+    inference = DefaultInference(n_cpus=n_cpus)
+    dds = DeseqDataSet(
+        counts=dat_c.T,
+        metadata=non_na_classification,
+        design = design,
+        refit_cooks = True,
+        inference = inference,
+        quiet = not verbose
+    )
+
+    dds.fit_size_factors()
+    dds.fit_genewise_dispersions()
+    dds.fit_dispersion_trend()
+    dds.fit_dispersion_prior()
+    dds.fit_MAP_dispersions()
+    dds.fit_LFC()
+
+    # Potential outliers
+    dds.calculate_cooks()
+    if dds.refit_cooks:
+        dds.refit()
+    
+    ds = DeseqStats(
+        dds,
+        contrast = np.array([0,1]),
+        cooks_filter=True,
+        independent_filter = True,
+        quiet = not verbose
+    )
+
+    ds.run_wald_test()
+    
+    # Adjusted p-valor
+    if ds.independent_filter:
+        ds._independent_filtering()
+    else:
+        ds._p_value_adjustment()
+
+    
+    logger.info("Differential Expression Analysis was successfully performed.")
+
+    # Results
+    ds.summary()
+    dea_res = ds.results_df
+    logger.debug(f"Differential Expression Analysis results:\n{dea_res.head(20).to_string()}")
+    degs = dea_res.query('padj < 0.05').shape[0]
+
+    return degs, dea_res
+
+
+def _correlation_of_gene_tuples(df: pd.DataFrame) -> pd.DataFrame:
+    """
+    Calculate pairwise Pearson correlations and p-values for features (columns) in a DataFrame.
+    """
+
+    # Calculate Pearson correlation (r)
+    r_df = df.corr(method='pearson')
+    # Calculate p-values with numpy 
+    n = len(df)
+    df_degrees = n - 2
+    with np.errstate(divide='ignore', invalid='ignore'):
+        t_matrix = r_df * np.sqrt(df_degrees / (1 - r_df**2))
+        p_matrix = stats.t.sf(np.abs(t_matrix), df_degrees) * 2
+
+    np.fill_diagonal(p_matrix, np.nan)
+    p_df = pd.DataFrame(p_matrix, index=r_df.index, columns=r_df.columns)
+
+    # Avoid repeted combinations by only having from the top diagonal
+    mask = np.triu(np.ones(r_df.shape), k=1).astype(bool)
+    df_result = pd.DataFrame({
+        'Gene1' : np.repeat(r_df.index, r_df.shape[1])[mask.ravel()],
+        'Gene2' : np.tile(r_df.index, r_df.shape[0])[mask.ravel()],
+        'R' : r_df.values[mask],
+        'p_value' : p_df.values[mask]
+    })
+    return df_result
+
+
+def _semisupervised_model(
+        data_raw: pd.DataFrame,
+        data: pd.DataFrame,
+        signature: list[str],
+        acute_classification: pd.DataFrame,
+        model: Any,
+        threshold: float,
+        classes: CatransClasses,
+        design: str = 'class',
+        n_cpus: int = 8
+        ) -> CatransResult:
+    """
+    Run an iterative semi-supervised model to relabel samples and re-run DE analysis.
+    Returns a `CatransResult` object containing iterations and classification history.
+    """
+
+    results = CatransResult()
+    signal = True
+    old_class = acute_classification[design]
+    i = 0
+    # baseline for degs; this way we can infer if classifications are indeed "better" than the initial classification.
+    degs, _ = _diffExpAnalysis(
+        data = data_raw, 
+        classification = acute_classification,
+        classes = classes,
+        n_cpus = n_cpus,
+        design= "~"+design
+    )
+
+
+    while signal:
+
+        i += 1
+        logger.info(f"Iteration {i}")
+
+        # Create the data frame with normalised and batch corrected data and the class for each sample
+        # Filter to only labeled samples to avoid training on unlabeled (NaN) samples
+        labeled_samples = old_class.dropna().index
+        X_tr = data.loc[signature, labeled_samples].T.to_numpy()
+        y_tr = old_class.loc[labeled_samples]
+        y_tr = y_tr.map(lambda x: 1 if x == classes.positive else 0).to_numpy()
+
+        # Train the model and predict
+        logger.info("Generating new predictions")
+
+        try: 
+            model.fit(X_tr, y_tr)
+            y_pred = model.predict_proba(data.loc[signature, :].T.to_numpy())
+        except Exception as e:
+            logger.error(f"Program has suffered a critical exception: {e}")
+            y_pred = None
+        
+
+        logger.info("Predictions were successfully performed")
+        # Check the prediction
+        new_classes = pd.DataFrame(y_pred)
+        
+        new_classes.set_index(data.columns, inplace=True)
+        
+        new_classes['prior_classification'] = old_class
+        new_classes.columns = ['negative_class_probability','positive_class_probability', 'prior_classification']
+        new_classes['current_classification'] = new_classes.apply(
+             lambda row: classes.negative if row['negative_class_probability'] >= threshold else (classes.positive if row['positive_class_probability'] > threshold else np.nan),
+              axis = 1
+              )
+            
+        logger.info("Updating classification")
+
+        logger.info(f"The number of unclassified samples in previous iteration is {int(new_classes['prior_classification'].isnull().sum())}")
+        logger.info(f"The number of unclassified samples in current iteration is {int(new_classes['current_classification'].isnull().sum())}")
+        # Stopping criteria
+        if not all(new_classes['prior_classification'] == new_classes['current_classification']) and int(new_classes['prior_classification'].isnull().sum()) > int(new_classes['current_classification'].isnull().sum()):
+            
+            # Update results object incrementally
+            logger.info("Classification changed; running Differential Expression Analysis...")        
+            classification = pd.DataFrame({
+                "sample" : new_classes.loc[new_classes['current_classification'].notna(),:].index,
+                design : new_classes.loc[new_classes['current_classification'].notna(),"current_classification"]
+            })
+            logger.info("Performing Differential Expression Analysis with new classification.")
+
+            new_degs, dea_results = _diffExpAnalysis(
+                data = data_raw, 
+                classification = classification,
+                classes = classes,
+                n_cpus = n_cpus,
+                design= "~"+design
+            )
+           
+            logger.info(f"DEGs on prior iteration: {degs}")
+            logger.info(f"DEGs on current iteration: {new_degs}")
+            
+            if new_degs > degs:
+                
+                logging.info("All conditions passed, saving iteration result.")
+                results._add_iteration(i, new_degs, dea_results, new_classes)
+                old_class = new_classes['current_classification']
+                degs = new_degs
+            
+            else:
+                logger.info("Stopping condition met: no more DEGs discovered than in previous step.")
+                logging.info("Results of this iteration will not be saved.")
+                
+                signal = False
+            
+        else:
+            logger.info("Stopping condition met: No changes in classification or no new samples classified.")
+            logging.info("Results of this iteration will not be saved.")
+            
+            signal = False
+
+    logger.info("Program ended.")
+    final_df = pd.DataFrame(old_class)
+    final_df.columns = [design]
+    results._set_final_classification(final_df)
+
+
+    return results
+
+
+def _get_normalized_dataset(
+    counts_df: pd.DataFrame,
+    metadata_df: pd.DataFrame,
+    batch_col: str | None = None,
+    log_transform: bool = True,
+    ) -> pd.DataFrame:
+    """
+    Normalize and batch-correct count data for downstream modeling.
+
+    This function applies ComBat-seq batch correction on raw counts and then
+    uses pydeseq2 to compute normalized counts, optionally applying log1p.
+
+    Parameters:
+        counts_df: Raw count matrix (genes x samples).
+        metadata_df: Sample metadata containing at least 'sample' and batch column.
+        batch_col: Column name in metadata specifying batch assignments.
+        log_transform: If True, apply log1p to normalized counts.
+
+    Returns:
+        DataFrame of normalized (and optionally log-transformed) counts.
+    """
+    logger.info("Performing Data Normalization")
+
+    if batch_col:     
+        logger.info(f"Batch column input: {batch_col}")        
+        logger.info("Performing batch correction")
+        # pycombat expects (genes x samples)
+        batch = metadata_df[batch_col].tolist()
+        data_for_dds = pycombat_seq(counts_df, batch).T
+    else:
+        logger.info("No batch column input")
+        logger.info("Normalization will be performed without batch correction")
+        
+        data_for_dds = counts_df.T
+
+    inference = DefaultInference(n_cpus=1) 
+    dds = DeseqDataSet(
+        counts=pd.DataFrame(data_for_dds), # pd.df just to shut up pylance error
+        metadata=metadata_df,
+        design_factors='1',
+        inference=inference,
+        quiet=True
+    )   
+
+    dds.fit_size_factors()
+
+    normed_counts = pd.DataFrame(
+        dds.layers["normed_counts"],
+        index=pd.DataFrame(data_for_dds).index,
+        columns=pd.DataFrame(data_for_dds).columns,
+    )
+
+    if log_transform:
+        normed_counts = pd.DataFrame(np.log1p(normed_counts))
+
+    logger.info("Normalized data successfully")
+
+    return normed_counts.T
+
+
+def correlation_based_feature_selection(
+        data: pd.DataFrame,
+        acute_classification: pd.DataFrame,
+        classes: CatransClasses = CatransClasses(),
+        pval: float = 0.05,
+        cutoff_corr: float | None = None,
+        cutoff_corr_genes: float | None = None,
+        n_cpus: int = 8,
+        verbose: bool = False
+    ) -> list[str] | None:
+    """
+    Find gene-gene correlation and select representative features.
+
+    This function computes gene-wise Spearman correlation against the class label,
+    then builds an undirected graph of highly correlated genes and selects a
+    representative gene per connected component.
+
+    Parameters:
+        data: Gene-expression matrix (genes x samples).
+        acute_classification: DataFrame with columns ['sample', 'class'] representing
+            the class label for each sample.
+        classes: CatransClasses object defining positive and negative labels.
+        pval: P-value threshold for significance when filtering gene-gene correlations.
+        cutoff_corr: Minimum absolute Spearman R for including genes in the gene-gene graph.
+        cutoff_corr_genes: Minimum absolute Pearson R for edge inclusion in the graph.
+
+    Returns:
+        DataFrame with selected genes and their correlation statistics.
+    """
+
+    _setup_internal_logger(verbose)
+
+    logger.info("Initializing Correlation-Based Feature Learning")
+
+    classified_samples_acute = acute_classification.loc[acute_classification['class'].notna(), 'sample']
+
+    # Samples are columns
+    dat_c = data.loc[:, classified_samples_acute]
+
+    corr_list = []
+    # Map labels to numeric to ensure scipy spearmanr calculates correctly on consistent numeric values
+    y_class = acute_classification.loc[:, 'class'].map({classes.negative: 0, classes.positive: 1})
+    logger.info("Performing correlation between Acute classification and genes expression")
+
+    for i in range(dat_c.shape[0]):
+        res = stats.spearmanr(dat_c.iloc[i, :], y_class)
+        corr_list.append({
+            'rho': res[0],
+            'p_value': res[1]
+        })
+
+    corr1 = pd.DataFrame(corr_list, index=dat_c.index)
+    corr1['Genes'] = corr1.index
+
+    if logger.isEnabledFor(logging.DEBUG):
+        logger.debug(f"corr1:\n{corr1.head(n=200).to_string()}")
+
+    if not cutoff_corr:
+        logger.info("Correlation between genes expression and the initial classification is not defined")
+        logger.info("Using Q3 of absolute rho values as cutoff")
+        cutoff_corr = abs(corr1['rho']).quantile(0.75)
+    
+    logger.info(f"R cutoff value between genes expression and classification: {cutoff_corr:.3f}")  
+    corr_genes = corr1[(abs(corr1['rho'])>=cutoff_corr) & (corr1['p_value']<=pval)].index.to_list()
+    logger.info(f"Number of significant genes with R higher than {cutoff_corr:.3f}: {len(corr_genes)}")
+
+    if len(corr_genes) == 0:
+
+        logger.warning(f"There are no genes higher than {cutoff_corr}.")
+        logger.warning(f"The maximum R value is {np.round(np.max(abs(corr1['rho'])),2)}.") # Fixed typo: 'R' to 'rho'
+        logger.warning("By default the analyses will be performed only with significant correlations (p-value <= 0.05)") 
+
+        corr_genes = corr1[corr1['p_value']<=pval].index.to_list()
+
+    subdat = dat_c.loc[corr_genes,:]
+
+    if logger.isEnabledFor(logging.DEBUG):
+        logger.debug(f"Selecction of genes data:\n{subdat.head(n=200).to_string()}")
+    logger.debug(f"Shape: {subdat.shape}")
+    logger.info("Performing Gene to Gene correlation for Feature Selection")
+
+    corr2 = _correlation_of_gene_tuples(subdat.T)
+    # pval_correction_method = 'fdr_bh'
+    pval_correction_method = 'bonferroni'
+    logger.debug(f"Using {pval_correction_method} to correct p-values")
+    _, corr2['p_adj'], _, _ = multipletests(corr2['p_value'], alpha=0.05, method=pval_correction_method)
+    
+
+    # if logger.level == logging.DEBUG:
+        # corr1.to_csv("corr1.csv", index=False, header = True) # DEBUG
+        # corr2.to_csv("corr2.csv", index=False, header = True) # DEBUG
+        # corr_2_2.to_csv("corr2_2.csv", index=False, header = True) # DEBUG
+    if logger.isEnabledFor(logging.DEBUG):
+        logger.debug(f"correlations Gene to Gene Results:\n{corr2.head(n=200).to_string()}")
+    
+    # Using iGraph for gene selection. 
+    # Correlation threshold is used to build a graph. 
+    # We only select the most representative (higher R with CLASSIFICATION) gene from each set
+
+    if not cutoff_corr_genes:
+        percentile = 0.75
+        logger.info("Correlation between genes expression is not defined")
+        logger.info("Using Q3 of absolute R values as cutoff")
+        # logger.info(f"Using percentile {percentile} of absolute R values as cutoff")
+        cutoff_corr_genes = abs(corr2['R']).quantile(percentile)
+        
+    logger.info(f"R Gene x Gene cutoff value: {cutoff_corr_genes:.3f}") # NOTE: change wording
+
+    gene_tuples = (
+        corr2[
+            (corr2['p_adj'] < pval)
+            & (abs(corr2['R']) > cutoff_corr_genes)
+        ]
+        .loc[:, ['Gene1', "Gene2"]]
+        .itertuples(index=False)  # Generator
+    )
+    
+    # Graph building
+    g = ig.Graph.TupleList(gene_tuples)
+    components = g.connected_components(mode='weak')
+    all_genes = set(corr2['Gene1']).union(set(corr2['Gene2']))
+    current_nodes = set(g.vs['name'])
+    isolated_nodes = all_genes - current_nodes
+    g.add_vertices(list(isolated_nodes))
+    components = g.connected_components(mode='weak')
+    
+    toselection = corr1.loc[g.get_vertex_dataframe()['name'],:]
+    toselection['membership'] = components.membership
+    selected_genes = []
+
+    for i in set(toselection['membership']):
+        logger.debug(f"Cluster: {i}")
+        values = toselection.loc[toselection['membership'] == i]
+        logger.debug(f"Number of genes in Cluster {i}: {len(values)}")
+        logger.debug(f"Cluster values: \n{values.to_string()}")
+        selected_gene = abs(values['rho']).idxmax()
+        logger.debug(f"Gene with max absolute R value from Cluster {i}: {selected_gene}")
+        selected_genes.append(selected_gene)
+       
+    corr1_final = corr1.loc[(corr1['Genes'].isin(selected_genes) & (corr1['p_value'] <= pval))] # is pval needed? 
+    logger.debug(corr1_final.to_string())
+    logger.info(f"Number of final genes selected: {len(corr1_final)}")
+    
+    return cast(list[str], corr1_final['Genes'].to_list())
+
+    
+def run_catrans(
+        raw_counts: pd.DataFrame,
+        metadata: pd.DataFrame,
+        acute_classification: pd.DataFrame,
+        model: Any,
+        classes: CatransClasses | None = None,
+        batch_col: str | None = None,
+        model_threshold: float = 0.8,
+        n_cpus: int = 8,
+        signature_genes: list[str] | None = None,
+        verbose: bool = False
+    ) -> CatransResult:
+
+    _setup_internal_logger(verbose=verbose)
+
+    if classes is None:
+        classes = CatransClasses()
+
+    # Argument checking
+    if not isinstance(acute_classification, pd.DataFrame):
+        raise TypeError("acute_classification must be a pandas.DataFrame")
+
+    if 'sample' not in acute_classification.columns or 'class' not in acute_classification.columns:
+        raise ValueError("acute_classification must be a pandas.DataFrame with 'sample' and 'class' columns.")
+
+    # Validate classes in acute_classification
+    allowed_values = {classes.positive, classes.negative}
+    actual_values = set(acute_classification['class'].dropna().unique())
+    invalid_values = actual_values - allowed_values
+    if invalid_values:
+        raise ValueError(
+            f"Found invalid labels in acute_classification['class']: {invalid_values}. "
+            f"Only '{classes.positive}' (positive) and '{classes.negative}' (negative) are allowed, plus NaN."
+        )
+
+    # Create a copy to avoid mutating the caller's DataFrame in-place
+    acute_classification = acute_classification.copy()
+
+    acute_classification.set_index(
+        pd.Index(acute_classification['sample'].to_list()),
+        inplace=True
+        )
+
+    if not hasattr(model, 'predict_proba'):
+        raise AttributeError("Passed model must have a predict_proba method in order to run semi-supervised learning.")
+
+    if signature_genes is None:
+        logger.info("No signature genes were provided.")
+        logger.info("Feature selection will be performed with default parameters.")
+        
+        signature_genes = correlation_based_feature_selection(
+            data=raw_counts,
+            acute_classification=acute_classification,
+            classes=classes,
+            n_cpus=n_cpus,
+            verbose=verbose
+        )
+        
+        if signature_genes is None:
+            raise ValueError("Feature selection failed to produce a gene signature.")
+
+    input_data = _CatransInput(
+        raw_counts=raw_counts,
+        metadata=metadata,
+        acute_classification=acute_classification,
+        model=model,
+        classes=classes,
+        batch_col=batch_col,
+        model_threshold=model_threshold,
+        n_cpus=n_cpus,
+        signature_genes=signature_genes
+    )
+
+    logger.info("Initializing CATranS algorithm")
+    logger.info("Normalizing DataSet...")
+
+    normalized_data = _get_normalized_dataset(
+        counts_df=input_data.raw_counts,
+        metadata_df=input_data.metadata,
+        batch_col=input_data.batch_col
+    )
+
+    results = _semisupervised_model(
+        data_raw=input_data.raw_counts,
+        data=normalized_data, 
+        signature=input_data.signature_genes or [],
+        acute_classification=input_data.acute_classification,
+        model=input_data.model,
+        threshold=input_data.model_threshold,
+        classes=input_data.classes,
+    )
+    
+    return results
+    
+    

catrans/data.py

@@ -0,0 +1,61 @@
+from dataclasses import dataclass
+from typing import Any, List, Optional
+import pandas as pd
+
+@dataclass
+class CatransClasses:
+    positive: str = "NonSurvivor"
+    negative: str = "Survivor"
+
+@dataclass
+class _CatransInput:
+    raw_counts: pd.DataFrame
+    metadata: pd.DataFrame
+    acute_classification: pd.DataFrame
+    model: Any
+    classes: CatransClasses
+    batch_col: Optional[str] = None
+    model_threshold: float = 0.8
+    n_cpus: int = 8
+    signature_genes: Optional[List[str]] = None
+
+@dataclass
+class _IterationResult:
+    iteration: int
+    differentially_expressed_genes: int
+    differential_expression_analysis_results: pd.DataFrame
+    model_classification_results: pd.DataFrame
+
+class CatransResult:
+    def __init__(self) -> None:
+        self.iterations: List[_IterationResult] = list()
+        self.final_classification: Optional[pd.DataFrame] = None
+
+    def _add_iteration(
+            self,
+            iteration_index: int,
+            de_genes_count: int,
+            dea_results: pd.DataFrame,
+            model_classification_results: pd.DataFrame
+        ) -> None:
+
+        self.iterations.append(
+            _IterationResult(
+                iteration=iteration_index,
+                differentially_expressed_genes=de_genes_count,
+                differential_expression_analysis_results=dea_results,
+                model_classification_results=model_classification_results
+            )
+        )
+
+    @property
+    def number_of_iterations(self) -> int:
+        return len(self.iterations)
+    
+    @property
+    def last_iteration(self) -> _IterationResult:
+        return self.iterations[-1]
+
+    def _set_final_classification(self, classification: pd.DataFrame) -> None:      
+        self.final_classification = classification
+

catrans-0.1.0.dist-info/METADATA

@@ -0,0 +1,268 @@
+Metadata-Version: 2.4
+Name: CATranS
+Version: 0.1.0
+Summary: Clinical Acute Transcriptomic Stratification
+Project-URL: Homepage, https://github.com/ruben-canas-ivi/CATranS
+Project-URL: Issues, https://github.com/ruben-canas-ivi/CATranS/issues
+Author-email: Patricia Sebastián-León <patricia.sebastian@ivirma.com>, Antonio Parraga-Leo <antonio.parraga@ivirma.com>, Rubén Cañas-Cañas <ruben.canas@ivirma.com>
+License-File: LICENSE
+Keywords: bioinformatics,deseq2,genomics,machine-learning,stratification
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.11
+Requires-Dist: igraph>=1.0.0
+Requires-Dist: inmoose>=0.9.1
+Requires-Dist: numpy>=2.3.0
+Requires-Dist: pandas>=2.3.3
+Requires-Dist: pydeseq2>=0.5.4
+Requires-Dist: scikit-learn>=1.8.0
+Requires-Dist: scipy>=1.17.1
+Description-Content-Type: text/markdown
+
+# CATranS: Clinical Acute Transcriptomic Stratification
+
+**CATranS** is a robust bioinformatics and machine learning pipeline written in Python designed to stratify acute clinical cohorts using transcriptomic count data. 
+
+Through an iterative, semi-supervised learning approach, CATranS combines data normalization, batch correction, correlation-based feature selection, and class prediction to refine classifications of patient cohorts (e.g., separating acute from non-acute states, or predicting survival outcomes).
+
+---
+
+## Key Features
+
+- **Iterative Semi-Supervised Relabeling**: Safely expands training cohorts by predicting clinical labels on unclassified/unlabeled samples using high-confidence thresholds.
+- **Generalized Custom Classes**: Supports user-defined positive and negative class labeling (e.g., `Survivor`/`NonSurvivor`, `Mild`/`Severe`, `Responders`/`NonResponders`) with robust Categorical ordering to fix Wald contrast directions in DESeq2.
+- **Batch Correction**: Integrated with `inmoose` for ComBat-seq count batch effect correction.
+- **DESeq2-style Normalization**: Leverages the high-performance `pydeseq2` implementation for median-of-ratios normalization.
+- **Correlation-Based Feature Learning**: Custom graph-theory based gene selection utilizing `igraph`. Filters out highly redundant co-expressed genes and selects optimal representative biomarkers correlating with clinical outcomes.
+- **Flexible Estimator Integration**: Compatible with any Scikit-Learn classifier exposing a `predict_proba` method.
+
+---
+
+## Workflow Overview
+
+```mermaid
+graph TD
+    A[Raw Count Matrix & Metadata] --> B[Data Normalization & Optional ComBat-seq Batch Correction]
+    B --> C[Feature Selection: Spearman Correlation with Labels]
+    C --> D[Graph Construction: Pearson Gene-Gene Network]
+    D --> E[Redundant Feature Compression: Connected Components Vertex Selection]
+    E --> F[Iterative Semi-Supervised Model Training]
+    F --> G[Fit Classifier & Predict Unlabeled Samples]
+    G --> H{Meets Threshold?}
+    H -- Yes --> I[Relabel Samples & Run DESeq2 Differential Expression Analysis]
+    I --> J{Are there new DEGs?}
+    J -- Yes --> F
+    J -- No --> K[Final Output Classifications & Iteration History]
+    H -- No --> K
+```
+
+---
+
+## Installation
+
+We recommend using [uv](https://github.com/astral-sh/uv) or `pip` for rapid virtual environment setup and dependency management.
+
+```bash
+# Clone the repository
+git clone https://github.com/ruben-canas-ivi/CATranS.git
+cd CATranS
+
+# Install dependencies and the package using uv
+uv sync
+```
+
+### Dependencies
+- Python `>=3.11`
+- `numpy>=2.3.0`
+- `pandas>=2.3.3`
+- `scipy>=1.14.0`
+- `scikit-learn>=1.8.0`
+- `pydeseq2>=0.5.4`
+- `igraph>=1.0.0`
+- `inmoose>=0.9.1`
+
+---
+
+## API Reference & Usage Scenarios
+
+### Core Classes & Functions
+
+#### 1. `CatransClasses`
+Defines the names of the binary classes.
+- `positive` (default `"Dead"`): The target/case class.
+- `negative` (default `"Alive"`): The reference/control class.
+
+#### 2. `correlation_based_feature_selection`
+Identifies representative biomarker genes by correlating expression levels with labels, building a gene-gene correlation network, and selecting one representative gene per connected component.
+
+#### 3. `run_catrans`
+Runs the iterative semi-supervised relabeling pipeline.
+- `raw_counts` (pd.DataFrame): Genes (rows) by Samples (columns).
+- `metadata` (pd.DataFrame): Samples (rows) with metadata.
+- `acute_classification` (pd.DataFrame): Samples (rows) with initially known labels under the column `"class"` (unlabeled samples should be `NaN`).
+- `model`: Any Scikit-Learn compatible classifier (e.g. `RandomForestClassifier`, `SVC(probability=True)`).
+- `classes` (CatransClasses, Optional): Custom positive/negative class names.
+- `batch_col` (str, Optional): Metadata column to use for ComBat-seq batch correction.
+- `model_threshold` (float, default `0.8`): Confidence threshold to assign a label.
+- `signature_genes` (list[str], Optional): Genes to use for training the model. If `None`, `correlation_based_feature_selection` runs automatically.
+
+---
+
+### Usage Scenarios
+
+#### Scenario 1: Normal Workflow (Two-step Feature Selection + Stratification)
+This is the recommended workflow where you first find a non-redundant gene signature, then pass it to the CATranS pipeline.
+
+```python
+import pandas as pd
+from sklearn.ensemble import RandomForestClassifier
+import catrans
+
+# 1. Load your transcriptomics and clinical datasets
+counts = pd.read_csv("data/raw_counts.tsv", sep="\t", index_col=0)
+metadata = pd.read_csv("data/metadata.tsv", sep="\t", index_col=0)
+initial_classes = pd.read_csv("data/initial_classes.tsv", sep="\t", index_col=0)
+
+# 2. Define custom labels: "Survivor" (negative) and "NonSurvivor" (positive)
+my_classes = catrans.CatransClasses(positive="NonSurvivor", negative="Survivor")
+
+# 3. Perform correlation-based feature selection to identify candidate biomarkers
+signature = catrans.correlation_based_feature_selection(
+    data=counts,
+    acute_classification=initial_classes,
+    classes=my_classes,
+    pval=0.05,
+    cutoff_corr=0.5,
+    cutoff_corr_genes=0.8,
+    n_cpus=4
+)
+
+# 4. Run the semi-supervised relabeling pipeline using the selected signature
+results = catrans.run_catrans(
+    raw_counts=counts,
+    metadata=metadata,
+    acute_classification=initial_classes,
+    classes=my_classes,
+    model=RandomForestClassifier(random_state=42),
+    model_threshold=0.75,
+    signature_genes=signature,
+    n_cpus=4
+)
+
+print(results.final_classification)
+```
+
+#### Scenario 2: Predefined/Custom Gene Signature (Direct Stratification)
+If you already have a target gene signature (e.g., from literature or a previous experiment), you can bypass the feature selection step entirely and run the stratification pipeline directly.
+
+```python
+import pandas as pd
+from sklearn.svm import SVC
+import catrans
+
+counts = pd.read_csv("data/raw_counts.tsv", sep="\t", index_col=0)
+metadata = pd.read_csv("data/metadata.tsv", sep="\t", index_col=0)
+initial_classes = pd.read_csv("data/initial_classes.tsv", sep="\t", index_col=0)
+
+# Custom predefined signature from literature
+custom_signature = ["ENSG00000034693.15", "ENSG00000101188.5", "ENSG00000104870.13"]
+
+# Run the CATranS pipeline directly with the custom signature
+results = catrans.run_catrans(
+    raw_counts=counts,
+    metadata=metadata,
+    acute_classification=initial_classes,
+    model=SVC(probability=True, random_state=42),
+    model_threshold=0.8,
+    signature_genes=custom_signature,
+    n_cpus=4
+)
+
+print(f"Completed in {results.number_of_iterations} iterations.")
+```
+
+#### Scenario 3: Implicit Feature Selection (Defaulting Signature Genes)
+If you do not specify a list of `signature_genes`, `run_catrans` will automatically execute `correlation_based_feature_selection` under the hood using default parameters.
+
+```python
+import pandas as pd
+from sklearn.ensemble import RandomForestClassifier
+import catrans
+
+counts = pd.read_csv("data/raw_counts.tsv", sep="\t", index_col=0)
+metadata = pd.read_csv("data/metadata.tsv", sep="\t", index_col=0)
+initial_classes = pd.read_csv("data/initial_classes.tsv", sep="\t", index_col=0)
+
+# Run CATranS (it will automatically perform feature selection internally)
+results = catrans.run_catrans(
+    raw_counts=counts,
+    metadata=metadata,
+    acute_classification=initial_classes,
+    model=RandomForestClassifier(random_state=42),
+    model_threshold=0.75,
+    n_cpus=4
+)
+```
+
+#### Scenario 4: Default Thresholds & Core Settings
+You can omit optional arguments like `model_threshold` or `classes` if you wish to use the defaults (`model_threshold=0.8`, `classes` defaulting to `"Dead"`/`"Alive"`).
+
+```python
+import pandas as pd
+from sklearn.ensemble import RandomForestClassifier
+import catrans
+
+counts = pd.read_csv("data/raw_counts.tsv", sep="\t", index_col=0)
+metadata = pd.read_csv("data/metadata.tsv", sep="\t", index_col=0)
+initial_classes = pd.read_csv("data/initial_classes.tsv", sep="\t", index_col=0)
+
+# Minimal parameters
+results = catrans.run_catrans(
+    raw_counts=counts,
+    metadata=metadata,
+    acute_classification=initial_classes,
+    model=RandomForestClassifier(random_state=42)
+)
+```
+
+#### Scenario 5: Running with Batch Correction
+To normalize and batch-correct raw counts concurrently, specify the name of the batch column in your metadata dataframe:
+
+```python
+results = catrans.run_catrans(
+    raw_counts=counts,
+    metadata=metadata,
+    acute_classification=initial_classes,
+    model=RandomForestClassifier(random_state=42),
+    batch_col="batch"  # ComBat-seq batch effect correction column
+)
+```
+
+---
+
+## Testing & Quality Assurance
+
+CATranS utilizes `pytest` for automated test suites, `ruff` for code style consistency, and `mypy` for strict type checking.
+
+```bash
+# Run tests
+uv run pytest
+
+# Check code format and style
+uv run ruff check .
+
+# Perform static type checks
+uv run mypy src/catrans
+```
+
+---
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

catrans-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+catrans/__init__.py,sha256=2YLkbeddIMqNLiOedoQZMCVSRgb4LlAl2lW5Jj8rT5A,496
+catrans/_logging.py,sha256=YoFzPtDDs4JogpKh3C8ZfzajpOeDMSz3XaQc04NKItE,1423
+catrans/core.py,sha256=bdyKDwJE5B9dT1vqdq80ex8COH_9Xxdu61T88Ikhj1s,21888
+catrans/data.py,sha256=WfEXgkPlNFb1t6_BwDKFQ-WJrmEManUA5jj4-TEenRA,1773
+catrans-0.1.0.dist-info/METADATA,sha256=xcDqt865sGdXLjmTThH2V6Gdnto0Cf1aXFLVvDAt3s4,10218
+catrans-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+catrans-0.1.0.dist-info/licenses/LICENSE,sha256=TMXaKrmR7IOOkX6DeBhc_d9UmTaix8VmIhWO0_0QxZw,1072
+catrans-0.1.0.dist-info/RECORD,,

catrans-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

catrans-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ruben-canas-ivi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.