data-visualiser-package 0.1.0__tar.gz

data_visualiser_package-0.1.0/.github/workflows/python-package.yml

@@ -0,0 +1,61 @@
+name: Python Package
+
+on:
+  push:
+    branches: [ main ]
+    tags:
+      - 'v*'
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.7', '3.8', '3.9', '3.10', '3.11']
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      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 .
+    - 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
+        # exit-zero treats all errors as warnings
+        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=120 --statistics
+    - name: Test with pytest
+      run: |
+        pytest
+
+  deploy:
+    needs: test
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/')
+    
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.9'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build twine
+    - name: Build and publish
+      env:
+        TWINE_USERNAME: ${{ secrets.PYPI_USERNAME }}
+        TWINE_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
+      run: |
+        python -m build
+        twine upload dist/*

data_visualiser_package-0.1.0/.gitignore

@@ -0,0 +1,51 @@
+# Python-generated files
+__pycache__/
+*.py[cod]
+*$py.class
+build/
+dist/
+wheels/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# Distribution / packaging
+.Python
+downloads/
+develop-eggs/
+.eggs/
+sdist/
+var/
+.installed.cfg
+MANIFEST
+
+# IDE files
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Output directories
+figures/
+tables/
+demo_output/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# Environment variables
+.env
+.env.*
+
+# Logs
+*.log
+
+# OS specific files
+.DS_Store
+Thumbs.db
+desktop.ini

data_visualiser_package-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

data_visualiser_package-0.1.0/CHANGELOG.md

@@ -0,0 +1,16 @@
+# 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.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.1.0/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.

data_visualiser_package-0.1.0/MANIFEST.in

@@ -0,0 +1,12 @@
+include LICENSE
+include README.md
+include CHANGELOG.md
+include pyproject.toml
+include py.typed
+
+recursive-include examples *.py
+
+prune __pycache__
+global-exclude *.py[cod]
+global-exclude *.so
+global-exclude .DS_Store

data_visualiser_package-0.1.0/PKG-INFO

@@ -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/PYPI_PUBLISH.md

@@ -0,0 +1,70 @@
+# PyPI Publishing Guide
+
+This guide outlines how to build and publish the data-visualiser-package to PyPI.
+
+## Prerequisites
+
+Ensure you have the necessary tools:
+
+```bash
+pip install build twine
+```
+
+## Building the Package
+
+1. Navigate to the root directory of the project:
+
+```bash
+cd /path/to/data_visualiser_package
+```
+
+2. Build the distribution packages:
+
+```bash
+python -m build
+```
+
+This will create both source and wheel distributions in the `dist/` directory.
+
+## Publishing to PyPI
+
+### Publishing to Test PyPI (Recommended for testing)
+
+1. Upload to Test PyPI:
+
+```bash
+python -m twine upload --repository-url https://test.pypi.org/legacy/ dist/*
+```
+
+2. Install from Test PyPI to verify:
+
+```bash
+pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ data-visualiser-package
+```
+
+### Publishing to PyPI
+
+Once you've confirmed everything works on TestPyPI, you can publish to the main PyPI:
+
+```bash
+python -m twine upload dist/*
+```
+
+## Versioning
+
+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.
+
+## Cleaning Up
+
+Remove build directories before rebuilding:
+
+```bash
+rm -rf build/ dist/ *.egg-info/
+```

data_visualiser_package-0.1.0/README.md

@@ -0,0 +1,154 @@
+# 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/examples/demo.py

@@ -0,0 +1,95 @@
+"""
+DataVisualiser Package Demo
+
+This script demonstrates how to use the DataVisualiser package with a sample dataset.
+"""
+import os
+import pandas as pd
+import numpy as np
+from data_visualiser_package import DataVisualiser
+
+def main():
+    # Create output directories
+    os.makedirs("./demo_output/figures", exist_ok=True)
+    os.makedirs("./demo_output/tables", exist_ok=True)
+    
+    # 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),
+        'treatment': np.random.choice(['Drug A', 'Drug B', 'Placebo', None], n),
+        'response': np.random.choice(['Good', 'Moderate', 'Poor', None], n, p=[0.5, 0.3, 0.15, 0.05]),
+    }
+    
+    # Create a DataFrame
+    df = pd.DataFrame(data)
+    
+    print("Sample data created:")
+    print(df.head())
+    print(f"\nDataset shape: {df.shape}")
+    print("\nData types:")
+    print(df.dtypes)
+    print("\nMissing values:")
+    print(df.isna().sum())
+    
+    # Initialize the DataVisualiser
+    dv = DataVisualiser(
+        record_unit_name="patient",
+        figures_dirpath="./demo_output/figures",
+        tables_dirpath="./demo_output/tables",
+        create_dirs=True
+    )
+    
+    print("\n1. Creating count plots...")
+    # Create count plots for categorical variables
+    dv.get_count_plot('gender', df, save_fig=True)
+    dv.get_count_plot('diagnosis', df, save_fig=True)
+    dv.get_count_plot('treatment', df, save_fig=True)
+    dv.get_count_plot('response', df, save_fig=True)
+    
+    print("2. Creating stratified count plots...")
+    # Create stratified count plots
+    dv.get_count_stratified_plot('diagnosis', df, col='gender', save_fig=True)
+    dv.get_count_stratified_plot('response', df, col='treatment', save_fig=True)
+    
+    print("3. Creating distribution plots...")
+    # Distribution plots for numerical variables
+    dv.get_dist_plot('age', df, save_fig=True)
+    dv.get_dist_plot('heart_rate', df, save_fig=True)
+    dv.get_dist_plot('blood_pressure', df, save_fig=True)
+    
+    print("4. Creating stratified distribution plots...")
+    # Create stratified distribution plots
+    dv.get_dist_stratified_plot('age', df, col='gender', save_fig=True)
+    dv.get_dist_stratified_plot('heart_rate', df, col='diagnosis', save_fig=True)
+    
+    print("5. Creating hued distribution plots...")
+    # Create hued distribution plots
+    dv.get_dist_hued_plot('blood_pressure', df, hue='gender', save_fig=True)
+    
+    print("6. Generating statistics tables...")
+    # Generate statistics tables
+    count_stats = dv.get_count_stats_df('diagnosis', df, save_table=True)
+    print("\nCount statistics for diagnosis:")
+    print(count_stats)
+    
+    dist_stats = dv.get_dist_stats_df('age', df, save_table=True)
+    print("\nDistribution statistics for age:")
+    print(dist_stats)
+    
+    strat_dist_stats = dv.get_dist_stratified_stats_df('heart_rate', df, col='gender', save_table=True)
+    print("\nStratified distribution statistics for heart_rate by gender:")
+    print(strat_dist_stats)
+    
+    print("\nAll visualizations and tables have been generated successfully!")
+    print(f"Check the demo_output directory for the generated files.")
+
+if __name__ == "__main__":
+    main()