adding documentation to new functions

Author: alexandriai168

enviroMS/LC_FTICR_workflow.py

@@ -23,6 +23,39 @@
 ################################### LC-FTICR OBJECT AND OBJECT'S METHODS ###################################
 @dataclass
 class LC_FTICR_WorkflowParameters:
+    """
+    Data class to establish workflow parameters.
+
+    Parameters
+    ----------
+    start_time : int
+        Start time (minutes).
+    end_time : int
+        End time (minutes).
+    time_block : int
+        Time block (seconds).
+    refmasslist_neg : str
+        Path to reference m/z database.
+    full_input_file_path : str
+        The path of file to process.
+    output_directory : str
+        Path to save outputs.
+    output_file_name : str
+        Output filename.
+    output_file_type : str
+        Output extension.
+    lc_fticr_toml_path : str
+        The path to the toml file with the lc-fticr ms workflow parameters.
+    corems_toml_path : str
+        The path to the toml file with the CoreMS parameters.
+    do_plot_van_krevelen_all_ids : bool
+        Output van krevelen plot for all ID's
+    do_plot_van_krevelen_individual : bool
+        Output individual van krevelen plot for all ID's
+    do_plot_properties : bool
+        Output plot of properties.
+    """
+
     # Time Block Parameters:
     start_time: int # minutes
     end_time: int # minutes
@@ -79,6 +112,13 @@ def create_temp_corems_toml(self):
 
     ### function that init parser and get data
     def init_parser_extract_data(self) -> pd.DataFrame:
+        """
+        Initialize the parser and extract data from input file.
+        This function reads the input file, extracts the Total Ion Chromatogram (TIC) data,
+        and returns a DataFrame containing the scans, TIC values, and time.
+
+        """
+
         # Define datafile location
         file_in = self.full_input_file_path
 
@@ -103,6 +143,25 @@ def init_parser_extract_data(self) -> pd.DataFrame:
     ### process timeblocks
     # Process the time block mass spectrum
     def proc_time_block_inner(self, msreader, datafile, block):
+        """
+        Process time blocks of mass spectra.
+
+        Parameters:
+        ----------
+        msreader : ImportMassSpectraThermoMSFileReader
+            The mass spectrum reader object.
+        datafile : str
+            The path to the data file.
+        block : int
+            The time block number.
+
+        Returns:
+        -------
+        msdf : pd.DataFrame
+            DataFrame containing the processed mass spectrum data.
+        statdict : dict
+            Dictionary containing statistics for the processed mass spectrum.
+        """
         # scans = list(subset_df['scan'])
 
         # load_and_set_toml_parameters_ms(MSParameters, self.corems_toml_path)
@@ -143,6 +202,21 @@ def proc_time_block_inner(self, msreader, datafile, block):
         return(msdf, statdict)
 
     def process_with_time_block(self, tic_df):
+        """
+        Process the mass spectra with time blocks.
+
+        Parameters:
+        ----------
+        tic_df : pd.DataFrame
+            DataFrame containing the Total Ion Chromatogram (TIC) data with time and scan information.
+        Returns:
+        -------
+        all_msdfs : pd.DataFrame
+            DataFrame containing all processed mass spectra data.
+        all_statdics : list
+            List of dictionaries containing statistics for each time block.
+
+        """
         # Strip out the time where there's no useful data
         file_in = self.full_input_file_path
         tic_df = tic_df[(tic_df['time'] > self.start_time) & (tic_df['time'] < self.end_time)]
@@ -178,6 +252,17 @@ def process_with_time_block(self, tic_df):
 
 
     def create_summary(self, all_statdics):
+        """
+        Create a summary DataFrame from the list of dictionaries containing statistics.
+        Parameters:
+        ----------
+        all_statdics : list
+            List of dictionaries containing statistics for each time block.
+        Returns:
+        -------
+        summary_df : pd.DataFrame
+            DataFrame containing the summary statistics for all time blocks.
+        """
         # Flatten the list of dictionaries
         flat_list = [inner_dict for outer_dict in all_statdics for inner_dict in outer_dict.values()]
         # Create a DataFrame
@@ -191,6 +276,19 @@ def create_summary(self, all_statdics):
 
 ## for creating plots
 def filter_out_common_background(df):
+    """
+    Filter out common background entries in the DataFrame based on 'Molecular Formula' and 'Peak Height'.
+
+    Parameters:
+    ----------
+    df : pd.DataFrame
+        DataFrame containing 'Molecular Formula', 'Peak Height', and 'block' columns.
+    Returns:
+    -------
+    filtered_df : pd.DataFrame
+        DataFrame with common background entries removed.
+    """
+
     formula_block_counts = df.pivot_table(index='Molecular Formula', columns='block', aggfunc='size', fill_value=0)
 
     # Filter to get 'Molecular Formula' entries that appear in all blocks
@@ -214,6 +312,19 @@ def peak_height_similar(df, tolerance=0.99):  # 10% tolerance
 
 ### create plots
 def plot_van_krevelen_all_ids(all_msdfs_path, output_dir):
+    """
+    Plot a van Krevelen diagram for all IDs in the provided DataFrame or CSV file.
+    Parameters:
+    ----------
+    all_msdfs_path : str or pd.DataFrame
+        Path to the CSV file containing all mass spectra data or a DataFrame.
+    output_dir : str
+        Directory where the plot will be saved.
+    Returns:
+    -------
+    None
+    """
+
     if isinstance(all_msdfs_path,str):
         all_msdfs_df = pd.read_csv(all_msdfs_path)
     else:
@@ -240,6 +351,18 @@ def plot_van_krevelen_all_ids(all_msdfs_path, output_dir):
     plt.show()
 
 def plot_van_krevelen_individual(all_msdfs_path, output_dir):
+    """
+    Plot individual van Krevelen diagrams for each time block in the provided DataFrame or CSV file.
+    Parameters:
+    ----------
+    all_msdfs_path : str or pd.DataFrame
+        Path to the CSV file containing all mass spectra data or a DataFrame.
+    output_dir : str
+        Directory where the plots will be saved.
+    Returns:
+    -------
+    None
+    """
     if isinstance(all_msdfs_path,str):
         all_msdfs_df = pd.read_csv(all_msdfs_path)
     else:
@@ -278,6 +401,18 @@ def plot_van_krevelen_individual(all_msdfs_path, output_dir):
     fig.savefig(output_dir+'TimeBlockIDs.png',dpi=300,bbox_inches='tight')
 
 def plot_properties(summary_df_path,output_dir):
+    """
+    Plot trends and distributions of various properties from the summary DataFrame or CSV file.
+    Parameters:
+    ----------
+    summary_df_path : str or pd.DataFrame
+        Path to the CSV file containing summary statistics or a DataFrame.
+    output_dir : str
+        Directory where the plots will be saved.
+    Returns:
+    -------
+    None
+    """
     if isinstance(summary_df_path,str):
         summary_df = pd.read_csv(summary_df_path)
     else:
@@ -314,6 +449,19 @@ def plot_properties(summary_df_path,output_dir):
 ################################### RUN LC-FTICR WORKFLOW ###################################
 
 def run_LC_FTICR_workflow(lc_fticr_workflow_paramaters_toml_file):
+    """
+    Run LC-FTICR metabolomics workflow.
+
+    Parameters
+    ----------
+    lc_fticr_workflow_paramaters_toml_file : str
+        Path to workflow parameters file.
+    Returns
+    -------
+    None
+
+    """
+
     # read in LC_WorkflowParameters from toml file
     with open(lc_fticr_workflow_paramaters_toml_file, "r") as infile:
         lc_object = LC_FTICR_WorkflowParameters(**toml.load(infile))
@@ -345,6 +493,41 @@ def run_LC_FTICR_workflow_wdl(
     do_plot_van_krevelen_individual,
     do_plot_properties,
 ):
+    """
+    Run LC-FTICR metabolomics workflow with parameters from WDL inputs.
+    Parameters
+    ----------
+    start_time : int
+        Start time (minutes).
+    end_time : int
+        End time (minutes).
+    time_block : int
+        Time block (seconds).
+    refmasslist_neg : str
+        Path to reference m/z database.
+    full_input_file_path : str
+        The path of file to process.
+    output_directory : str
+        Path to save outputs.
+    output_file_name : str
+        Output filename.
+    output_file_type : str
+        Output extension.
+    lc_fticr_toml_path : str
+        The path to the toml file with the lc-fticr ms workflow parameters.
+    corems_toml_path : str
+        The path to the toml file with the CoreMS parameters.
+    do_plot_van_krevelen_all_ids : bool
+        Output van krevelen plot for all ID's.
+    do_plot_van_krevelen_individual : bool
+        Output individual van krevelen plot for all ID's.
+    do_plot_properties : bool
+        Output plot of properties.
+
+    Returns
+    -------
+    None
+    """
     # read in LC_WorkflowParameters from wdl inputs
     lc_object = LC_FTICR_WorkflowParameters(start_time = start_time,
                                             end_time = end_time,

enviroMS/cli.py

@@ -121,13 +121,13 @@ def create_database(corems_parameters_file, jobs):
 @click.argument("raw_file_final_scan", required=True, type=int)
 @click.argument("is_centroid", required=True, type=bool)
 @click.argument("calibration_ref_file_path", required=False, type=str)
-@click.option("--calibrate", "-c", default=True)
-@click.option("--plot_mz_error", "-e", default=True)
-@click.option("--plot_ms_assigned_unassigned", "-a", default=True)
-@click.option("--plot_c_dbe", "-cb", default=True)
-@click.option("--plot_van_krevelen", "-vk", default=True)
-@click.option("--plot_ms_classes", "-mc", default=True)
-@click.option("--plot_mz_error_classes", "-ec", default=True)
+@click.option("--calibrate", "-c", default=True, help="Calibrate the raw files")
+@click.option("--plot_mz_error", "-e", default=True, help="Plot m/z error")
+@click.option("--plot_ms_assigned_unassigned", "-a", default=True, help="Plot MS assigned and unassigned")
+@click.option("--plot_c_dbe", "-cb", default=True, help="Plot C vs DBE")
+@click.option("--plot_van_krevelen", "-vk", default=True, help="Plot Van Krevelen diagram")
+@click.option("--plot_ms_classes", "-mc", default=True, help="Plot MS classes")
+@click.option("--plot_mz_error_classes", "-ec", default=True, help="Plot m/z error classes")
 @click.option("--jobs", "-j", default=4, help="'cpu's'")
 def run_di_wdl(*args, **kwargs):
     """Run the Direct Infusion Workflow using wdl"""
@@ -160,7 +160,39 @@ def run_di(di_workflow_paramaters_file, jobs, replicas, tasks, mpi):
 @cli.command(name="run_lc_fticr")
 @click.argument("lc_fticr_workflow_paramaters_file", required=True, type=str)
 def run_lc_fticr(lc_fticr_workflow_paramaters_file):
-    """Run the LC-FTICR workflow"""
+    """Run the LC FTICR MS workflow
+
+    Parameters
+    ----------
+    full_input_file_path : str
+        The path to the toml file with the workflow parameters
+    start_time : int
+        The paths to the input files, separated by commas as one string
+    end_time : int
+        The directory where the output files will be stored
+    time_block : int
+        The path corems parameters toml file
+    refmasslist_neg : str
+        The path to the sqlite database for spectra searching
+    output_directory : str
+        The path to the scan translator file
+    output_file_name : str
+        The number of cores to use for processing
+    output_file_type : str
+        The number of cores to use for processing
+    lc_fticr_toml_path : str
+        The number of cores to use for processing
+    corems_toml_path : str
+        The number of cores to use for processing
+    do_plot_van_krevelen_all_ids : bool
+        The number of cores to use for processing
+    do_plot_van_krevelen_individual : bool
+        The number of cores to use for processing
+    do_plot_properties : bool
+        The number of cores to use for processing
+
+    """
+
     run_LC_FTICR_workflow(lc_fticr_workflow_paramaters_file)
 
 
@@ -175,9 +207,9 @@ def run_lc_fticr(lc_fticr_workflow_paramaters_file):
 @click.argument("output_file_type", required=True, type=str)
 @click.argument("lc_fticr_toml_path", required=True, type=str)
 @click.argument("corems_toml_path", required=True, type=str)
-@click.option("--do_plot_van_krevelen_all_ids", "-a", default=True)
-@click.option("--do_plot_van_krevelen_individual", "-i", default=True)
-@click.option("--do_plot_properties", "-p", default=True)
+@click.option("--do_plot_van_krevelen_all_ids", "-a", default=True, help="Creates Van Krevelen plots for all ids.")
+@click.option("--do_plot_van_krevelen_individual", "-i", default=True, help="Creates Van Krevelen plots for all ids individually.")
+@click.option("--do_plot_properties", "-p", default=True, help="Creates plots of properties for run.")
 def run_lc_fticr_wdl(
     full_input_file_path,
     start_time,
@@ -193,7 +225,38 @@ def run_lc_fticr_wdl(
     do_plot_van_krevelen_individual,
     do_plot_properties,
 ):
-    """Run the LC-FTICR Workflow using wdl"""
+    """
+    Run the LC FTICR MS workflow using WDL.
+
+    Parameters
+    ----------
+    full_input_file_path : str
+        The path to the input file containing LC-FTICR data
+    start_time : float
+        The start time for the LC-FTICR analysis
+    end_time : float
+        The end time for the LC-FTICR analysis
+    time_block : float
+        The time block for processing the LC-FTICR data
+    refmasslist_neg : str
+        The path to the reference mass list for negative ion mode
+    output_directory : str
+        The directory where the output files will be stored
+    output_file_name : str
+        The name of the output file to be generated
+    output_file_type : str
+        The type of the output file (e.g., csv, json)
+    lc_fticr_toml_path : str
+        The path to the LC-FTICR workflow parameters file in TOML format
+    corems_toml_path : str
+        The path to the CoreMS parameters file in TOML format
+    do_plot_van_krevelen_all_ids : bool
+        Whether to create Van Krevelen plots for all IDs
+    do_plot_van_krevelen_individual : bool
+        Whether to create individual Van Krevelen plots for each ID
+    do_plot_properties : bool
+        Whether to create plots of properties for the run
+    """
     click.echo("Running lc-fticr workflow")
     run_LC_FTICR_workflow_wdl(
         full_input_file_path = full_input_file_path,