Metadata-Version: 2.4
Name: mnplib
Version: 2.0.0a2
Summary: Machine learning with the Minimum Nescience Principle
Author-email: "R. Garcia Leiva" <rgarcialeiva@gmail.com>
License: GPL-3.0-only
Project-URL: Homepage, https://github.com/rleiva/mnplib
Project-URL: Repository, https://github.com/rleiva/mnplib
Project-URL: Issues, https://github.com/rleiva/mnplib/issues
Keywords: machine-learning,automl,minimum-nescience,scikit-learn,time-series
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
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: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.23
Requires-Dist: pandas>=1.5
Requires-Dist: scikit-learn>=1.2
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Provides-Extra: examples
Requires-Dist: jupyter>=1.0; extra == "examples"
Requires-Dist: matplotlib>=3.7; extra == "examples"

# Machine Learning with the Minimum Nescience Principle

`mnplib` is an open-source Python library for machine learning based on the **Minimum Nescience Principle**. It is built on top of [scikit-learn](https://scikit-learn.org/stable/) and provides tools for evaluating datasets, models, and automated machine-learning candidates through the lens of nescience.

The library is based on the [*Minimum Nescience Principle*](https://www.amazon.com/dp/B0GZH1FZ9J), a mathematical framework for measuring how well a problem is understood given a **representation** and a **description**. In machine learning, the representation is usually a dataset, while the description is a fitted model.

`mnplib` is currently focused on three main goals:

* measuring the quality of data representations;
* measuring the quality and complexity of fitted models;
* exploring nescience-guided alternatives to conventional AutoML.

> **Development status**
>
> `mnplib 2.0.0a1` is an alpha release. The API, documentation, examples, and automated searchers are still under active development. The package is suitable for experimentation and testing, but it should not yet be considered production-ready.

## Installation

Install the current alpha release from PyPI:

```bash
pip install mnplib==2.0.0a1
```

Because this is a pre-release, installing the explicit version is recommended.

## Core Concepts

The library is built around the notion of **nescience**, which combines several complementary quantities.

### Miscoding

`Miscoding` measures how well a dataset represents the target variable. It can be used to analyze feature relevance, feature redundancy, and the representational quality of the available data.

### Inaccuracy

`Inaccuracy` measures the error made by a fitted model. It compares the true target values with the model predictions using an complexity-theoretic perspective.

### Surfeit

`Surfeit` measures the unnecessary complexity of a model description. A model may be accurate but unnecessarily complex; surfeit is intended to capture this excess descriptive cost.

### Nescience

`Nescience` combines representation quality, model error, and model complexity into a single quantity. It can be used to compare models from different model families, provided that each model can be converted into an explicit representation containing:

* the selected feature subset;
* the prediction vector;
* the serialized model description.

## Automated Machine Learning

`mnplib` includes experimental AutoML tools for classification and regression.

Unlike conventional AutoML systems, the goal is not to perform a large hyperparameter grid search, or to run time consuming cross-validations. Instead, the current design explores candidate models generated by nescience-guided principles, such as:

* feature selection based on miscoding;
* robust accuracy computation;
* model complexity measured by serialization;
* optimal pruning paths, bounded local searches, ...

The automated searchers are still experimental and may change substantially before a stable release.

## User Guide

The user guide contains the following sections:

* [Feature Selection](https://github.com/rleiva/fastautoml/wiki/Feature-Selection)
* [Model Inaccuacy](https://github.com/rleiva/fastautoml/wiki/Model-Inaccuracy)
* [Model Complexity](https://github.com/rleiva/fastautoml/wiki/Model-Complexity)
* [Hyperparameters Selection](https://github.com/rleiva/fastautoml/wiki/Hyperparameters-Selection)
* [Auto Classification](https://github.com/rleiva/fastautoml/wiki/Auto-Classification)
* [Auto Regression](https://github.com/rleiva/fastautoml/wiki/Auto-Regression)
* [Time Series](https://github.com/rleiva/fastautoml/wiki/Time-Series-Analysis)
* [Anomalies Detection](https://github.com/rleiva/nescience/wiki/Anomalies-Detection)

## Quick Start: Classification

```python
from sklearn.datasets import load_breast_cancer

from mnplib.classifier import NescienceClassifier

X, y = load_breast_cancer(return_X_y=True)

model = NescienceClassifier()
model.fit(X, y)

print(model.predict(X))
print(model.score(X, y))
print(model.components())
```

## Quick Start: Regression

```python
from sklearn.datasets import make_regression

from mnplib.regressor import NescienceRegressor

X, y = make_regression(
    n_samples=100,
    n_features=5,
    n_informative=3,
    noise=0.1,
    random_state=42,
)

model = NescienceRegressor()

model.fit(X, y)

print(model.predict(X))
print(model.score(X, y))
print(model.components())
```

## Inspecting AutoML Results

After fitting an automated model, you can inspect the evaluated candidates:

```python
results = model.results_dataframe()
print(results.head())
```

The results table contains information such as:

* candidate name;
* model family;
* nescience score;
* miscoding components;
* inaccuracy;
* surfeit;
* selected features;
* description length;
* native estimator score.

You can also retrieve the best fitted estimator:

```python
best_model = model.get_model()
```

and obtain a structured explanation:

```python
explanation = model.explain()
print(explanation)
```

## Main Modules

The main public modules are:

* `mnplib.miscoding`
* `mnplib.inaccuracy`
* `mnplib.surfeit`
* `mnplib.nescience`
* `mnplib.classifier`
* `mnplib.regressor`
* `mnplib.timeseries`
* `mnplib.utils`

Some modules are still experimental and may change before the stable `2.0.0` release.

## Current Scope

The current alpha version includes support for several model families, including:

* decision trees;
* linear regression;
* logistic regression;
* Gaussian Naive Bayes;
* linear support-vector models;
* multilayer perceptrons.

Support varies by task and by model family. Some serializers and searchers are experimental.

The library intentionally avoids some common AutoML mechanisms in its default methodology, such as:

* broad hyperparameter grid search;
* cross-validation-based model selection;
* ensemble search as a default strategy.

This is a design choice: the purpose of `mnplib` is to explore machine learning through nescience-guided representations, descriptions, and model comparison.

## Testing

To run the test suite from the repository root:

```bash
python -m pip install -e .
python -m pytest tests
```

Using `python -m pytest` is recommended because it ensures that tests run with the same Python interpreter in which `mnplib` is installed.

## Contributing

This is an alpha release, and feedback is welcome.

Useful contributions include:

* testing the package on real datasets;
* reporting bugs;
* improving documentation;
* adding examples;
* reviewing the mathematical consistency of the metrics;
* improving or extending model serializers;
* proposing better nescience-guided search strategies.

Please open issues or pull requests through the GitHub repository:

https://github.com/rleiva/mnplib

## Reporting Issues

When reporting a bug, please include:

* the installed `mnplib` version;
* the Python version;
* the operating system;
* a minimal code example;
* the full error traceback;
* the dataset shape and target type, when relevant.

You can check the installed version with:

```python
import mnplib

print(mnplib.__version__)
```

## Project Status

`mnplib 2.0.0a1` is the first alpha release of the redesigned library. The package is being actively revised, and several parts of the API may still change.

The current priority is to stabilize:

* empirical code-length utilities;
* miscoding, inaccuracy, surfeit, and nescience metrics;
* explicit model serialization;
* automated classification and regression workflows;
* examples and documentation.

## License

See the repository license file for licensing details.

## Citation

If you use `mnplib` in academic or research work, please cite the associated theoretical work on the [*Minimum Nescience Principle*](https://www.amazon.com/dp/B0GZH1FZ9J). A formal citation entry will be added in a future release.
