improved docs

Author: palec87

docs/api.rst

@@ -52,7 +52,7 @@ This module offers methods for calculating and analyzing biodiversity metrics fr
     :show-inheritance:
 
 Galaxy integration
-==================
+===================
 This module enables integration with the Galaxy platform for workflow automation and reproducibility. We keep it minimalistic, because we expect to use direct install of Galaxy once demos are deployed in the final VRE.
 
 .. automodule:: momics.galaxy
@@ -62,7 +62,7 @@ This module enables integration with the Galaxy platform for workflow automation
 Panel dashboard module
 ========================
 This module provides some of the utilities for building interactive dashboards using the Panel library. These are Specific
-for FAIR-EASE use case and more methods and widgets can be found directly in the demo workflow notebooks [here](https://github.com/emo-bon/momics-demos).
+for FAIR-EASE use case and more methods and widgets can be found directly in the demo workflow notebooks `here <https://github.com/emo-bon/momics-demos>`_.
 
 .. automodule:: momics.panel_utils
     :members:
@@ -85,7 +85,7 @@ This module provides tools for handling and analyzing taxonomic information in o
     :show-inheritance:
 
 Utilities of all sorts
-==================
+=========================
 This module contains miscellaneous utility functions used throughout the momics package.
 
 .. automodule:: momics.utils

docs/index.rst

@@ -4,12 +4,12 @@ Marine omics methods
 
 These package currently supports FAIR-EASE `pilot demos <https://github.com/emo-bon/momics-demos>`_, but eventually it can serve for general purpose manipulation of metagenomic data, locally and in VREs.
 
-The idea is to provide testable methods to allow as much flexibility and remixing of the functionalities provided
+The idea is to provide testable methods to allow as much flexibility and remixing of the functionalities provided.
 
-European Marine Omics Biodiversity Observation Network
+EMO-BON
 ===========================================================
 
-Specifically, we aim primarily to manipulate EMO-BON marine genomics sampling data and metadata from ENA project `PRJEB51688 <https://www.ebi.ac.uk/ena/browser/view/PRJEB51688>`_. The interactive dashboards and jupyter notebooks built on top of this repository can be found `here <https://github.com/emo-bon/momics-demos/tree/main>`_.
+Specifically, we aim primarily to manipulate European Marine Omics Biodiversity Observation Network (EMO-BON) sampling data and metadata from ENA project `PRJEB51688 <https://www.ebi.ac.uk/ena/browser/view/PRJEB51688>`_. The interactive dashboards and jupyter notebooks built on top of this repository can be found `here <https://github.com/emo-bon/momics-demos/tree/main>`_.
 
 The methods are mixture of statistical methods, plotting functionalities, metadata and data handling utilities and generators of `holoviz panel` widgets and panes. Experimental integration to `Galaxy` uses a wrapper around `bioblend <https://bioblend.readthedocs.io/en/latest/>`_.
 

momics/diversity.py

@@ -232,12 +232,16 @@ def beta_diversity_parametrized(
 # helper functions #
 ####################
 def update_subset_indicator(indicator, df):
-    """Update the subset indicator with the number of unique `index`_ids."""
+    """
+    Update the subset indicator with the number of unique `index` ids.
+    """
     indicator.value = df.index.nunique()
 
 
 def update_taxa_count_indicator(indicator, df):
-    """Update the taxa count indicator with the number of unique taxa."""
+    """
+    Update the taxa count indicator with the number of unique taxa.
+    """
     indicator.value = df.index.nunique()
 
 

momics/galaxy/gecco.py

@@ -6,7 +6,23 @@
 
 
 class Gecco:
+    """
+    A class to interact with the GECCO tool in the Galaxy platform for comparative genomics.
+
+    This class manages user authentication, history and dataset selection, file uploads,
+    and submission of jobs to the GECCO tool via the Galaxy API.
+
+    Args:
+        params (dict): Dictionary of Panel widgets and parameters required for interaction.
+    """
+
     def __init__(self, params):
+        """
+        Initialize the Gecco class with user parameters and Galaxy connection.
+
+        Args:
+            params (dict): Dictionary containing Panel widgets and configuration parameters.
+        """
         self.exp = RemGalaxy("GALAXY_EARTH_URL", "GALAXY_EARTH_KEY")
         self.logger = self.exp.logger
         self.gecco_tool_id = "gecco"
@@ -31,19 +47,28 @@ def __init__(self, params):
         self.debug = False
 
     def handle_login(self, clicks):
+        """
+        Handles user login and retrieves relevant data.
+
+        Args:
+            clicks (int): Number of times the login button has been clicked.
+        """
         pn.state.notifications.info(f"User logged in: {self.exp.cfg.whoami()}")
         self.logger.info(f"You have clicked me {clicks} times")
         self.handle_get_histories(clicks)
-
-        # get the datasets right upon login
         self.handle_get_datasets(clicks)
 
     def handle_get_histories(self, clicks):
+        """
+        Retrieves the user's Galaxy histories and updates the selection widget.
+
+        Args:
+            clicks (int): Number of times the login button has been clicked.
+        """
         self.exp.get_histories()
 
         # clean histories dict for display, remove deleted histories and select fust relevant fields
         clean_histories = self.exp.clean_histories_for_display()
-
         self.select_history.options = clean_histories
         self.select_history.value = clean_histories[0]
         self.logger.info(f"{len(clean_histories)} histories found.")
@@ -53,7 +78,12 @@ def handle_get_histories(self, clicks):
         self.handle_update_current_history_id(self.select_history.value)
 
     def handle_get_datasets(self, clicks):
-        # filtering seems too narrow or too broad, not sure what to do about it, but broad is better
+        """
+        Retrieves available datasets from Galaxy and updates the selection widget.
+
+        Args:
+            clicks (int): Number of times the login button has been clicked.
+        """
         datasets, *_ = self.exp.get_datasets_by_key(
             "extension", ["fasta", "gbk", "embl", "genbank", "gb"]
         )
@@ -74,30 +104,46 @@ def handle_get_datasets(self, clicks):
             self.logger.info(
                 f"Datasets selector value[1]: {self.select_dataset.value[1]}"
             )
-        # this is the id of the dataset
         self.handle_update_current_file_name(self.select_dataset.value)
-
         self.logger.info(f"{len(datasets)} datasets found.")
 
     def handle_update_current_file_name(self, value):
+        """
+        Updates the current file name and ID based on the selected dataset.
+
+        Args:
+            value (tuple): Tuple containing the file name and file ID.
+        """
         self.current_file_name.value = value[0]
         self.current_file_id.value = value[1]
 
     def handle_update_current_history_name(self, value):
+        """
+        Updates the current history name based on the selected history.
+
+        Args:
+            value (dict): Dictionary containing history information.
+        """
         self.current_history_name.value = value["name"]
 
     def handle_update_current_history_id(self, value):
-        self.current_history_id.value = value["id"]
+        """
+        Updates the current history ID based on the selected history.
 
-    def handle_update_current_file_name(self, value):
-        self.current_file_name.value = value[0]
-        self.current_file_id.value = value[1]
+        Args:
+            value (dict): Dictionary containing history information.
+        """
+        self.current_history_id.value = value["id"]
 
     def handle_create_history(self, clicks):
-        # this supresses history creation upon startup
+        """
+        Creates a new history in Galaxy if requested by the user.
+
+        Args:
+            clicks (int): Number of times the create history button has been clicked.
+        """
         if clicks == 0:
             return
-
         if self.history_name.value != "":
             self.exp.set_history(hname=self.history_name.value)
         else:
@@ -107,6 +153,12 @@ def handle_create_history(self, clicks):
         self.handle_get_histories(clicks)
 
     def handle_upload_dataset(self, clicks):
+        """
+        Uploads a dataset to Galaxy if the user chooses to upload from local source.
+
+        Args:
+            clicks (int): Number of times the upload button has been clicked.
+        """
         if self.file_source_checkbox.value:
             pn.state.notifications.warning("You selected Galaxy source and not upload.")
         else:
@@ -123,7 +175,6 @@ def handle_upload_dataset(self, clicks):
                 != "ok"
             ):
                 time.sleep(1)
-
             self.logger.info(f"Upload data: {upload_data}")
             uploaded_dataset_id = upload_data["outputs"][0]["id"]
             self.current_file_name.value = upload_data["outputs"][0]["name"]
@@ -132,15 +183,19 @@ def handle_upload_dataset(self, clicks):
             self.logger.info(f"Dataset {uploaded_dataset_id} uploaded.")
 
     def handle_submit_gecco(self, clicks):
+        """
+        Submits a job to the GECCO tool in Galaxy with the selected parameters.
+
+        Args:
+            clicks (int): Number of times the submit button has been clicked.
+        """
         if clicks == 0:
             pn.state.notifications.warning("You need to log in first.")
             return
-
         if self.current_file_id.value == "":
             pn.state.notifications.warning("No dataset selected.")
             self.logger.warning("No dataset selected.")
             return
-
         if self.current_history_id.value == "":
             pn.state.notifications.warning("No history selected.")
             self.logger.warning("No history selected.")

momics/plotting.py

@@ -1,28 +1,12 @@
 """
-This module contains functions for plotting alpha and beta diversity results.
-
-Functions:
-- hvplot_alpha_diversity: Creates a horizontal bar plot for alpha diversity using hvplot.
-- plot_pcoa_black: Plots a PCoA plot with optional coloring.
-- mpl_alpha_diversity: Plots the Shannon index grouped by a factor.
-- mpl_average_per_factor: Plots the average Shannon index grouped by a factor.
-- mpl_bgcs_violin: Creates a violin plot for BGC probabilities by type.
-- alpha_plot: Creates an alpha diversity plot.
-- av_alpha_plot: Creates an average alpha diversity plot.
-- beta_plot: Creates a beta diversity heatmap plot.
-- beta_plot_pc: Creates a beta diversity PCoA plot.
-- beta_plot_pc_granular: Creates a beta diversity PCoA plot for granular data.
-- mpl_plot_heatmap: Creates a heatmap plot for beta diversity.
-- fold_legend_labels_from_series: Folds a list of labels to a maximum length from a Series.
-- change_legend_labels: Changes the labels of a legend on a given matplotlib axis.
-- cut_xaxis_labels: Changes the x-tick labels by cutting them short.
-- get_sankey: Creates a Sankey diagram using Plotly.
-
-Constants:
-- PLOT_FACE_COLOR: The face color for the plot.
-
-TODO: returns should be plt.figure and not pn.pane.Matplotlib, as already
-implemented for beta_plot_pc() function.
+
+Constants
+---------
+- PLOT_FACE_COLOR : str
+    The face color for the plot.
+
+TODO:
+- Returns should be plt.figure and not pn.pane.Matplotlib, as already implemented for beta_plot_pc() function.
 """
 
 import logging

momics/taxonomy.py

@@ -90,17 +90,20 @@ def pivot_taxonomic_data(df: pd.DataFrame) -> pd.DataFrame:
 
 def normalize_abundance(
     df: pd.DataFrame, method: str = "tss_sqrt", rarefy_depth: int = None
-):
+) -> pd.DataFrame:
     """
     Normalize the abundance DataFrame using specified method.
+
     Args:
         df (pd.DataFrame): The input DataFrame containing taxonomic information.
         method (str): Normalization method. Options: 'tss', 'tss_sqrt', 'rarefy'.
             Defaults to 'tss_sqrt'.
         rarefy_depth (int, optional): Depth for rarefaction. If None, uses min sample sum.
             Defaults to None.
+    
     Returns:
         pd.DataFrame: A DataFrame with normalized abundance values.
+    
     Raises:
         IndexError: If the DataFrame does not have a multiindex with 'taxonomic_concat' and 'ncbi_tax_id'.
         TypeError: If the DataFrame does not contain numeric values for normalization.