added documentation

bioprocessnexus/__init__.py

@@ -1 +1,24 @@
+"""
+bioprocessnexus package
+
+This package provides tools and modules for processing, analyzing, and managing techno economic bioprocess data.
+It includes functions and classes for data management, model training, prediction, performance 
+evaluation, and SHAP explanations.
+
+Modules:
+    - data_management: Functions for managing and processing data.
+    - explanations: Tools for generating SHAP explanations.
+    - helpers: Utility functions for various tasks.
+    - hist: Functions related to histogram processing and analysis.
+    - interact_hist: Interactive histogram functionalities.
+    - main: The main execution script.
+    - mc_subsampling: Monte Carlo subsampling utilities.
+    - model_training: Tools for training predictive models.
+    - optimizer: Optimization of model responses.
+    - performance_eval: Functions for evaluating model performance.
+    - prediction_making: Functions for making predictions with trained models.
+    - scaling_performance: Utilities for data scaling and performance testing.
+
+"""
+
 from .main import launch_nexus

bioprocessnexus/data_managment.py

@@ -11,6 +11,18 @@
 
 
 def set_file_dir(parent):
+    """
+    Prompts the user to select a data file (CSV or Excel) and loads it into the application.
+
+    Args:
+        parent: The main application instance
+
+    This function displays an information box, resets some attributes in parent,
+    opens a file dialog for selecting a CSV or Excel file, reads the file, and
+    processes it into the application's data structure. It performs checks to ensure
+    data format and compatibility.
+    """
+
     tk.messagebox.showinfo(
         "Information", "Plase select the file containing the data.")
     parent.model_loaded = 0
@@ -73,10 +85,29 @@ def set_file_dir(parent):
 
 
 def bool_switch(parent, name):
+    """
+    Sets the feature selection for a specific feature to "0" in the application's selection interface.
+
+    Args:
+        parent: The main application instance
+        name: The name of the feature whose selection is being modified.
+
+    This function directly modifies the "feature_selection" attribute in "parent".
+    """
     parent.feature_selection[name].set("0")
 
 
 def choose_y(parent):
+    """
+    Opens a window to allow the user to select response and feature variables from the loaded data.
+
+    Args:
+        parent: The main application instance
+
+    This function checks if data is loaded, then generates a new window where the user
+    can specify which columns to use as responses or features. This selection is stored
+    within the application and influences further analysis or model building.
+    """
     if hasattr(parent, "data") is False:
         tk.messagebox.showerror("Error message", "No data has been loaded.")
     else:
@@ -152,6 +183,16 @@ def choose_y(parent):
 
 
 def fix_selection(parent):
+    """
+    Finalizes the selected features and responses for the application, applying user choices to the main instance.
+
+    Args:
+        parent: The main application instance
+
+    The function converts selected features and responses into boolean arrays and
+    stores them in the parent instance for further processing. Checks if at least one
+    response and one feature are selected, otherwise shows an error message.
+    """
     parent.response_bool_vars = np.zeros(len(parent.response_selection))
     parent.feature_bool_vars = np.zeros(len(parent.feature_selection))
 
@@ -185,6 +226,17 @@ def fix_selection(parent):
 
 
 def mix_models(parent):
+    """
+    Allows the user to generate a mixture of experts model by combining multiple models from a specified directory.
+
+    Args:
+        parent: The main application instance
+
+    This function prompts the user to select a directory containing model links, then
+    reads available models and responses, populates a GUI window where the user can
+    specify which models to include in the mixture. Finalizes the model combination by
+    allowing a model name input.
+    """
     parent.mix_dir = ctk.filedialog.askdirectory(
         title="Select model_links folder")
     parent.mix_dir = str.rsplit(parent.mix_dir, "/", 1)[0]+"/data"
@@ -280,6 +332,17 @@ def mix_models(parent):
 
 
 def save_mixture_model(parent):
+    """
+    Saves the configured mixture model, verifying model compatibility and storing it in a specified directory.
+
+    Args:
+        parent: The main application instance
+
+    This function checks feature compatibility across selected models, creates a directory
+    for the new mixture model, and saves model-specific data in a consistent format. It
+    then loads the new model for immediate use in the application.
+    """
+
     if parent.mix_model_name.get() == "":
         cur_datetime = datetime.now().strftime("%m_%d_%Y_%H_%M")
         mix_model_name = "mixed_model_"+cur_datetime
@@ -333,6 +396,15 @@ def save_mixture_model(parent):
 
 
 def choose_model(parent):
+    """
+    Prompts the user to select a .nexus model file and loads the specified model into the application.
+
+    Args:
+        parent: The main application instance
+
+    This function validates the selected file format and path, loads feature selections,
+    and stores relevant data within the "parent" instance for use in subsequent analysis.
+    """
     tk.messagebox.showinfo(
         "Information", "Please select .nexus file from the folder ~/model_links.")
     link_dir = ctk.filedialog.askopenfilename(
@@ -357,4 +429,3 @@ def choose_model(parent):
             parent.y_names.append(response)
     tk.messagebox.showinfo("Information",
                            f"{model_name} loaded.")
-

bioprocessnexus/explanations.py

@@ -16,6 +16,15 @@
 
 
 def make_explanation(parent):
+    """
+    Initializes the SHAP explanation window, prompting the user to enter a fraction of samples to analyze.
+
+    Args:
+        parent: The main application instance
+
+    Raises:
+        Displays an error message if no model has been loaded.
+    """
     if parent.model_loaded == 0:
         tk.messagebox.showerror("Error message", "No model has been loaded.")
     else:
@@ -52,6 +61,16 @@ def make_explanation(parent):
 
 
 def plot_explanation(parent):
+    """
+    Generates and displays SHAP explanations for model predictions on a fraction of the test dataset.
+
+    Args:
+        parent: The main application instance
+
+    This function loads the model, computes SHAP values using KernelExplainer, and plots the explanations
+    for each response variable. It handles memory errors gracefully by prompting the user to reduce
+    the number of samples if necessary.
+    """
     if parent.fraction.get() == "":
         tk.messagebox.showerror("Error message", "The fraction hasn´t been specified.",
                                 parent=parent.exp_window)
@@ -246,10 +265,19 @@ def plot_explanation(parent):
 
 
 def denormalized_prediction(data_in, parent):
+    """
+    Makes predictions on normalized input data and denormalizes the output.
+
+    Args:
+        data_in (numpy array): Normalized input data for the model.
+        parent: The main application instance
+
+    Returns:
+        data_out: A numpy array of denormalized predictions.
+    """
     preds = parent.model.predict(data_in)
     # Vectorize predictions in case they are not
     if len(preds.shape) != 1:
         preds = preds[:, 0]
     data_out = denormalize(preds, parent.y_mus, parent.y_stds)
     return data_out
-

bioprocessnexus/helpers.py

@@ -5,21 +5,55 @@
 
 
 def normalize(array, mus, stds):
+    """
+    Normalizes the input array by subtracting the mean and dividing by the standard deviation.
+
+    Args:
+        array (numpy array): Array to be normalized.
+        mus (numpy array): Array of means for each feature in "array".
+        stds (numpy array): Array of standard deviations for each feature in "array".
+
+    Returns:
+        normalized_array: Normalized input array
+    """
     normalized_array = (array-mus)/stds
     return normalized_array
 
 
 def denormalize(array, mus, stds):
+    """
+    Reverts normalization by applying mean and standard deviation scaling.
+
+    Args:
+        array (numpy array): Array to be denormalized.
+        mus (numpy array): Array of means used for normalization.
+        stds (numpy array): Array of standard deviations used for normalization.
+
+    Returns:
+        denormalized_array: Denormalized input array
+    """
     denormalized_array = array*stds+mus
     return denormalized_array
 
 
 def open_help():
+    """
+    Opens a web browser to the help tutorial URL.
+    """
     webbrowser.open(
         "https://boku.ac.at/rali/stat/testseiten-stat/testseiten-stat-matthias/tutorials")
 
 
 def zip_dir(parent):
+    """
+    Compresses a directory selected by the user into a zip file.
+
+    Args:
+        parent: The main application instance
+
+    This function prompts the user to select a directory, creates a zip file with the same name,
+    and saves it in the same location.
+    """
     parent.zip_dir = ctk.filedialog.askdirectory()
     if not parent.zip_dir:
         return
@@ -35,6 +69,15 @@ def zip_dir(parent):
 
 
 def unzip_dir(parent):
+    """
+    Extracts a zip file selected by the user into a new directory.
+
+    Args:
+        parent: The main application instance
+
+    This function prompts the user to select a zip file, creates a directory with the same name,
+    and extracts the zip file contents into this directory.
+    """
     parent.unzip_dir = ctk.filedialog.askopenfile(
         filetypes=[(".zip files", "*.zip")]).name
     if os.path.exists(str.rsplit(parent.unzip_dir, ".zip", 1)[0]) is False:
@@ -44,6 +87,15 @@ def unzip_dir(parent):
 
 
 def nice_round(num):
+    """
+    Rounds a number based on its magnitude to provide a concise output.
+
+    Args:
+        num (float): Number to be rounded.
+
+    Returns:
+        float: Rounded number with appropriate precision.
+    """
     if num > 10000:
         return round(num)
     elif num < 10000 and num > 1000:
@@ -65,6 +117,19 @@ def nice_round(num):
 
 
 def check_dir(parent, y_dir, dir_type, central_log=0):
+    """
+    Verifies and creates the necessary directory structure for storing logs or images.
+
+    Args:
+        parent: The main application instance
+        y_dir (str): Directory name for a specific response variable.
+        dir_type (str): Type of directory to create (e.g., "logs", "images").
+        central_log (int, optional): If set to 1, creates only the main directory without nested folders.
+
+    Returns:
+        str: Path to the created directory, if central_log is 0.
+    """
+
     mother_dir = parent.model_dir.rsplit("/", 2)[0]
     model_name = parent.model_dir.rsplit("/")[-1]
     if os.path.exists(f"{mother_dir}/{dir_type}") is False:
@@ -80,4 +145,3 @@ def check_dir(parent, y_dir, dir_type, central_log=0):
 
     if central_log == 0:
         return f"{mother_dir}/{dir_type}/{model_name}/{y_dir}"
-

bioprocessnexus/hist.py

@@ -11,6 +11,15 @@
 
 
 def init_hist(parent):
+    """
+    Initializes the histogram plotting process, including checking for loaded models and initiating plot threads.
+
+    Args:
+        parent: The main application instance
+
+    Raises:
+        Displays an error message if no model has been loaded or if responses and features are not selected.
+    """
     # List of distribution names for distfit
     parent.distfit_distributions = ["alpha", "beta", "gamma", "loggamma", "laplace", "chi2",
                                     "norm", "lognorm", "exponnorm", "gennorm", "powernorm", "t",
@@ -27,6 +36,14 @@ def init_hist(parent):
 
 
 def check_hist_queue(parent):
+    """
+    Monitors the plotting queue for completed histograms and displays them in a new window.
+
+    Args:
+        parent: The main application instance
+
+    This function continues to check the queue until all histograms are plotted.
+    """
     while not parent.queue.empty():
         # Creating a new window for the histogram
         parent.histogram_window = tk.Toplevel(parent)
@@ -45,6 +62,15 @@ def check_hist_queue(parent):
 
 
 def plot_hist(parent):
+    """
+    Generates and saves histograms of response data with fitted probability distributions.
+
+    Args:
+        parent: The main application instance
+
+    This function fits a probability distribution to each response, plots the histogram with fitted distribution,
+    and saves both the plot and distribution parameters.
+    """
     # Checking if a model has been loaded
     if parent.model_loaded == 0:
         parent.model_dir = str.rsplit(parent.filename, "/", 1)[0]+"/data/no_model_" + \
@@ -169,4 +195,3 @@ def plot_hist(parent):
     save_dir = save_dir.rsplit("/", 1)[0]
     tk.messagebox.showinfo(
         "Information", f"Images saved at {img_dir}\nLogs saved at {save_dir}")
-