Metadata-Version: 2.4
Name: varsculpt
Version: 0.1.0
Summary: Fast, shared C++ binning and distribution diagnostics for Python and R
Keywords: binning,discretization,mdlp,psi,feature-engineering
Author: Maria Calderon
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Project-URL: Homepage, https://github.com/glassbox-ml/varsculpt
Project-URL: Repository, https://github.com/glassbox-ml/varsculpt
Project-URL: Issues, https://github.com/glassbox-ml/varsculpt/issues
Requires-Python: >=3.8
Requires-Dist: numpy>=1.22
Requires-Dist: pandas>=1.5
Provides-Extra: plot
Requires-Dist: matplotlib>=3.5; extra == "plot"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: cibuildwheel>=2.23; extra == "dev"
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Description-Content-Type: text/markdown

# VarSculpt

VarSculpt provides fast binning, MDLP discretization and distribution diagnostics
for Python and R. Both interfaces call the same C++17 core so numerical results
and interval conventions remain aligned across languages.

The project is under active development. The first public Python release is
version `0.1.0`.

## Python installation

```bash
python -m pip install varsculpt
```

Install plotting support with:

```bash
python -m pip install "varsculpt[plot]"
```

## Python example

```python
import numpy as np
import varsculpt

rng = np.random.default_rng(123)
x = rng.normal(size=1_000)
y = (x + rng.normal(scale=0.7, size=x.size) > 0).astype(int)
x[::100] = np.nan

result = varsculpt.binning(x, y, method="mdlp", params={"minobs": 20})
print(result.splits)
print(result.summary())

comparison = varsculpt.compare_distributions(
    x[:500], x[500:], splits=result.splits
)
print(comparison.summary())
print("PSI:", comparison.psi, "KS:", comparison.ks)
comparison.plot(kind="density")
```

Numeric intervals follow `(left, right]`. Missing values are excluded when
learning cuts and retained in a dedicated `Missing` bin in summaries,
transformations and distribution comparisons.

## Main features

- Supervised MDLP discretization.
- Equal-width bins over full, quantile-trimmed or IQR-based ranges.
- Equal-frequency quantile bins and explicit custom cuts.
- Binary and continuous-target summaries.
- Missing-aware transformations and fuzzy memberships.
- PSI and KS distribution comparison on learned or reused cuts.
- Categorical summaries, ordering helpers and Lorenz/Gini diagnostics.

The complete interface is documented in
[`docs/BINNING_API.md`](docs/BINNING_API.md). Executable examples are available
under [`examples/python`](examples/python) and [`examples/r`](examples/r).

Interactive help documents arguments, return classes, methods and examples:

```python
help(varsculpt.binning)
help(varsculpt.BinningResult.transform)
help(varsculpt.compare_distributions)
```

```r
?binning
?transform.varsculpt_binning
?compare_distributions
methods(class = "varsculpt_binning")
```

## R package

The repository also contains the `varsculpt` R package, backed by the same core.
Build and install its self-contained source package with:

```bash
bash tools/make_cran_tar_v3.sh
R CMD INSTALL dist/varsculpt_*.tar.gz
```

## Development and validation

Create a development environment and install the project from the repository
root:

```bash
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev,plot]"
```

The complete validation builds the C++ core, Python wheel and R source package
in isolated temporary installations, runs their test suites, performs
`R CMD check`, and verifies cross-language numerical equality:

```bash
bash tools/build_and_test_all.sh
```

Build Python distributions directly with:

```bash
python -m build
python -m twine check dist/*
```

## Release process

Releases are built by GitHub Actions. A manual run publishes a candidate to
TestPyPI; publishing a GitHub Release whose tag matches the project version
publishes the validated artifacts to PyPI after approval of the protected
`pypi` environment. Authentication uses PyPI Trusted Publishing, so no
long-lived API token is stored in GitHub.

Detailed maintainer instructions are in
[`docs/RELEASING.md`](docs/RELEASING.md).

## License

VarSculpt is distributed under the [Apache License 2.0](LICENSE). See [NOTICE](NOTICE) for attribution information.
