classifier-toolkit 0.2.2__tar.gz → 0.2.4__tar.gz

classifier_toolkit-0.2.4/.github/pull_request_template/default.md

@@ -0,0 +1,13 @@
+## Objective
+
+## Why
+
+## How
+
+## Publishing teps
+
+- [ ] Run the pipeline
+- [ ] Run all section examples with changes
+- [ ] Update version
+- [ ] Merge before publishing
+- [ ] Add a tag with the corresponding version

classifier_toolkit-0.2.4/.github/workflows/checks.yaml

@@ -0,0 +1,134 @@
+name: Checks
+
+on:
+  workflow_call:
+    secrets:
+      NEXUS_READER_PASSWORD:
+        required: true
+    inputs:
+      python_version:
+        required: false
+        type: string
+        default: "3.12.6"
+
+env:
+  UV_INDEX_URL: "https://${{ vars.NEXUS_READER_USERNAME }}:${{ secrets.NEXUS_READER_PASSWORD }}@package-registry.tooling-production.qonto.co/repository/pypi-proxies/simple"
+
+jobs:
+  dependencies:
+    runs-on: default
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ inputs.python_version }}
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y build-essential gcc g++ make
+
+      - name: Configure Git
+        run: |
+          git config --global url."https://x-access-token:${GITHUB_TOKEN}@github.com/".insteadOf "https://github.com/"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install uv
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          echo "$HOME/.local/bin" >> $GITHUB_PATH
+
+      - name: Cache uv
+        uses: actions/cache@v5
+        with:
+          path: |
+            ~/.cache/uv
+            .venv
+          key: ${{ runner.os }}-uv-${{ github.ref_name }}-${{ hashFiles('**/pyproject.toml', '**/uv.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-uv-${{ github.ref_name }}-
+
+      - name: Install dependencies
+        run: uv sync --group test --extra liveplotting
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  lint:
+    needs: dependencies
+    runs-on: default
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ inputs.python_version }}
+
+      - name: Install uv
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          echo "$HOME/.local/bin" >> $GITHUB_PATH
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y build-essential gcc g++ make
+
+      - name: Restore cache
+        uses: actions/cache@v5
+        with:
+          path: |
+            ~/.cache/uv
+            .venv
+          key: ${{ runner.os }}-uv-${{ github.ref_name }}-${{ hashFiles('**/pyproject.toml', '**/uv.lock') }}
+
+      - name: Install dependencies
+        run: uv sync --group lint
+
+      - name: Run linting
+        run: uv run make lint
+
+  test:
+    needs: dependencies
+    runs-on: default
+    strategy:
+      fail-fast: false
+      matrix:
+        test-group: [eda, feature_selection, feature_reduction]
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ inputs.python_version }}
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y build-essential gcc g++ make
+
+      - name: Install uv
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          echo "$HOME/.local/bin" >> $GITHUB_PATH
+
+      - name: Restore cache
+        uses: actions/cache@v5
+        with:
+          path: |
+            ~/.cache/uv
+            .venv
+            .pytest_cache
+          key: ${{ runner.os }}-uv-${{ github.ref_name }}-${{ hashFiles('**/pyproject.toml', '**/uv.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-uv-${{ github.ref_name }}-
+
+      - name: Install dependencies
+        run: uv sync --group test --extra exp --extra liveplotting
+
+      - name: Run tests (${{ matrix.test-group }})
+        run: uv run pytest tests/${{ matrix.test-group }}/ -v --lf --ff

classifier_toolkit-0.2.4/.github/workflows/master.yaml

@@ -0,0 +1,48 @@
+name: Master
+run-name: "${{ github.actor }} - Merge to Master"
+
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  run-checks:
+    name: Checks
+    uses: ./.github/workflows/checks.yaml
+    secrets:
+      NEXUS_READER_PASSWORD: ${{ secrets.NEXUS_READER_PASSWORD }}
+
+  build-and-publish:
+    needs: run-checks
+    runs-on: default
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.12.6"
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y build-essential gcc g++ make
+
+      - name: Install uv
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          echo "$HOME/.local/bin" >> $GITHUB_PATH
+
+      - name: Install dependencies
+        run: uv sync
+        env:
+          UV_INDEX_URL: "https://${{ vars.NEXUS_READER_USERNAME }}:${{ secrets.NEXUS_READER_PASSWORD }}@package-registry.tooling-production.qonto.co/repository/pypi-proxies/simple"
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish --token ${{ secrets.PYPI_TOKEN }}

classifier_toolkit-0.2.4/.github/workflows/working-branch.yaml

@@ -0,0 +1,14 @@
+name: Working Branch
+run-name: "${{ github.ref_name }} - Working Branch"
+
+on:
+  push:
+    branches-ignore:
+      - master
+
+jobs:
+  run-checks:
+    name: Checks
+    uses: ./.github/workflows/checks.yaml
+    secrets:
+      NEXUS_READER_PASSWORD: ${{ secrets.NEXUS_READER_PASSWORD }}

classifier_toolkit-0.2.4/.gitignore

@@ -0,0 +1,180 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+*.ipynb
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# VS Code
+.vscode/
+
+# Mac OS
+.DS_Store
+
+# Output files
+*.parquet
+*.csv
+/**/output/*
+
+# Catboost files
+catboost_info/
+
+# Gitkeep
+!/**/.gitkeep

classifier_toolkit-0.2.4/.python-version

@@ -0,0 +1 @@
+3.12

classifier_toolkit-0.2.4/.sqlfluff

@@ -0,0 +1,38 @@
+[sqlfluff]
+dialect = snowflake
+encoding = utf-8
+max_line_length = 120
+exclude_rules = AM06, ST06
+large_file_skip_byte_limit = 0
+templater = placeholder
+
+[sqlfluff:templater:placeholder]
+param_style = pyformat
+
+# Layout configuration
+[sqlfluff:layout:type:comma]
+line_position = trailing
+
+# Common rules
+[sqlfluff:indentation]
+tab_space_size = 4
+indent_unit = space
+
+# Some rules have their own specific config
+[sqlfluff:rules:capitalisation.keywords]
+capitalisation_policy = upper
+
+[sqlfluff:rules:capitalisation.identifiers]
+extended_capitalisation_policy = lower
+
+[sqlfluff:rules:references.consistent]
+single_table_references = consistent
+
+[sqlfluff:rules:capitalisation.functions]
+extended_capitalisation_policy = upper
+
+[sqlfluff:rules:capitalisation.literals]
+capitalisation_policy = upper
+
+[sqlfluff:rules:capitalisation.types]
+extended_capitalisation_policy = upper

classifier_toolkit-0.2.4/Makefile

@@ -0,0 +1,22 @@
+lint:
+	ruff check .
+	ruff format --check --diff .
+	sqlfluff lint . --processes 0
+
+lint-fix:
+	ruff check --fix .
+	ruff format .
+	sqlfluff fix . --processes 0
+
+format:
+	ruff format .
+	sqlfluff fix . --processes 0
+
+mypy:
+	mypy --install-types classifier_toolkit
+
+test:
+	pytest -v
+
+docs:
+	mkdocs serve

classifier_toolkit-0.2.4/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: classifier-toolkit
+Version: 0.2.4
+Author-email: "senih.yilmaz" <senih.yilmaz@qonto.com>, "jeremy.fraoua" <jeremy.fraoua@qonto.com>, "gauthier.marquand" <gauthier.marquand@qonto.com>, "arnaud.alepee" <arnaud.alepee@qonto.com>
+License-File: LICENSE
+Requires-Python: <3.13,>=3.9
+Requires-Dist: catboost<2.0.0,>=1.2.2
+Requires-Dist: category-encoders<3.0.0,>=2.6.3
+Requires-Dist: colorama<0.5.0,>=0.4.6
+Requires-Dist: lightgbm<5.0.0,>=4.5.0
+Requires-Dist: matplotlib<4.0.0,>=3.9.2
+Requires-Dist: nbformat>=5.10.4
+Requires-Dist: numpy<2.0
+Requires-Dist: optuna<4.0.0,>=3.5.0
+Requires-Dist: pandas<3.0.0,>=2.2.0
+Requires-Dist: polars<2.0.0,>=1.2.1
+Requires-Dist: pyarrow<19.0.0,>=18.0.0
+Requires-Dist: scikit-learn<2.0.0,>=1.4.0
+Requires-Dist: scipy<1.14
+Requires-Dist: shap<0.45.0,>=0.44.1
+Requires-Dist: statsmodels<0.15.0,>=0.14.2
+Requires-Dist: tabulate<0.10.0,>=0.9.0
+Requires-Dist: tqdm<5.0.0,>=4.66.0
+Requires-Dist: xgboost<3.0.0,>=2.1.1
+Provides-Extra: exp
+Requires-Dist: bayesian-optimization<3.0.0,>=2.0.0; extra == 'exp'
+Provides-Extra: liveplotting
+Requires-Dist: nbformat>=4.2.0; extra == 'liveplotting'
+Description-Content-Type: text/markdown
+
+[PyPI: classifier-toolkit](https://pypi.org/project/classifier-toolkit/)
+
+```bash
+pip install classifier-toolkit
+```
+
+# Classifier Toolkit
+
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Linting - Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Code style - Black](https://img.shields.io/badge/Code%20Style-Black-000000.svg)](https://github.com/psf/black)
+
+This is a new project.
+
+-----
+
+## Table of Content
+
+<!-- [[_TOC_]] -->
+
+1. [Installation](#installation)
+2. [Usage](#usage)
+3. [Modules Overview](#modules-overview)
+4. [Development & CI/CD](#development--cicd)
+5. [Future Work](#future-work)
+
+### Installation
+
+This library is published in the PyPI directory. To install, users can run pip install 'classifier_toolkit' command.
+
+### Usage
+
+This library automates binary classification tasks in the finance domain, specifically for default and fraud labeling. It includes several packages designed to address the main steps in any machine learning/data science task:
+
+1. **EDA**: accessible via `EDA_Toolkit`. Provides EDA and feature engineering functionality with all necessary visualizations.
+2. **Feature Reduction**: filter-style pre-selection pipeline (expert rules, low variance, drift, predictive power, counter-intuitive direction, high correlation).
+3. **Feature Selection**: wrapper and embedded methods (RFE, Boruta, Sequential, Bayesian, ElasticNet, MetaSelector).
+4. Model fitting and hyperparameter tuning: To be implemented.
+5. Evaluation and reporting: To be implemented.
+
+In the future, the package architectures will be included here. However, for now please consult the docstrings in the specific methods in the relevant modules.
+
+**Note**: that this library does not contain data wrangling steps (although it contains feature engineering), it's an intermediate step between EDA and feature engineering where users should fix any data quality related issues. Therefore, conducting the EDA is crucial to mitigate any issues before moving onto the feature engineering and the subsequent steps.
+
+### Modules Overview
+
+- **EDA Toolkit**: This module includes classes and methods for performing comprehensive exploratory data analysis. It provides automated warnings for data quality issues, univariate and bivariate analysis, and various data visualizations to help understand the dataset.
+
+- **Univariate Analysis**: This class focuses on the analysis of individual variables. It includes methods for calculating statistical measures, visualizing distributions, and assessing relationships between variables and a target through techniques like Cramer's V and Information Value. This helps in understanding the significance and distribution of each feature independently.
+
+- **Bivariate Analysis**: This class deals with the analysis of two variables to understand their relationship. It includes functionalities for generating correlation heatmaps, performing ANOVA tests between numerical and categorical variables, and computing pairwise Cramer's V for categorical features. This aids in identifying patterns and correlations between pairs of variables, which is crucial for feature selection and engineering.
+
+- **Feature Engineering**: This module assists in transforming features, handling missing values, encoding categorical variables, and more. It aims to enhance the dataset's quality for better model performance.
+
+- **Visualizations**: This module offers a wide range of plotting capabilities to visually analyze data distributions, relationships, and other crucial aspects of the dataset.
+
+- **Automated Warnings**: A utility to automatically check the dataset for common issues such as missing or duplicate values, outliers, and more, providing warnings to guide data cleaning efforts.
+
+- **Feature Reduction**: Filter-style pipeline that reduces the feature set *before* model-based selection. Six sequential steps, each independently configurable:
+  1. **Expert Rules** — drop features by hand-coded list.
+  2. **Low Variance** — drop near-constant numerical and categorical features.
+  3. **Drift** — drop features whose distribution has shifted (PSI, KS, JS and more).
+  4. **Predictive Power** — drop features with weak univariate Gini / PR-AUC.
+  5. **Counter-Intuitive Direction** — drop features violating a business prior.
+  6. **High Correlation** — drop pairwise-redundant features (Pearson/Spearman/Kendall; Cramér's V).
+
+  The `FeatureReducer` orchestrates all six steps in one sklearn-compatible `fit` / `transform` call.
+
+  ```python
+  from classifier_toolkit.feature_reduction import FeatureReducer
+
+  reducer = FeatureReducer(gini_threshold=0.01, numeric_correlation_threshold=0.85)
+  reducer.fit(X_train, y=y_train, X_val=X_val)
+  X_filtered = reducer.transform(X_train)
+
+  reducer.summary()                          # print pipeline summary
+  reducer.export_summary("summary.xlsx", format="excel")
+  ```
+
+  Standalone helpers are also available for ad-hoc analysis outside the pipeline:
+
+  ```python
+  from classifier_toolkit.feature_reduction import (
+      calculate_feature_predictive_metrics,  # Gini + PR-AUC for every feature
+      CorrelationAnalyser,                   # inspect all correlated pairs
+      DriftAnalyser,                         # inspect drift stats per feature
+  )
+  ```
+
+  Logs are **silent by default**. To enable them:
+
+  ```python
+  import logging
+
+  logging.basicConfig(level=logging.INFO)
+  logging.getLogger("classifier_toolkit.feature_reduction").setLevel(logging.INFO)
+  ```
+
+- **Feature Selection**: This module provides various feature selection techniques:
+  - **Embedded Methods**: Includes ElasticNet for regularization-based feature selection.
+  - **Wrapper Methods**:
+    - Recursive Feature Elimination (RFE) with support for various ensemble methods (Random Forest, XGBoost, LightGBM, CatBoost).
+    - Sequential Feature Selection (forward, backward, floating, and bidirectional).
+  - **Meta Selector**: Combines multiple feature selection methods to provide a robust selection.
+  - **Utility Functions**: Includes scoring functions and plotting utilities for feature importance visualization.
+
+### Development & CI/CD
+
+This project uses modern tooling for fast and efficient development workflows:
+
+#### Dependency Management
+- **UV**: Lightning-fast Python package installer and resolver (replacing Poetry)
+- Install UV: `curl -LsSf https://astral.sh/uv/install.sh | sh`
+- Install dependencies: `uv sync --group dev --group lint --group test`
+
+#### CI/CD Pipeline
+Our CI/CD pipeline is optimized for speed and efficiency:
+
+- **Parallel Test Execution**: Tests are split into two groups (`eda` and `feature_selection`) that run simultaneously, reducing test time by ~50%
+- **Shared Caching**: Both parallel jobs share the same dependency cache (~1.7GB), avoiding duplicate downloads
+- **Smart Test Reruns**: Failed tests run first (`pytest --lf --ff`) for faster feedback on fixes
+- **Master Protection**: Build tests only run on `master` branch and PRs targeting `master`, saving CI resources on feature branches
+- **Automatic Linting**: Code quality checks (Ruff, SQLFluff) run on every push
+
+**Pipeline Jobs:**
+1. `dependencies` - Installs and caches project dependencies
+2. `lint` - Runs code quality checks (Ruff, SQLFluff)
+3. `test` - Executes tests in parallel with shared cache
+4. `build_test` - Builds and validates package (master/PRs only)
+
+**Local Development:**
+```bash
+# Run linting
+uv run make lint
+
+# Run tests
+uv run make test
+
+# Build package
+uv build
+```
+
+### Future Work
+The next planned improvements and additions to the library include:
+* Adding model fitting and hyperparameter tuning functionalities.
+* Developing comprehensive evaluation and reporting tools to assist with model assessment.
+* Expanding documentation to include architecture diagrams and detailed usage examples.