data-visualiser-package 0.1.0__py3-none-any.whl

data_visualiser_package/__init__.py

@@ -0,0 +1,12 @@
+"""
+Data Visualiser Package
+
+A utility package for visualizing and analyzing data with Matplotlib and Seaborn.
+Creates plots and statistics tables for data exploration and presentation.
+"""
+
+__version__ = "0.1.0"
+
+from .data_visualiser import DataVisualiser, categorise_variable_in_df, uncategorise
+
+__all__ = ["DataVisualiser", "categorise_variable_in_df", "uncategorise"]

data_visualiser_package/data_visualiser.py

@@ -0,0 +1,643 @@
+"""
+Data Visualiser Package
+
+A utility package for visualizing and analyzing data with Matplotlib and Seaborn.
+Creates plots and statistics tables for data exploration and presentation.
+
+Quick import example:
+```python
+from data_visualiser_package import DataVisualiser
+dv = DataVisualiser()
+
+
+```
+"""
+import os
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple, Union
+
+import matplotlib.pyplot as plt
+import numpy as np
+import pandas as pd
+import seaborn as sns
+
+from .export_latex_tables import get_latex_table_bold_col_header, get_n_decimals_to_include
+
+# Constants
+RECORD_UNIT_NAME = "patient"  # What a single record represents (e.g., patient in clinical data)
+NAN_REPLACEMENT_STR = "NaN"   # String to use when replacing NaN values for display
+HEIGHT = 4                    # Default plot height in inches
+
+
+def uncategorise(col: pd.Series) -> pd.Series:
+    """
+    Convert categorical columns back to their original data types.
+    
+    Args:
+        col: The pandas Series to convert
+        
+    Returns:
+        The uncategorized pandas Series
+    """
+    if col.dtype.name == "category":
+        try:
+            return col.astype(col.cat.categories.dtype)
+        except:
+            # In case there is pd.NA (pandas >= 1.0), Int64 should be used instead of int64
+            return col.astype(col.cat.categories.dtype.name.title())
+    else:
+        return col
+
+
+def categorise_variable_in_df(
+    var: str, 
+    df: pd.DataFrame, 
+    forced_order: Optional[List[str]] = None, 
+    nan_replacement_str: str = NAN_REPLACEMENT_STR
+) -> None:
+    """
+    Categorize a variable in a DataFrame, handling NaN values and custom ordering.
+    
+    Args:
+        var: Variable name to categorize
+        df: DataFrame containing the variable
+        forced_order: Optional custom ordering of categories
+        nan_replacement_str: String used to replace NaN values
+        
+    Note:
+        This function modifies the DataFrame in-place.
+    """
+    if (df[var] == nan_replacement_str).any():
+        if forced_order is not None:
+            assert (set(df[var]) - {nan_replacement_str}).issubset(
+                forced_order
+            ), f"forced_order for var {var} is incomplete: {(set(df[var]) - set([nan_replacement_str])) - set(forced_order)}"
+            categories = forced_order + [nan_replacement_str]
+        else:
+            categories = sorted(set(df[var].unique()) - {nan_replacement_str}) + [
+                nan_replacement_str
+            ]
+    else:
+        if forced_order is not None:
+            assert (set(df[var]) - {np.nan}).issubset(
+                forced_order
+            ), f"forced_order for var {var} is incomplete: {(set(df[var]) - set([np.nan])) - set(forced_order)}"
+            categories = forced_order
+        else:
+            categories = sorted(set(df[var]) - {np.nan})
+
+    df[var] = pd.Categorical(df[var], categories=categories)
+
+
+class DataVisualiser:
+    """
+    A class for creating and saving data visualizations and statistics tables.
+    
+    This class provides methods to generate common statistical visualizations and tables,
+    including count plots, distribution plots, and their stratified versions.
+    
+    Attributes:
+        record_unit_name: Name of what a single record represents (e.g., "patient")
+        count_colname: Column name used for count statistics
+        figures_dirpath: Directory path for saving figures
+        tables_dirpath: Directory path for saving tables
+    """
+    
+    def __init__(
+        self,
+        record_unit_name: str = RECORD_UNIT_NAME,
+        figures_dirpath: Optional[str] = None,
+        tables_dirpath: Optional[str] = None,
+        create_dirs: bool = False,
+    ):
+        """
+        Initialize DataVisualiser with paths and record unit information.
+        
+        Args:
+            record_unit_name: Name of what a single record represents (e.g., "patient")
+            figures_dirpath: Directory path for saving figures
+            tables_dirpath: Directory path for saving tables
+            create_dirs: Whether to create the figures and tables directories if they don't exist
+        """
+        self.record_unit_name = record_unit_name
+        self.count_colname = f"# {record_unit_name}s"
+        self.figures_dirpath = figures_dirpath
+        self.tables_dirpath = tables_dirpath
+
+        if create_dirs and figures_dirpath and tables_dirpath:
+            Path(figures_dirpath).mkdir(parents=True, exist_ok=True)
+            Path(tables_dirpath).mkdir(parents=True, exist_ok=True)
+
+    def get_count_plot(
+        self,
+        var: str,
+        df: pd.DataFrame,
+        show_nan: bool = True,
+        save_fig: bool = False,
+        plot_kwargs: Dict = {},
+        xlabels_rotation: Optional[int] = None,
+        forced_order: Optional[List[str]] = None,
+    ) -> Tuple[plt.Figure, plt.Axes]:
+        """
+        Create a count plot for a categorical variable.
+        
+        Args:
+            var: Variable to plot
+            df: DataFrame containing the data
+            show_nan: Whether to show NaN values as a separate category
+            save_fig: Whether to save the figure to disk
+            plot_kwargs: Additional keyword arguments to pass to seaborn's countplot
+            xlabels_rotation: Rotation angle for x-axis labels
+            forced_order: Optional custom ordering of categories
+            
+        Returns:
+            Tuple of (figure, axes)
+        """
+        # Preprocess df
+        df = df[var].astype(str).to_frame().copy()
+        if show_nan:
+            df = df[var].fillna(NAN_REPLACEMENT_STR).to_frame().copy()
+        # Order variables alphabetically
+        categorise_variable_in_df(var, df, forced_order=forced_order)
+
+        fig, ax = plt.subplots()
+        sns.countplot(y=var, data=df, **plot_kwargs)
+        ax.set_title(f"Number of {self.record_unit_name}s separated by {var}")
+
+        if xlabels_rotation:
+            plt.xticks(rotation=xlabels_rotation)
+
+        if save_fig and self.figures_dirpath:
+            plt.savefig(
+                os.path.join(self.figures_dirpath, f"count_plot_{var}.png"),
+                bbox_inches="tight",
+            )
+            plt.close()
+
+        return fig, ax
+
+    def get_count_stratified_plot(
+        self,
+        var: str,
+        df: pd.DataFrame,
+        col: str = "sexe_desc",
+        show_nan: bool = True,
+        show_nan_col: bool = True,
+        save_fig: bool = False,
+        col_wrap: int = 3,
+        plot_kwargs: Dict = {},
+        xlabels_rotation: Optional[int] = None,
+        forced_order: Optional[List[str]] = None,
+        forced_order_col: Optional[List[str]] = None,
+    ) -> sns.FacetGrid:
+        """
+        Create stratified count plots for a categorical variable.
+        
+        Args:
+            var: Variable to plot
+            df: DataFrame containing the data
+            col: Column to stratify by
+            show_nan: Whether to show NaN values in var as a separate category
+            show_nan_col: Whether to show NaN values in col as a separate category
+            save_fig: Whether to save the figure to disk
+            col_wrap: Number of facets per row
+            plot_kwargs: Additional keyword arguments to pass to seaborn's catplot
+            xlabels_rotation: Rotation angle for x-axis labels
+            forced_order: Optional custom ordering of categories for var
+            forced_order_col: Optional custom ordering of categories for col
+            
+        Returns:
+            Seaborn FacetGrid object
+        """
+        # Preprocess df
+        df = df[[var, col]].astype(str).copy()
+        if show_nan:
+            df[var] = df[var].fillna(NAN_REPLACEMENT_STR)
+        if show_nan_col:
+            df[col] = df[col].fillna(NAN_REPLACEMENT_STR)
+        # Order variables alphabetically
+        categorise_variable_in_df(var, df, forced_order=forced_order)
+        categorise_variable_in_df(col, df, forced_order=forced_order_col)
+
+        # Use height from plot_kwargs if specified, otherwise use HEIGHT
+        if plot_kwargs.get("height") is None:
+            plot_kwargs["height"] = HEIGHT
+
+        fg = sns.catplot(
+            y=var, col=col, col_wrap=col_wrap, kind="count", data=df, **plot_kwargs
+        )
+        fg.fig.suptitle(
+            f"Number of {self.record_unit_name}s separated by {var} in each {col}",
+            y=1.02,
+        )
+
+        if xlabels_rotation:
+            fg.tick_params(axis="x", rotation=xlabels_rotation)
+
+        if save_fig and self.figures_dirpath:
+            plt.savefig(
+                os.path.join(
+                    self.figures_dirpath, f"count_plot_{var}_for_each_{col}.png"
+                ),
+                bbox_inches="tight",
+            )
+            plt.close()
+
+        return fg
+
+    def get_count_stats_df(
+        self,
+        var: str,
+        df: pd.DataFrame,
+        show_nan: bool = True,
+        save_table: bool = False,
+        percentage: bool = True,
+        add_total: bool = False,
+        round_n_digits: int = 1,
+        forced_order: Optional[List[str]] = None,
+    ) -> pd.DataFrame:
+        """
+        Create a DataFrame with count statistics for a categorical variable.
+        
+        Args:
+            var: Variable to analyze
+            df: DataFrame containing the data
+            show_nan: Whether to include NaN values as a separate category
+            save_table: Whether to save the statistics as a LaTeX table
+            percentage: Whether to include percentage column
+            add_total: Whether to add a "Total" row
+            round_n_digits: Number of decimal places to round to
+            forced_order: Optional custom ordering of categories
+            
+        Returns:
+            DataFrame with count statistics
+        """
+        # Preprocess df
+        df = df[var].astype(str).to_frame().copy()
+        if show_nan:
+            df = df[var].fillna(NAN_REPLACEMENT_STR).to_frame().copy()
+        # Order variables alphabetically
+        categorise_variable_in_df(var, df, forced_order=forced_order)
+
+        # Compute stats df
+        stats_df = df.groupby(var).size().rename(self.count_colname).to_frame()
+
+        if percentage:
+            stats_df = pd.concat(
+                [
+                    stats_df,
+                    (100 * stats_df / stats_df.sum()).rename(
+                        columns={self.count_colname: "%"}
+                    ),
+                ],
+                axis=1,
+            )
+
+        if add_total:
+            stats_df = pd.concat(
+                [
+                    stats_df,
+                    stats_df.sum(axis=0).rename("Total").to_frame().transpose(),
+                ],
+                axis=0,
+            )
+            # Convert count_colname back to int type
+            stats_df[self.count_colname] = stats_df[self.count_colname].astype(int)
+
+        if save_table and self.tables_dirpath:
+            filepath = os.path.join(self.tables_dirpath, f"count_stats_table_{var}.tex")
+            with open(filepath, "w") as f:
+                f.write(stats_df.round(round_n_digits).to_latex())
+
+        return stats_df
+
+    def get_count_stratified_stats_df(
+        self,
+        var: str,
+        df: pd.DataFrame,
+        col: str = "sexe_desc",
+        show_nan: bool = True,
+        show_nan_col: bool = True,
+        save_table: bool = False,
+        percentage: bool = True,
+        round_n_digits: int = 1,
+        forced_order: Optional[List[str]] = None,
+        forced_order_col: Optional[List[str]] = None,
+    ) -> pd.DataFrame:
+        """
+        Create a DataFrame with stratified count statistics for a categorical variable.
+        
+        Args:
+            var: Variable to analyze
+            df: DataFrame containing the data
+            col: Column to stratify by
+            show_nan: Whether to include NaN values in var as a separate category
+            show_nan_col: Whether to include NaN values in col as a separate category
+            save_table: Whether to save the statistics as a LaTeX table
+            percentage: Whether to include percentage column
+            round_n_digits: Number of decimal places to round to
+            forced_order: Optional custom ordering of categories for var
+            forced_order_col: Optional custom ordering of categories for col
+            
+        Returns:
+            DataFrame with stratified count statistics
+        """
+        # Preprocess df
+        df = df[[var, col]].astype(str).copy()
+        if show_nan:
+            df[var] = df[var].fillna(NAN_REPLACEMENT_STR)
+        if show_nan_col:
+            df[col] = df[col].fillna(NAN_REPLACEMENT_STR)
+        # Order variables alphabetically
+        categorise_variable_in_df(var, df, forced_order=forced_order)
+        categorise_variable_in_df(col, df, forced_order=forced_order_col)
+
+        # Compute stats df
+        stratified_stats_df = pd.DataFrame(
+            df.groupby([col, var]).size(), columns=[self.count_colname]
+        )
+
+        if percentage:
+            stratified_stats_df = pd.concat(
+                [
+                    stratified_stats_df,
+                    (
+                        100
+                        * stratified_stats_df
+                        / stratified_stats_df.groupby(level=0).sum()
+                    ).rename(columns={self.count_colname: "%"}),
+                ],
+                axis=1,
+            )
+
+        if save_table and self.tables_dirpath:
+            filepath = os.path.join(
+                self.tables_dirpath,
+                f"count_stats_table_{var}_for_each_{col}.tex",
+            )
+            with open(filepath, "w") as f:
+                f.write(stratified_stats_df.round(round_n_digits).to_latex())
+
+        return stratified_stats_df
+
+    def get_dist_plot(
+        self, 
+        var: str, 
+        df: pd.DataFrame, 
+        save_fig: bool = False, 
+        plot_kwargs: Dict = {"kde": True}, 
+        xlabels_rotation: Optional[int] = None
+    ) -> Tuple[plt.Figure, plt.Axes]:
+        """
+        Create a distribution plot for a numerical variable.
+        
+        Args:
+            var: Variable to plot
+            df: DataFrame containing the data
+            save_fig: Whether to save the figure to disk
+            plot_kwargs: Additional keyword arguments to pass to seaborn's histplot
+            xlabels_rotation: Rotation angle for x-axis labels
+            
+        Returns:
+            Tuple of (figure, axes)
+        """
+        fig, ax = plt.subplots()
+        sns.histplot(data=df, x=var, ax=ax, **plot_kwargs)
+        ax.set_title(f"Distribution of {var}")
+
+        if xlabels_rotation:
+            plt.xticks(rotation=xlabels_rotation)
+
+        if save_fig and self.figures_dirpath:
+            plt.savefig(
+                os.path.join(self.figures_dirpath, f"dist_plot_{var}.png"),
+                bbox_inches="tight",
+            )
+            plt.close()
+
+        return fig, ax
+
+    def get_dist_stratified_plot(
+        self,
+        var: str,
+        df: pd.DataFrame,
+        col: str = "sexe_desc",
+        show_nan_col: bool = True,
+        save_fig: bool = False,
+        col_wrap: int = 3,
+        plot_kwargs: Dict = {"kde": True},
+        xlabels_rotation: Optional[int] = None,
+        forced_order_col: Optional[List[str]] = None,
+    ) -> sns.FacetGrid:
+        """
+        Create stratified distribution plots for a numerical variable.
+        
+        Args:
+            var: Variable to plot
+            df: DataFrame containing the data
+            col: Column to stratify by
+            show_nan_col: Whether to show NaN values in col as a separate category
+            save_fig: Whether to save the figure to disk
+            col_wrap: Number of facets per row
+            plot_kwargs: Additional keyword arguments to pass to seaborn's displot
+            xlabels_rotation: Rotation angle for x-axis labels
+            forced_order_col: Optional custom ordering of categories for col
+            
+        Returns:
+            Seaborn FacetGrid object
+        """
+        # Preprocess df
+        df = df[[var, col]].copy()
+        df[col] = df[col].astype(str)
+        if show_nan_col:
+            df[col] = df[col].fillna(NAN_REPLACEMENT_STR)
+        # Order variables alphabetically
+        categorise_variable_in_df(col, df, forced_order=forced_order_col)
+
+        # Use height from plot_kwargs if specified, otherwise use HEIGHT
+        if plot_kwargs.get("height") is None:
+            plot_kwargs["height"] = HEIGHT
+
+        fg = sns.displot(data=df, x=var, col=col, col_wrap=col_wrap, **plot_kwargs)
+        fg.fig.suptitle(f"Distribution of {var} for each {col}", y=1.02)
+
+        if xlabels_rotation:
+            fg.set_xticklabels(rotation=xlabels_rotation)
+
+        if save_fig and self.figures_dirpath:
+            plt.savefig(
+                os.path.join(
+                    self.figures_dirpath, f"dist_plot_{var}_for_each_{col}.png"
+                ),
+                bbox_inches="tight",
+            )
+            plt.close()
+
+        return fg
+
+    def get_dist_hued_plot(
+        self,
+        var: str,
+        df: pd.DataFrame,
+        hue: str = "sexe_desc",
+        show_nan_col: bool = True,
+        save_fig: bool = False,
+        plot_kwargs: Dict = {"kde": True},
+        xlabels_rotation: Optional[int] = None,
+        forced_order_col: Optional[List[str]] = None,
+    ) -> sns.FacetGrid:
+        """
+        Create a distribution plot for a numerical variable with hue for categories.
+        
+        Args:
+            var: Variable to plot
+            df: DataFrame containing the data
+            hue: Column to use for color encoding
+            show_nan_col: Whether to show NaN values in hue as a separate category
+            save_fig: Whether to save the figure to disk
+            plot_kwargs: Additional keyword arguments to pass to seaborn's displot
+            xlabels_rotation: Rotation angle for x-axis labels
+            forced_order_col: Optional custom ordering of categories for hue
+            
+        Returns:
+            Seaborn FacetGrid object
+        """
+        # Preprocess df
+        df = df[[var, hue]].copy()
+        df[hue] = df[hue].astype(str)
+        if show_nan_col:
+            df[hue] = df[hue].fillna(NAN_REPLACEMENT_STR)
+        # Order variables alphabetically
+        categorise_variable_in_df(hue, df, forced_order=forced_order_col)
+
+        # Use height from plot_kwargs if specified, otherwise use HEIGHT
+        if plot_kwargs.get("height") is None:
+            plot_kwargs["height"] = HEIGHT
+
+        fg = sns.displot(data=df, x=var, hue=hue, **plot_kwargs)
+        fg.fig.suptitle(f"Distribution of {var} for each {hue}", y=1.02)
+
+        if xlabels_rotation:
+            fg.set_xticklabels(rotation=xlabels_rotation)
+
+        if save_fig and self.figures_dirpath:
+            plt.savefig(
+                os.path.join(
+                    self.figures_dirpath, f"dist_plot_{var}_for_hue_{hue}.png"
+                ),
+                bbox_inches="tight",
+            )
+            plt.close()
+
+        return fg
+
+    def get_dist_stats_df(
+        self,
+        var: str,
+        df: pd.DataFrame,
+        save_table: bool = False
+    ) -> pd.DataFrame:
+        """
+        Create a DataFrame with distribution statistics for a numerical variable.
+        
+        Args:
+            var: Variable to analyze
+            df: DataFrame containing the data
+            save_table: Whether to save the statistics as a LaTeX table
+            
+        Returns:
+            DataFrame with distribution statistics
+        """
+        stats_df = pd.DataFrame(df[var].describe()).transpose()
+
+        # Convert 'count' column into 'int' type
+        stats_df["count"] = stats_df["count"].astype(int)
+
+        # Add number and percentage of NaNs
+        stats_df.insert(1, "nan_perc", value=100 * df[var].isna().mean())
+        stats_df.insert(1, "n_nan", value=df[var].isna().sum())
+
+        if save_table and self.tables_dirpath:
+            # Get number of decimals to include
+            std = stats_df.squeeze()["std"]
+            round_n_digits = get_n_decimals_to_include(std)
+
+            filepath = os.path.join(self.tables_dirpath, f"dist_stats_table_{var}.tex")
+            with open(filepath, "w") as f:
+                f.write(
+                    get_latex_table_bold_col_header(
+                        stats_df, round_n_digits=round_n_digits
+                    )
+                )
+
+        return stats_df
+
+    def get_dist_stratified_stats_df(
+        self,
+        var: str,
+        df: pd.DataFrame,
+        col: str = "sexe_desc",
+        show_nan_col: bool = True,
+        save_table: bool = False,
+        forced_order_col: Optional[List[str]] = None,
+    ) -> pd.DataFrame:
+        """
+        Create a DataFrame with stratified distribution statistics for a numerical variable.
+        
+        Args:
+            var: Variable to analyze
+            df: DataFrame containing the data
+            col: Column to stratify by
+            show_nan_col: Whether to show NaN values in col as a separate category
+            save_table: Whether to save the statistics as a LaTeX table
+            forced_order_col: Optional custom ordering of categories for col
+            
+        Returns:
+            DataFrame with stratified distribution statistics
+        """
+        # Preprocess df
+        df = df[[var, col]].copy()
+        df[col] = df[col].astype(str)
+        if show_nan_col:
+            df[col] = df[col].fillna(NAN_REPLACEMENT_STR)
+        # Order variables alphabetically
+        categorise_variable_in_df(col, df, forced_order=forced_order_col)
+
+        stratified_stats_df = pd.DataFrame(df.groupby(col)[var].describe())
+
+        # Convert 'count' column into 'int' type
+        stratified_stats_df["count"] = stratified_stats_df["count"].astype(int)
+
+        # Add number and percentage of NaNs
+        stratified_stats_df.insert(
+            1,
+            "nan_perc",
+            value=100 * df.groupby(col)[var].apply(lambda x: x.isna().mean()),
+        )
+        stratified_stats_df.insert(
+            1, "n_nan", value=df.groupby(col)[var].apply(lambda x: x.isna().sum())
+        )
+
+        if save_table and self.tables_dirpath:
+            # Get number of decimals to include
+            std = stratified_stats_df["std"].min()
+            round_n_digits = get_n_decimals_to_include(std)
+
+            filepath = os.path.join(
+                self.tables_dirpath,
+                f"dist_stats_table_{var}_for_each_{col}.tex",
+            )
+            with open(filepath, "w") as f:
+                f.write(
+                    get_latex_table_bold_col_header(
+                        stratified_stats_df, round_n_digits=round_n_digits
+                    )
+                )
+
+        return stratified_stats_df
+
+
+if __name__ == '__main__':
+    print("DataVisualiser: A tool for data visualization and analysis")
+    print("Import this module to use the functionality")
+    print("Example: from data_visualiser_package import DataVisualiser")

data_visualiser_package/export_latex_tables.py

@@ -0,0 +1,102 @@
+import os
+
+import numpy as np
+
+
+def remove_toprule(s):
+    return s.replace("\\toprule\n", "")
+
+
+def remove_bottomrule(s):
+    return s.replace("\\bottomrule\n", "")
+
+
+def replace_midrule_with_hline(s):
+    return s.replace("\\midrule", "\\hline")
+
+
+def replace_bottomrule_with_hline(s):
+    return s.replace("\\bottomrule", "\\hline")
+
+
+def change_header(s, header_list):
+    lines = s.split("\n")
+    header_line = lines[2]
+    new_header_line = " & ".join(header_list) + " \\\\"
+    new_lines = lines[:2] + [new_header_line] + lines[3:]
+    new_s = "\n".join(new_lines)
+
+    return new_s
+
+
+def change_values_title(s, new_values_title):
+    lines = s.split("\n")
+    values_line = lines[-4]
+    values_list = values_line.split("&")
+
+    new_values_list = [new_values_title + " "] + values_list[1:]
+    new_values_line = "&".join(new_values_list)
+    new_lines = lines[:4] + [new_values_line] + lines[5:]
+    s = "\n".join(new_lines)
+
+    return s
+
+
+def add_hline(s, line_number_from_end=3):
+    """Add hline at line_number_from_end.
+
+    The default '3' corresponds to
+    adding a line before the last line of the table.
+    """
+    lines = s.split("\n")
+    new_lines = (
+        lines[:-line_number_from_end] + ["\\hline"] + lines[-line_number_from_end:]
+    )
+
+    return "\n".join(new_lines)
+
+
+def format_table(s, header_list=None, new_values_title=None):
+    if header_list is not None:
+        s = change_header(s, header_list)
+    if new_values_title is not None:
+        s = change_values_title(s, new_values_title)
+    s = remove_toprule(s)
+    s = remove_bottomrule(s)
+    s = replace_midrule_with_hline(s)
+    #     s = replace_bottomrule_with_hline(s)
+    return s
+
+
+def write_table_to_file(s, variable, dirpath):
+    with open(os.path.join(dirpath, variable + "_table.tex"), "w") as f:
+        f.write(s)
+
+
+def boldify_line(line, words_to_boldify):
+    for word in words_to_boldify:
+        line = line.replace(word, "\\textbf{" + f"{word}" + "}")
+    return line
+
+
+def get_latex_table_bold_col_header(df2, round_n_digits=1):
+    table_lines = df2.round(round_n_digits).to_latex().split("\\\\")
+
+    col_headers = list(df2.columns.str.replace("%", "\\%").str.replace("_", "\\_"))
+    new_line0 = boldify_line(table_lines[0], col_headers)
+
+    boldified_table = "\\\\".join([new_line0] + table_lines[1:])
+    return boldified_table
+
+
+def get_n_decimals_to_include(std, min_n_decimals=1):
+    # If std == 0, return min_n_decimals, otherwise we get an error when applying the log
+    if std == 0:
+        return min_n_decimals
+
+    n_decimals_to_include = -(np.log10(std).round() - 1)
+
+    if n_decimals_to_include < 1:
+        return min_n_decimals
+    else:
+        return int(n_decimals_to_include)

data_visualiser_package-0.1.0.dist-info/METADATA

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: data-visualiser-package
+Version: 0.1.0
+Summary: A utility package for data visualization and statistical analysis with Matplotlib and Seaborn
+Project-URL: Homepage, https://github.com/jonathan-doenz/data-visualiser-package
+Project-URL: Bug Tracker, https://github.com/jonathan-doenz/data-visualiser-package/issues
+Author-email: jonathan-doenz <jonathan.doenz@gmail.com>
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.7
+Requires-Dist: matplotlib>=3.3.0
+Requires-Dist: numpy>=1.19.0
+Requires-Dist: pandas>=1.0.0
+Requires-Dist: seaborn>=0.11.0
+Description-Content-Type: text/markdown
+
+# Data Visualiser Package
+
+A Python utility package for data visualization and statistical analysis with Matplotlib and Seaborn. This package provides a simple interface to create common visualizations and statistical tables for exploratory data analysis and reporting.
+
+## Installation
+
+```bash
+pip install data-visualiser-package
+```
+
+## Features
+
+- Create count plots and distribution plots
+- Generate stratified visualizations by categorical variables
+- Compute and display statistical tables for numerical and categorical variables
+- Save plots and tables to disk (including LaTeX export)
+- Handling of missing values
+
+## Quick Start
+
+```python
+import pandas as pd
+from data_visualiser_package import DataVisualiser
+
+# Create a DataVisualiser instance
+dv = DataVisualiser(
+    record_unit_name="patient",  # What a single record represents
+    figures_dirpath="./figures", # Where to save figures
+    tables_dirpath="./tables",   # Where to save tables
+    create_dirs=True             # Create directories if they don't exist
+)
+
+# Load your data
+df = pd.read_csv("your_data.csv")
+
+# Create a count plot
+fig, ax = dv.get_count_plot(
+    var="diagnosis",          # Categorical variable to plot
+    df=df,                   # DataFrame containing the data
+    show_nan=True,           # Show NaN values as a separate category
+    save_fig=True            # Save the figure to disk
+)
+
+# Create a distribution plot
+fig, ax = dv.get_dist_plot(
+    var="age",              # Numerical variable to plot
+    df=df,                  # DataFrame containing the data
+    save_fig=True           # Save the figure to disk
+)
+
+# Generate statistics tables
+stats_df = dv.get_count_stats_df(
+    var="diagnosis",        # Categorical variable to analyze
+    df=df,                  # DataFrame containing the data
+    save_table=True         # Save the table to disk as LaTeX
+)
+
+# Create stratified visualizations
+fg = dv.get_dist_stratified_plot(
+    var="age",              # Numerical variable to plot
+    df=df,                  # DataFrame containing the data
+    col="gender",           # Categorical variable to stratify by
+    save_fig=True           # Save the figure to disk
+)
+```
+
+## Example
+
+Here's a complete example of how to use the DataVisualiser class:
+
+```python
+import pandas as pd
+import numpy as np
+from data_visualiser_package import DataVisualiser
+
+# Create a sample dataset
+np.random.seed(42)
+n = 1000
+
+# Generate sample data
+data = {
+    'age': np.random.normal(50, 15, n),
+    'gender': np.random.choice(['Male', 'Female'], n),
+    'diagnosis': np.random.choice(['Healthy', 'Condition A', 'Condition B', None], n, p=[0.6, 0.2, 0.15, 0.05]),
+    'heart_rate': np.random.normal(80, 10, n),
+    'blood_pressure': np.random.normal(120, 15, n)
+}
+
+# Create a DataFrame
+df = pd.DataFrame(data)
+
+# Initialize the DataVisualiser
+dv = DataVisualiser(
+    record_unit_name="patient",
+    figures_dirpath="./output/figures",
+    tables_dirpath="./output/tables",
+    create_dirs=True
+)
+
+# Create plots
+dv.get_count_plot('gender', df, save_fig=True)
+dv.get_count_plot('diagnosis', df, save_fig=True)
+
+# Create stratified count plots
+dv.get_count_stratified_plot('diagnosis', df, col='gender', save_fig=True)
+
+# Distribution plots
+dv.get_dist_plot('age', df, save_fig=True)
+dv.get_dist_stratified_plot('age', df, col='gender', save_fig=True)
+dv.get_dist_hued_plot('age', df, hue='gender', save_fig=True)
+
+# Generate statistics tables
+dv.get_count_stats_df('diagnosis', df, save_table=True)
+dv.get_dist_stats_df('age', df, save_table=True)
+dv.get_dist_stratified_stats_df('age', df, col='gender', save_table=True)
+
+print("All visualizations and tables have been generated successfully!")
+```
+
+## API Reference
+
+### DataVisualiser Class
+
+```python
+class DataVisualiser(
+    record_unit_name="patient",
+    figures_dirpath=None,
+    tables_dirpath=None,
+    create_dirs=False
+)
+```
+
+#### Count Visualizations
+
+- `get_count_plot(var, df, show_nan=True, save_fig=False, plot_kwargs={}, xlabels_rotation=None, forced_order=None)`
+- `get_count_stratified_plot(var, df, col="gender", show_nan=True, show_nan_col=True, save_fig=False, col_wrap=3, plot_kwargs={}, xlabels_rotation=None, forced_order=None, forced_order_col=None)`
+- `get_count_stats_df(var, df, show_nan=True, save_table=False, percentage=True, add_total=False, round_n_digits=1, forced_order=None)`
+- `get_count_stratified_stats_df(var, df, col="gender", show_nan=True, show_nan_col=True, save_table=False, percentage=True, round_n_digits=1, forced_order=None, forced_order_col=None)`
+
+#### Distribution Visualizations
+
+- `get_dist_plot(var, df, save_fig=False, plot_kwargs={"kde": True}, xlabels_rotation=None)`
+- `get_dist_stratified_plot(var, df, col="gender", show_nan_col=True, save_fig=False, col_wrap=3, plot_kwargs={"kde": True}, xlabels_rotation=None, forced_order_col=None)`
+- `get_dist_hued_plot(var, df, hue="gender", show_nan_col=True, save_fig=False, plot_kwargs={"kde": True}, xlabels_rotation=None, forced_order_col=None)`
+- `get_dist_stats_df(var, df, save_table=False)`
+- `get_dist_stratified_stats_df(var, df, col="gender", show_nan_col=True, save_table=False, forced_order_col=None)`
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

data_visualiser_package-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+data_visualiser_package/__init__.py,sha256=T1CoedsuYqnuk2XDHUAOdza90JWoiJsQG4Cj3sB1UQc,374
+data_visualiser_package/data_visualiser.py,sha256=3yBLInKSc0BPIIZvCA6h1ybtG5IO6Ezm7V4aH71RLRg,22981
+data_visualiser_package/export_latex_tables.py,sha256=cN9H_cey6NFvc1S9LOQWmK8qu-w0YenFvmO85riW0pk,2715
+data_visualiser_package/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+data_visualiser_package-0.1.0.dist-info/METADATA,sha256=YIqDWOmIqxr3OMxCiVqKf_hgXJlStYFolSf6Q8tj-gY,6459
+data_visualiser_package-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+data_visualiser_package-0.1.0.dist-info/licenses/LICENSE,sha256=IU2SLcxqnhJpreQXofrrzughr5gqNgcOoxb7CF585AY,1071
+data_visualiser_package-0.1.0.dist-info/RECORD,,

data_visualiser_package-0.1.0.dist-info/WHEEL

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

data_visualiser_package-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jonathan Doenz
+
+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.