data-visualiser-package 0.1.0__tar.gz → 0.2.0__tar.gz

{data_visualiser_package-0.1.0 → data_visualiser_package-0.2.0}/.github/workflows/python-package.yml

@@ -2,38 +2,38 @@ name: Python Package
 
 on:
   push:
-    branches: [ main ]
+    branches: [ master, main ]
     tags:
       - 'v*'
   pull_request:
-    branches: [ main ]
+    branches: [ master, main ]
 
 jobs:
   test:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ['3.7', '3.8', '3.9', '3.10', '3.11']
+        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        python -m pip install flake8 pytest
-        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
-        python -m pip install -e .
+        python -m pip install -e ".[dev]"
     - name: Lint with flake8
       run: |
         # stop the build if there are Python syntax errors or undefined names
-        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+        flake8 src tests examples --count --select=E9,F63,F7,F82 --show-source --statistics
         # exit-zero treats all errors as warnings
-        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=120 --statistics
+        flake8 src tests examples --count --exit-zero --max-complexity=10 --max-line-length=120 --statistics
     - name: Test with pytest
+      env:
+        MPLBACKEND: Agg
       run: |
         pytest
 
@@ -41,13 +41,13 @@ jobs:
     needs: test
     runs-on: ubuntu-latest
     if: startsWith(github.ref, 'refs/tags/')
-    
+
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Set up Python
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
-        python-version: '3.9'
+        python-version: '3.12'
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip

{data_visualiser_package-0.1.0 → data_visualiser_package-0.2.0}/.gitignore

@@ -49,3 +49,8 @@ demo_output/
 .DS_Store
 Thumbs.db
 desktop.ini
+
+# Editor/tool caches
+tags
+.mypy_cache/
+.pytest_cache/

data_visualiser_package-0.2.0/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+All notable changes to the Data Visualiser Package will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-09-11
+
+### Fixed
+- Missing values are now handled consistently: `None`, `NaN` and `pd.NA` all become a single
+  `"NaN"` category placed last, `show_nan=False` really excludes them, and numeric categories
+  are ordered numerically (`2 < 5 < 10`) instead of alphabetically. Previously values were
+  converted to strings before being filled, which produced `"None"`/`"nan"` labels and made
+  `show_nan` a no-op.
+- Every column title of saved LaTeX tables is now bold, including titles containing `_` or `%`
+  (`n_nan`, `nan_perc`, `25%`, ...). Count tables now use the same bold-header writer.
+- LaTeX export no longer depends on pandas' `to_latex`, which required the undeclared
+  optional dependency `jinja2` on pandas >= 2.0 and escaped special characters differently
+  across versions. Special characters (`#`, `%`, `_`, `&`, ...) are always escaped.
+- Saving a distribution table whose standard deviation is NaN (single value / all missing)
+  no longer crashes.
+- `plot_kwargs` dictionaries passed by the caller (and the defaults) are no longer mutated.
+- `create_dirs=True` now creates each configured directory independently.
+- Figures are saved and closed by object rather than through the "current figure".
+- CI runs on the `master` branch and on Python 3.9-3.13.
+
+### Changed (breaking)
+- `col` / `hue` are now required arguments of the stratified and hued methods (the previous
+  default `"sexe_desc"` was dataset-specific).
+- `save_fig=True` / `save_table=True` raise a `ValueError` when the corresponding directory
+  is not configured, instead of silently doing nothing.
+- `get_dist_stats_df` / `get_dist_stratified_stats_df` / `get_box_stratified_plot` raise a
+  `TypeError` for non-numeric variables.
+- `categorise_variable_in_df` raises `ValueError` (instead of `AssertionError`) when
+  `forced_order` is incomplete.
+- Minimum supported Python is 3.9; minimum pandas is 1.5.
+- The unused low-level helpers of `export_latex_tables` (`format_table`, `boldify_line`, ...)
+  were removed. `get_latex_table_bold_col_header` and `get_n_decimals_to_include` remain.
+- `setup.py` was removed; `pyproject.toml` (hatchling) is the single build configuration.
+
+### Added
+- `DataVisualiser(nan_label=..., fig_format=..., dpi=..., table_format=...)` to customise the
+  missing-value label, the figure file format/resolution and the default table format.
+- Tables can be saved as LaTeX, CSV, Markdown or HTML (`table_format` on the constructor or
+  per call).
+- `get_box_stratified_plot(var, df, col, kind="box"|"violin")`.
+- `get_count_stratified_stats_df(..., wide=True)` returns a crosstab with strata as columns.
+- `round_n_digits` on the distribution table methods (auto-derived from the spread by default).
+- Public helpers `prepare_categorical`, `dataframe_to_latex`, `dataframe_to_markdown`.
+
+## [0.1.0] - 2025-05-14
+
+### Added
+- Initial release of the DataVisualiser package
+- Core functionality for data visualization and statistical analysis
+- Support for count plots and distribution plots
+- Support for stratified visualizations
+- LaTeX table export functionality
+- Comprehensive documentation and examples

data_visualiser_package-0.2.0/PKG-INFO

@@ -0,0 +1,243 @@
+Metadata-Version: 2.5
+Name: data-visualiser-package
+Version: 0.2.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.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.9
+Requires-Dist: matplotlib>=3.5.0
+Requires-Dist: numpy>=1.21.0
+Requires-Dist: pandas>=1.5.0
+Requires-Dist: seaborn>=0.11.2
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: build>=0.10.0; extra == 'dev'
+Requires-Dist: flake8>=5.0.0; extra == 'dev'
+Requires-Dist: isort>=5.10.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: twine>=4.0.0; extra == 'dev'
+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
+```
+
+Requires Python 3.9+ (pandas >= 1.5, seaborn >= 0.11.2, matplotlib >= 3.5).
+
+## Features
+
+- Count plots and distribution plots, plain or stratified by a categorical variable
+- Box / violin plots of a numerical variable per category
+- Count and distribution statistics tables, including stratified (long or wide) versions
+- Save figures as PNG, PDF, SVG, ... and tables as LaTeX (bold headers, escaped special characters), CSV, Markdown or HTML
+- Consistent handling of missing values: `None`, `NaN` and `pd.NA` become one `"NaN"` category placed last, or are excluded with `show_nan=False`
+- Categories are ordered on their native type (`2 < 5 < 10`), or by an explicit `forced_order`
+
+## 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
+    fig_format="png",             # Any format matplotlib supports (png, pdf, svg, ...)
+    dpi=150,                      # Resolution of saved figures (None = matplotlib default)
+    table_format="latex",         # Default table format: latex, csv, markdown or html
+)
+
+# 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 (last) category
+    save_fig=True,            # Save the figure to disk
+)
+
+# Create a distribution plot
+fig, ax = dv.get_dist_plot(var="age", df=df, save_fig=True)
+
+# Generate statistics tables
+stats_df = dv.get_count_stats_df(var="diagnosis", df=df, save_table=True)
+
+# Create stratified visualizations
+fg = dv.get_dist_stratified_plot(var="age", df=df, col="gender", save_fig=True)
+
+# Box plot of a numerical variable per category
+fig, ax = dv.get_box_stratified_plot(var="age", df=df, col="diagnosis", save_fig=True)
+
+# Wide crosstab (rows: diagnosis categories, columns: one block per gender), saved as CSV
+wide = dv.get_count_stratified_stats_df(
+    "diagnosis", df, col="gender", wide=True, save_table=True, table_format="csv"
+)
+```
+
+## Missing values and category order
+
+All categorical inputs go through the same preprocessing (`prepare_categorical`):
+
+- `None`, `np.nan` and `pd.NA` are treated as missing. With `show_nan=True` (default) they form
+  a single category labelled `"NaN"` (configurable through `DataVisualiser(nan_label=...)`) that is
+  always placed last. With `show_nan=False` the records are excluded from that plot/table, and
+  percentages are computed over the remaining records.
+- Categories are sorted on their native values, so numeric codes are ordered numerically.
+  Integral floats are labelled without decimals (`10.0` -> `"10"`).
+- `forced_order` (and `forced_order_col` for the stratification variable) imposes an explicit
+  order and may list categories absent from the data (they appear with a count of 0). It must
+  cover every value present, otherwise a `ValueError` is raised.
+
+Distribution tables report `n_nan` and `nan_perc` next to the usual `describe()` statistics.
+
+## 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
+
+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)
+}
+df = pd.DataFrame(data)
+
+dv = DataVisualiser(
+    record_unit_name="patient",
+    figures_dirpath="./output/figures",
+    tables_dirpath="./output/tables",
+    create_dirs=True
+)
+
+# Plots
+dv.get_count_plot('gender', df, save_fig=True)
+dv.get_count_plot('diagnosis', df, save_fig=True)
+dv.get_count_stratified_plot('diagnosis', df, col='gender', save_fig=True)
+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)
+dv.get_box_stratified_plot('heart_rate', df, col='diagnosis', kind='violin', save_fig=True)
+
+# Statistics tables
+dv.get_count_stats_df('diagnosis', df, save_table=True, add_total=True)
+dv.get_count_stratified_stats_df('diagnosis', df, col='gender', wide=True, 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, table_format="markdown")
+
+print("All visualizations and tables have been generated successfully!")
+```
+
+See `examples/demo.py` for a runnable version.
+
+## API Reference
+
+### DataVisualiser Class
+
+```python
+class DataVisualiser(
+    record_unit_name="patient",
+    figures_dirpath=None,
+    tables_dirpath=None,
+    create_dirs=False,
+    nan_label="NaN",
+    fig_format="png",
+    dpi=None,
+    table_format="latex",
+)
+```
+
+`save_fig=True` / `save_table=True` require the corresponding directory to be configured and raise a `ValueError` otherwise. Saved figures are closed after writing.
+
+#### Count Visualizations
+
+- `get_count_plot(var, df, show_nan=True, save_fig=False, plot_kwargs=None, xlabels_rotation=None, forced_order=None)` -> `(fig, ax)`
+- `get_count_stratified_plot(var, df, col, show_nan=True, show_nan_col=True, save_fig=False, col_wrap=3, plot_kwargs=None, xlabels_rotation=None, forced_order=None, forced_order_col=None)` -> `FacetGrid`
+- `get_count_stats_df(var, df, show_nan=True, save_table=False, percentage=True, add_total=False, round_n_digits=1, forced_order=None, table_format=None)` -> `DataFrame`
+- `get_count_stratified_stats_df(var, df, col, show_nan=True, show_nan_col=True, save_table=False, percentage=True, round_n_digits=1, forced_order=None, forced_order_col=None, wide=False, table_format=None)` -> `DataFrame` (percentages are within each stratum; `wide=True` returns strata as columns)
+
+#### Distribution Visualizations
+
+- `get_dist_plot(var, df, save_fig=False, plot_kwargs=None, xlabels_rotation=None)` -> `(fig, ax)` (`plot_kwargs` defaults to `{"kde": True}`)
+- `get_dist_stratified_plot(var, df, col, show_nan_col=True, save_fig=False, col_wrap=3, plot_kwargs=None, xlabels_rotation=None, forced_order_col=None)` -> `FacetGrid`
+- `get_dist_hued_plot(var, df, hue, show_nan_col=True, save_fig=False, plot_kwargs=None, xlabels_rotation=None, forced_order_col=None)` -> `FacetGrid`
+- `get_box_stratified_plot(var, df, col, kind="box", show_nan_col=True, save_fig=False, plot_kwargs=None, xlabels_rotation=None, forced_order_col=None)` -> `(fig, ax)` (`kind` is `"box"` or `"violin"`)
+- `get_dist_stats_df(var, df, save_table=False, round_n_digits=None, table_format=None)` -> `DataFrame`
+- `get_dist_stratified_stats_df(var, df, col, show_nan_col=True, save_table=False, forced_order_col=None, round_n_digits=None, table_format=None)` -> `DataFrame`
+
+The distribution methods require a numeric `var` (a `TypeError` is raised otherwise). When `round_n_digits` is `None`, the number of decimals written to the table is derived from the standard deviation of the data.
+
+#### Output files
+
+| Method | File name (in `figures_dirpath` / `tables_dirpath`) |
+| --- | --- |
+| `get_count_plot` | `count_plot_{var}.{fig_format}` |
+| `get_count_stratified_plot` | `count_plot_{var}_for_each_{col}.{fig_format}` |
+| `get_dist_plot` | `dist_plot_{var}.{fig_format}` |
+| `get_dist_stratified_plot` | `dist_plot_{var}_for_each_{col}.{fig_format}` |
+| `get_dist_hued_plot` | `dist_plot_{var}_for_hue_{hue}.{fig_format}` |
+| `get_box_stratified_plot` | `{kind}_plot_{var}_for_each_{col}.{fig_format}` |
+| `get_count_stats_df` | `count_stats_table_{var}.{tex,csv,md,html}` |
+| `get_count_stratified_stats_df` | `count_stats_table_{var}_for_each_{col}.{tex,csv,md,html}` |
+| `get_dist_stats_df` | `dist_stats_table_{var}.{tex,csv,md,html}` |
+| `get_dist_stratified_stats_df` | `dist_stats_table_{var}_for_each_{col}.{tex,csv,md,html}` |
+
+LaTeX tables use `booktabs` rules (`\toprule`, `\midrule`, `\bottomrule`), bold column titles and escaped special characters (`#`, `%`, `_`, `&`, ...).
+
+### Helper functions
+
+- `prepare_categorical(series, show_nan=True, forced_order=None, nan_label="NaN")` -> ordered categorical `Series` of string labels
+- `categorise_variable_in_df(var, df, forced_order=None, nan_replacement_str="NaN")` -> categorises a column in place
+- `dataframe_to_latex(df, bold_header=True, round_n_digits=None, na_rep="", column_format=None)` -> `str`
+- `dataframe_to_markdown(df, round_n_digits=None, na_rep="")` -> `str`
+
+## Development
+
+```bash
+uv sync --group dev        # or: pip install -e ".[dev]"
+uv run pytest
+uv run flake8 src tests examples --max-line-length=120
+```
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

{data_visualiser_package-0.1.0 → data_visualiser_package-0.2.0}/PYPI_PUBLISH.md

@@ -56,7 +56,6 @@ When releasing a new version:
 
 1. Update the version number in:
    - `pyproject.toml`
-   - `setup.py`
    - `src/data_visualiser_package/__init__.py`
 
 2. Add release notes to the README.md or CHANGELOG.md file.

data_visualiser_package-0.2.0/README.md

@@ -0,0 +1,208 @@
+# 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
+```
+
+Requires Python 3.9+ (pandas >= 1.5, seaborn >= 0.11.2, matplotlib >= 3.5).
+
+## Features
+
+- Count plots and distribution plots, plain or stratified by a categorical variable
+- Box / violin plots of a numerical variable per category
+- Count and distribution statistics tables, including stratified (long or wide) versions
+- Save figures as PNG, PDF, SVG, ... and tables as LaTeX (bold headers, escaped special characters), CSV, Markdown or HTML
+- Consistent handling of missing values: `None`, `NaN` and `pd.NA` become one `"NaN"` category placed last, or are excluded with `show_nan=False`
+- Categories are ordered on their native type (`2 < 5 < 10`), or by an explicit `forced_order`
+
+## 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
+    fig_format="png",             # Any format matplotlib supports (png, pdf, svg, ...)
+    dpi=150,                      # Resolution of saved figures (None = matplotlib default)
+    table_format="latex",         # Default table format: latex, csv, markdown or html
+)
+
+# 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 (last) category
+    save_fig=True,            # Save the figure to disk
+)
+
+# Create a distribution plot
+fig, ax = dv.get_dist_plot(var="age", df=df, save_fig=True)
+
+# Generate statistics tables
+stats_df = dv.get_count_stats_df(var="diagnosis", df=df, save_table=True)
+
+# Create stratified visualizations
+fg = dv.get_dist_stratified_plot(var="age", df=df, col="gender", save_fig=True)
+
+# Box plot of a numerical variable per category
+fig, ax = dv.get_box_stratified_plot(var="age", df=df, col="diagnosis", save_fig=True)
+
+# Wide crosstab (rows: diagnosis categories, columns: one block per gender), saved as CSV
+wide = dv.get_count_stratified_stats_df(
+    "diagnosis", df, col="gender", wide=True, save_table=True, table_format="csv"
+)
+```
+
+## Missing values and category order
+
+All categorical inputs go through the same preprocessing (`prepare_categorical`):
+
+- `None`, `np.nan` and `pd.NA` are treated as missing. With `show_nan=True` (default) they form
+  a single category labelled `"NaN"` (configurable through `DataVisualiser(nan_label=...)`) that is
+  always placed last. With `show_nan=False` the records are excluded from that plot/table, and
+  percentages are computed over the remaining records.
+- Categories are sorted on their native values, so numeric codes are ordered numerically.
+  Integral floats are labelled without decimals (`10.0` -> `"10"`).
+- `forced_order` (and `forced_order_col` for the stratification variable) imposes an explicit
+  order and may list categories absent from the data (they appear with a count of 0). It must
+  cover every value present, otherwise a `ValueError` is raised.
+
+Distribution tables report `n_nan` and `nan_perc` next to the usual `describe()` statistics.
+
+## 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
+
+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)
+}
+df = pd.DataFrame(data)
+
+dv = DataVisualiser(
+    record_unit_name="patient",
+    figures_dirpath="./output/figures",
+    tables_dirpath="./output/tables",
+    create_dirs=True
+)
+
+# Plots
+dv.get_count_plot('gender', df, save_fig=True)
+dv.get_count_plot('diagnosis', df, save_fig=True)
+dv.get_count_stratified_plot('diagnosis', df, col='gender', save_fig=True)
+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)
+dv.get_box_stratified_plot('heart_rate', df, col='diagnosis', kind='violin', save_fig=True)
+
+# Statistics tables
+dv.get_count_stats_df('diagnosis', df, save_table=True, add_total=True)
+dv.get_count_stratified_stats_df('diagnosis', df, col='gender', wide=True, 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, table_format="markdown")
+
+print("All visualizations and tables have been generated successfully!")
+```
+
+See `examples/demo.py` for a runnable version.
+
+## API Reference
+
+### DataVisualiser Class
+
+```python
+class DataVisualiser(
+    record_unit_name="patient",
+    figures_dirpath=None,
+    tables_dirpath=None,
+    create_dirs=False,
+    nan_label="NaN",
+    fig_format="png",
+    dpi=None,
+    table_format="latex",
+)
+```
+
+`save_fig=True` / `save_table=True` require the corresponding directory to be configured and raise a `ValueError` otherwise. Saved figures are closed after writing.
+
+#### Count Visualizations
+
+- `get_count_plot(var, df, show_nan=True, save_fig=False, plot_kwargs=None, xlabels_rotation=None, forced_order=None)` -> `(fig, ax)`
+- `get_count_stratified_plot(var, df, col, show_nan=True, show_nan_col=True, save_fig=False, col_wrap=3, plot_kwargs=None, xlabels_rotation=None, forced_order=None, forced_order_col=None)` -> `FacetGrid`
+- `get_count_stats_df(var, df, show_nan=True, save_table=False, percentage=True, add_total=False, round_n_digits=1, forced_order=None, table_format=None)` -> `DataFrame`
+- `get_count_stratified_stats_df(var, df, col, show_nan=True, show_nan_col=True, save_table=False, percentage=True, round_n_digits=1, forced_order=None, forced_order_col=None, wide=False, table_format=None)` -> `DataFrame` (percentages are within each stratum; `wide=True` returns strata as columns)
+
+#### Distribution Visualizations
+
+- `get_dist_plot(var, df, save_fig=False, plot_kwargs=None, xlabels_rotation=None)` -> `(fig, ax)` (`plot_kwargs` defaults to `{"kde": True}`)
+- `get_dist_stratified_plot(var, df, col, show_nan_col=True, save_fig=False, col_wrap=3, plot_kwargs=None, xlabels_rotation=None, forced_order_col=None)` -> `FacetGrid`
+- `get_dist_hued_plot(var, df, hue, show_nan_col=True, save_fig=False, plot_kwargs=None, xlabels_rotation=None, forced_order_col=None)` -> `FacetGrid`
+- `get_box_stratified_plot(var, df, col, kind="box", show_nan_col=True, save_fig=False, plot_kwargs=None, xlabels_rotation=None, forced_order_col=None)` -> `(fig, ax)` (`kind` is `"box"` or `"violin"`)
+- `get_dist_stats_df(var, df, save_table=False, round_n_digits=None, table_format=None)` -> `DataFrame`
+- `get_dist_stratified_stats_df(var, df, col, show_nan_col=True, save_table=False, forced_order_col=None, round_n_digits=None, table_format=None)` -> `DataFrame`
+
+The distribution methods require a numeric `var` (a `TypeError` is raised otherwise). When `round_n_digits` is `None`, the number of decimals written to the table is derived from the standard deviation of the data.
+
+#### Output files
+
+| Method | File name (in `figures_dirpath` / `tables_dirpath`) |
+| --- | --- |
+| `get_count_plot` | `count_plot_{var}.{fig_format}` |
+| `get_count_stratified_plot` | `count_plot_{var}_for_each_{col}.{fig_format}` |
+| `get_dist_plot` | `dist_plot_{var}.{fig_format}` |
+| `get_dist_stratified_plot` | `dist_plot_{var}_for_each_{col}.{fig_format}` |
+| `get_dist_hued_plot` | `dist_plot_{var}_for_hue_{hue}.{fig_format}` |
+| `get_box_stratified_plot` | `{kind}_plot_{var}_for_each_{col}.{fig_format}` |
+| `get_count_stats_df` | `count_stats_table_{var}.{tex,csv,md,html}` |
+| `get_count_stratified_stats_df` | `count_stats_table_{var}_for_each_{col}.{tex,csv,md,html}` |
+| `get_dist_stats_df` | `dist_stats_table_{var}.{tex,csv,md,html}` |
+| `get_dist_stratified_stats_df` | `dist_stats_table_{var}_for_each_{col}.{tex,csv,md,html}` |
+
+LaTeX tables use `booktabs` rules (`\toprule`, `\midrule`, `\bottomrule`), bold column titles and escaped special characters (`#`, `%`, `_`, `&`, ...).
+
+### Helper functions
+
+- `prepare_categorical(series, show_nan=True, forced_order=None, nan_label="NaN")` -> ordered categorical `Series` of string labels
+- `categorise_variable_in_df(var, df, forced_order=None, nan_replacement_str="NaN")` -> categorises a column in place
+- `dataframe_to_latex(df, bold_header=True, round_n_digits=None, na_rep="", column_format=None)` -> `str`
+- `dataframe_to_markdown(df, round_n_digits=None, na_rep="")` -> `str`
+
+## Development
+
+```bash
+uv sync --group dev        # or: pip install -e ".[dev]"
+uv run pytest
+uv run flake8 src tests examples --max-line-length=120
+```
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.