wormcat3 0.1.11__py3-none-any.whl

wormcat3/__init__.py

@@ -0,0 +1,7 @@
+
+__version__ = "0.1.11"
+
+from .wormcat import Wormcat
+from .annotations_manger import AnnotationsManager
+from .constants import PAdjustMethod
+from .wormcat_error import WormcatError, ErrorCode

wormcat3/annotations_manger.py

@@ -0,0 +1,210 @@
+import pandas as pd
+import os
+from pathlib import Path
+from wormcat3 import file_util
+import wormcat3.constants as cs
+from wormcat3.wormcat_error import WormcatError, ErrorCode
+    
+
+class AnnotationsManager:
+    """ Manages gene annotations and preprocessing. """
+    
+    def __init__(self, annotation_file=cs.DEFAULT_ANNOTATION_FILE_NAME):
+        """Initialize with the path to the annotation file."""
+        if file_util.is_file_path(annotation_file):
+            self.annotation_file_path = annotation_file
+        else:
+            self.annotation_file_path = file_util.find_file_path(annotation_file)
+            if not self.annotation_file_path:
+                raise WormcatError(f"Annotation file not found: {annotation_file}", ErrorCode.FILE_NOT_FOUND.to_dict())
+                        
+        self.annotations_df = self._load_annotations()
+            
+     
+        
+    def _load_annotations(self):
+        """ Load annotations from file. """
+        try:
+            df = pd.read_csv(self.annotation_file_path) # type: ignore
+            df.columns = df.columns.str.replace(' ', '.')
+            if df.empty:
+                raise WormcatError(f"Annotation file '{self.annotation_file_path}' is empty.", ErrorCode.FILE_LOAD_FAILED.to_dict())
+            return df
+        except Exception as e:
+            raise WormcatError(f"Failed to load annotation file: {e}", 
+                                ErrorCode.FILE_LOAD_FAILED.to_dict(), 
+                                origin="AnnotationsManager._load_annotations")
+            
+    @staticmethod
+    def available_annotation_files():
+        """
+        Return a list of .csv file names located in:
+        - the 'extdata' directory (next to this script), and
+        - the directory defined by the WORMCAT_DATA_PATH environment variable (if set).
+        """
+        file_path = Path(__file__).resolve()
+        extdata_path = file_path.parent / "extdata"
+
+        search_dirs = [extdata_path]
+
+        env_path = os.environ.get("WORMCAT_DATA_PATH")
+        if env_path:
+            env_path = Path(env_path)
+            if env_path.exists() and env_path.is_dir():
+                search_dirs.append(env_path)
+
+        found_files = set()
+
+        for directory in search_dirs:
+            if directory.exists():
+                for f in directory.glob("*.csv"):
+                    if f.is_file():
+                        found_files.add(f.name)
+
+        return sorted(found_files)
+
+    
+    def annotation_name(self):
+        # Get the base name of the file (with extension, no directory)
+        if isinstance(self.annotation_file_path, (str, os.PathLike)) and self.annotation_file_path:
+            return os.path.basename(self.annotation_file_path)
+        else:
+            return "[NO_ANNOTATION_NAME]"
+
+    def get_gene_id_type(self, gene_set):
+        # Skip the first row (possible header), then filter valid gene entries
+        valid_genes = [
+            g for g in gene_set[1:]  # Skip the first row
+            if isinstance(g, str) and len(g.strip()) > 1
+        ]
+
+        if len(valid_genes) < 2:
+            raise WormcatError(
+                "Not enough valid gene entries to determine gene type.",
+                ErrorCode.INVALID_VALUE.to_dict()
+            )
+
+        # Check if both start with 'WBGene' or not
+        if valid_genes[0].startswith("WBGene") and valid_genes[1].startswith("WBGene"):
+            return cs.GENE_TYPE_WORMBASE_ID
+        elif not valid_genes[0].startswith("WBGene") and not valid_genes[1].startswith("WBGene"):
+            return cs.GENE_TYPE_SEQUENCE_ID
+        else:
+            raise WormcatError(
+                "Invalid gene data: One gene starts with 'WBGene', but the other does not.",
+                ErrorCode.INVALID_VALUE.to_dict()
+            )
+           
+    @staticmethod
+    def dedup_list(input_list):
+        """ Deduplicate a list while preserving order. """
+        
+        seen = set()
+        deduped_list = []
+        for item in input_list:
+            if item not in seen:
+                deduped_list.append(item)
+                seen.add(item)
+        return deduped_list
+    
+    def add_annotations(self, gene_set_list, gene_type):
+        """ Add annotations to the gene set. """
+        
+        gene_set_df = pd.DataFrame(gene_set_list, columns=[gene_type])
+        
+        # Verify if 'gene_type' is a column in the DataFrame
+        if gene_type not in self.annotations_df.columns:
+            raise WormcatError(f"Column '{gene_type}' not found in the DataFrame.", ErrorCode.INVALID_VALUE.to_dict())
+        
+        return pd.merge(gene_set_df, self.annotations_df, on=gene_type, how='left')
+
+
+    def segment_genes_by_annotation_match(self, gene_set_list, gene_type):
+        """ Split genes into those with and without annotations. """
+        
+        gene_set_df = pd.DataFrame(gene_set_list, columns=[gene_type])
+        gene_set_df = gene_set_df.fillna('') # It is rare but possible that we get NaN in the input
+        
+        # Check if gene_type is in both dataframes
+        if gene_type not in gene_set_df.columns:
+            raise WormcatError(f"'{gene_type}' MUST be a column in the Gene Set DataFrame.", ErrorCode.MISSING_FIELD.to_dict())
+        if gene_type not in self.annotations_df.columns:
+            raise WormcatError(f"Incorrect '{gene_type}' name. Column not found in {self.annotation_name()} file.", ErrorCode.MISSING_FIELD.to_dict())
+        
+        # Perform the left merge
+        merged_df = pd.merge(gene_set_df, self.annotations_df, on=gene_type, how='left')
+        
+        # Split based on presence of annotation (assuming at least one non-key column in annotations_df)
+        annotation_columns = [col for col in self.annotations_df.columns if col != gene_type]
+        
+        genes_matched_df = merged_df.dropna(subset=annotation_columns)
+        genes_not_matched_df = merged_df[merged_df[annotation_columns].isnull().all(axis=1)]
+        genes_not_matched_df = genes_not_matched_df[[gene_type]]
+
+        return genes_matched_df, genes_not_matched_df
+
+    def create_gmt_for_annotations(self, output_dir_path, id_col_nm="Wormbase.ID", output_file_nm_prefix="wormcat"):
+        """ Create GMT formatted files for all categories. """
+        for category in [1,2,3]:
+            gmt_format = self.category_to_gmt_format(category, id_col_nm)
+            output_file_path = f"{output_dir_path}/{output_file_nm_prefix}_cat_{category}.gmt"
+            self._save_gmt_to_file(gmt_format, output_file_path)    
+
+    def category_to_gmt_format(self, category, id_col_nm="Wormbase.ID"):
+        """ Convert an annotation dataframe category to GMT format. """
+        category_col = f"Category.{category}"
+        id_col = "Function.ID"
+                
+        category_df = self.annotations_df[[id_col_nm, category_col]]
+        category_df = category_df.rename(columns={category_col: id_col})
+        
+        # Validate that required columns exist
+        required_cols = [id_col, id_col_nm]        
+        missing_cols = [col for col in required_cols if col not in category_df.columns]
+        if missing_cols:
+            raise WormcatError(f"Incorrect column names: {', '.join(missing_cols)} {self.annotation_name()} file does not have these columns.", 
+                                ErrorCode.MISSING_FIELD.to_dict())
+        
+        if category_df[id_col].isna().any():
+            raise WormcatError(f"{self.annotation_name()} dataframe Column '{id_col}' contains NaN values", 
+                                ErrorCode.INVALID_VALUE.to_dict())
+        
+        # Use ID column as description if desc_col is None
+        grouped = category_df.groupby([id_col])[id_col_nm].apply(list).reset_index()
+        
+        if len(grouped) == 0:
+            raise WormcatError("No gene sets found after grouping", ErrorCode.INVALID_VALUE.to_dict())
+        
+        # Create GMT formatted dictionary
+        gmt_format = {}
+        for _, row in grouped.iterrows():            
+            # Filter out any None or NaN values from gene list
+            gene_list = [str(gene) for gene in row[id_col_nm] if pd.notna(gene)]
+            
+            # Only include if there are genes in the set
+            if gene_list:
+                gmt_format[row[id_col]] = gene_list
+                
+        return gmt_format
+
+    def _save_gmt_to_file(self, gmt_format, output_file_path='wormcat.gmt'):
+        """ Write GMT formatted dictionary to disk. """
+        # Ensure the output directory exists
+        output_dir_path = os.path.dirname(output_file_path)
+        file_util.validate_directory_path(output_dir_path, not_empty_check = False) 
+        
+        # Write to GMT file
+        with open(output_file_path, 'w') as file:
+            for gene_id, gene_list in gmt_format.items():
+                description = gene_id
+                line = f"{gene_id}\t{description}\t" + '\t'.join(gene_list)
+                file.write(line + '\n')
+        
+        if not os.path.exists(output_file_path):
+            print(f"[Warning] Output file {output_file_path} was not created.")
+        elif os.path.getsize(output_file_path) == 0:
+            print(f"[Warning] Output file {output_file_path} is empty.")
+        else:
+            print(f"Successfully created GMT file: {output_file_path}")
+        
+        return output_file_path

wormcat3/bubble_chart.py

@@ -0,0 +1,240 @@
+# cSpell:ignore ggplot ggtitle ylim darkred orangered dimgray
+
+import matplotlib
+matplotlib.use('Agg') 
+
+import pandas as pd
+import numpy as np
+from plotnine import (
+    ggplot, aes, geom_point, ggtitle, labs, ylim, coord_flip,
+    scale_color_manual, scale_size_manual,
+    theme, element_blank, element_rect, element_text
+)
+from pathlib import Path
+import wormcat3.constants as cs
+import warnings
+from wormcat3.wormcat_error import WormcatError, ErrorCode
+
+# Suppress UserWarnings and DeprecationWarnings from plotnine
+warnings.filterwarnings('ignore', category=UserWarning, module='plotnine')
+warnings.filterwarnings('ignore', category=DeprecationWarning, module='plotnine')
+warnings.filterwarnings('ignore', module="matplotlib.font_manager")
+    
+def preprocess_bubble_data(data_file_path, add_calibration=False):
+    """
+    Preprocess CSV data for bubble plot visualization.
+    
+    Args:
+        csv_file_name (str): Path to the CSV file containing the data.
+        
+    Returns:
+        pd.DataFrame: Processed DataFrame ready for plotting.
+    """
+    try:
+        # Read the CSV file
+        bubbles_data = pd.read_csv(data_file_path)
+        column_names = bubbles_data.columns.tolist()
+        correction_method = 'Bonferroni' if 'Bonferroni' in column_names else 'FDR'
+        
+        # Remove rows with missing values
+        bubbles_data = bubbles_data.dropna()
+        
+        # # Add calibration points
+        if add_calibration:
+            calibration_points = pd.DataFrame({
+                "Category": ["calibration high", "calibration low"],
+                "RGS": [250, 1],
+                "AC": [0, 0],
+                "PValue": [1.00E-50, 1],
+                correction_method: [1.00E-50, 1]
+            })
+            bubbles_data = pd.concat([bubbles_data, calibration_points], ignore_index=True)
+        
+        # Compute normalized value as a placeholder
+        scale_for_visualization=0.001
+        bubbles_data['bubbles_z'] = round(scale_for_visualization * (bubbles_data['PValue'] - bubbles_data['PValue'].mean()) / bubbles_data['PValue'].std(), 2)
+        
+        # Create color coding based on Bonferroni-corrected p-values
+        conditions = [     
+            (bubbles_data[correction_method] < 1e-40),
+            (bubbles_data[correction_method] < 1e-20),
+            (bubbles_data[correction_method] < 1e-10),
+            (bubbles_data[correction_method] < 1e-5),
+            (bubbles_data[correction_method] < 1e-2),
+            (bubbles_data[correction_method] < 5e-2),
+            (bubbles_data[correction_method] >= 5e-2)
+        ]
+        
+        values = ["Col1", "Col2", "Col3", "Col4", "Col5", "Col6", "NS"]
+        bubbles_data['p_value_type'] = np.select(conditions, values, default='')
+
+        
+        # Create size coding based on RGS values
+        size_conditions = [
+            (bubbles_data['RGS'] > 150),
+            (bubbles_data['RGS'] > 100),
+            (bubbles_data['RGS'] > 75),
+            (bubbles_data['RGS'] > 50),
+            (bubbles_data['RGS'] > 25),
+            (bubbles_data['RGS'] > 10),
+            (bubbles_data['RGS'] > 5),
+            (bubbles_data['RGS'] > 2),
+            (bubbles_data['RGS'] <= 2)
+        ]
+        
+        size_values = ["Size1", "Size2", "Size3", "Size4", "Size5", "Size6", "Size7", "Size8", "Size9"]
+        bubbles_data['RGS_size'] = np.select(size_conditions, size_values, default='')
+        
+        bubbles_data = order_categories_by_column(
+            bubbles_data, 
+            category_column = 'Category', 
+            order_by_column = correction_method, 
+            ascending=False
+        )
+        
+        return bubbles_data
+        
+    except FileNotFoundError:
+        raise WormcatError(f"Error/Warning in create Bubble Chart: CSV file not found: {data_file_path}", ErrorCode.FILE_NOT_FOUND.to_dict())
+    except pd.errors.EmptyDataError:
+        raise WormcatError(f"Error/Warning in create Bubble Chart: The CSV file is empty: {data_file_path}", ErrorCode.FILE_LOAD_FAILED.to_dict())
+    except pd.errors.ParserError:
+        raise WormcatError(f"Error/Warning in create Bubble Chart: Error parsing CSV file: {data_file_path}", ErrorCode.FILE_LOAD_FAILED.to_dict())
+    except KeyError as e:
+        raise WormcatError(f"Error/Warning in create Bubble Chart: Required column missing in CSV file: {e}", ErrorCode.FILE_LOAD_FAILED.to_dict())
+
+
+def order_categories_by_column(df, category_column='Category', order_by_column='PValue', ascending=True):
+    """
+    Convert a column to a categorical type ordered by another column.
+    
+    Args:
+        df (pd.DataFrame): DataFrame with category and ordering columns.
+        category_column (str): Name of the column to be converted to categorical.
+        order_by_column (str): Name of the column to order by.
+        ascending (bool): Sort order - True for ascending, False for descending.
+        
+    Returns:
+        pd.DataFrame: DataFrame with category column converted to categorical type.
+    """
+    if df is None or df.empty:
+        raise WormcatError("While creating bubble plot found DataFrame empty or None", ErrorCode.INVALID_STATE.to_dict())
+        
+    if category_column not in df.columns:
+        raise WormcatError(f"While creating bubble plot required column '{category_column}' not found in DataFrame",ErrorCode.INVALID_STATE.to_dict())
+        
+    if order_by_column not in df.columns:
+        raise WormcatError(f"While creating bubble plot required column '{order_by_column}' not found in DataFrame",ErrorCode.INVALID_STATE.to_dict())
+    
+    # Sort the dataframe by the specified column
+    sorted_df = df.sort_values(by=order_by_column, ascending=ascending)
+    
+    # Get the categories in the order determined by the sorting column
+    category_order = sorted_df[category_column].unique()
+    
+    # Convert category column to categorical type with the specified order
+    df[category_column] = pd.Categorical(
+        df[category_column], 
+        categories=category_order,
+        ordered=True
+    )
+    
+    return df
+    
+def generate_bubble_plot(df, svg_file_path, plot_title=cs.DEFAULT_TITLE, width=cs.DEFAULT_WIDTH, height=cs.DEFAULT_HEIGHT):
+    """
+    Generate and save a bubble plot as an SVG using plotnine.
+
+    """
+    if df is None or df.empty:
+        raise WormcatError("While Generating Bubble Plot found DataFrame empty or None", ErrorCode.INVALID_STATE.to_dict())
+        
+    required_columns = ['Category', 'bubbles_z', 'RGS_size', 'p_value_type']
+    missing_columns = [col for col in required_columns if col not in df.columns]
+    if missing_columns:
+        raise WormcatError(f"While Generating Bubble Plot found required columns missing in DataFrame: {missing_columns}", ErrorCode.MISSING_FIELD.to_dict())
+
+    # Define color and size mapping dictionaries
+    color_mapping = {
+        "Col1": "darkred",
+        "Col2": "orangered",
+        "Col3": "tomato",
+        "Col4": "orange",
+        "Col5": "gold",
+        "Col6": "yellow",
+        "NS": "dimgray"
+    }
+    
+    size_mapping = {
+        "Size1": 10,
+        "Size2": 9,
+        "Size3": 8,
+        "Size4": 7,
+        "Size5": 6,
+        "Size6": 5,
+        "Size7": 2.5,
+        "Size8": 1,
+        "Size9": 0.1
+    }
+
+    # Manual color and size scales
+    color_scale = scale_color_manual(
+        name="P value",
+        labels=["10-40", "10-20", "10-10", "10-5", "0.001", "0.05", "NS"],
+        values=color_mapping,
+        limits=list(color_mapping.keys())
+    )
+
+    size_scale = scale_size_manual(
+        name="Count",
+        labels=["150", "100", "75", "50", "25", "10", "5", "2", "Zero"],
+        values=size_mapping,
+        limits=list(size_mapping.keys())
+    )
+
+    # Build the plot
+    p = (
+        ggplot(df, aes(x='Category', y='bubbles_z', size='RGS_size', color='p_value_type')) +
+        ggtitle(title=plot_title) +
+        geom_point(stat='identity') +
+        color_scale +
+        size_scale +
+        labs(y=' ') +
+        ylim(-1.0, 1.0) +
+        coord_flip() +
+        theme(
+            panel_grid=element_blank(),
+            panel_background=element_blank(),
+            legend_key=element_rect(fill="white", color="white"),
+            text=element_text(family="Arial", size=14),
+            axis_text_x=element_blank(),   # Remove x-axis tick labels
+            axis_ticks_x=element_blank(),  # Remove x-axis tick marks
+            plot_title=element_text(margin={"b": 3, "units": "lines"})
+        )
+    )
+
+    try:
+        p.save(filename=svg_file_path, format = "svg", width = width, height = height)
+    except Exception as e:
+        raise WormcatError(f"Failed to save plot: {e}", ErrorCode.INTERNAL_ERROR.to_dict())
+
+
+def create_bubble_chart(dir_path: str, data_file_nm: str, plot_title="RGS", add_calibration=False) -> None:
+    try:
+        data_file_path = Path(dir_path) / data_file_nm
+        svg_file_nm = data_file_nm[:-3] + 'svg'
+        svg_file_path = Path(dir_path) / svg_file_nm
+        
+        bubbles_data = preprocess_bubble_data(data_file_path, add_calibration = add_calibration)
+        
+        # Scale the height of the bubble chart based on the number of items
+        bubbles_data_len = len(bubbles_data)
+        height_fun = lambda x: min(0.1 * x + 6.3, 25)
+        height = height_fun(bubbles_data_len)
+        
+        generate_bubble_plot(bubbles_data, svg_file_path, plot_title = plot_title, height=height, width=9)
+    except Exception as e:
+        print(f"Error: {e}")
+
+
+    

wormcat3/constants.py

@@ -0,0 +1,33 @@
+from enum import Enum
+
+# Enum for p-value adjustment methods
+class PAdjustMethod(Enum):
+    BONFERRONI = 'bonferroni'
+    FDR = 'fdr_bh'
+    
+    @classmethod
+    def from_str(cls, value: str) -> "PAdjustMethod":
+        for method in cls:
+            if method.value == value:
+                return method
+        raise ValueError(f"Invalid PAdjustMethod: {value}")
+
+    
+# Wormcat Configuration
+DEFAULT_WORKING_DIR_PATH = "./wormcat_out"
+DEFAULT_RUN_PREFIX = "run"
+
+# Annotations Management Configuration
+DEFAULT_P_ADJUST_THRESHOLD = 0.05
+DEFAULT_ANNOTATION_FILE_NAME = "whole_genome_v2_nov-11-2021.csv"
+
+# Gene Set Enrichment Analysis
+DEFAULT_GSEA_RESULTS_DIR = "./gsea_results"
+
+GENE_TYPE_WORMBASE_ID = "Wormbase.ID"
+GENE_TYPE_SEQUENCE_ID = "Sequence.ID"
+
+# Bubble Chart Configuration
+DEFAULT_TITLE = "RGS"
+DEFAULT_WIDTH = 6
+DEFAULT_HEIGHT = 5.5