Metadata-Version: 2.4
Name: ffx
Version: 2.1.0
Summary: Fast Function Extraction: A fast, scalable, and deterministic symbolic regression tool.
Project-URL: Homepage, https://github.com/natekupp/ffx
Project-URL: Repository, https://github.com/natekupp/ffx
Author-email: Trent McConaghy <gtrent@gmail.com>, Nate Kupp <nathan.kupp@gmail.com>
Maintainer-email: Nate Kupp <nathan.kupp@gmail.com>
License: FFX Software Licence Agreement (like BSD, but adapted for
        non-commercial gain only)
        
        Copyright © 2011, Solido Design Automation Inc. Authored by Trent
        McConaghy. All rights reserved.
        
        Redistribution and use in source and binary forms, with or
        without modification, are permitted provided that the following
        conditions are met:
        
        Usage does not involve commercial gain.
        Redistributions of source code must retain the above copyright
        notice, this list of conditions and the following disclaimer.
        Redistributions in binary form must reproduce the above copyright
        notice, this list of conditions and the following disclaimer in
        the documentation and/or other materials provided with the
        distribution.
        Neither the name of the associated institutions nor the names of
        its contributors may be used to endorse or promote products
        derived from this software without specific prior written
        permission.
        For permissions beyond the scope of this license, please contact
        Trent McConaghy (trentmc@solidodesign.com).
        
        THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ‘'AS IS’‘ AND ANY
        EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
        PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
        DEVELOPERS OR THEIR INSTITUTIONS BE LIABLE FOR ANY DIRECT,
        INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
        GOODS OR SERVICES;LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
        INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
        WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
        NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
        THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
        
        Patent pending.
License-File: LICENSE
Keywords: machine learning,symbolic regression
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
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
Requires-Python: >=3.9
Requires-Dist: click>=5.0
Requires-Dist: contextlib2>=0.5.4
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: scikit-learn
Description-Content-Type: text/markdown

# FFX: Fast Function Extraction

[![CI](https://github.com/natekupp/ffx/workflows/CI/badge.svg)](https://github.com/natekupp/ffx/actions?query=workflow%3ACI)
[![Coverage Status](https://coveralls.io/repos/github/natekupp/ffx/badge.svg?branch=master)](https://coveralls.io/github/natekupp/ffx?branch=master)

FFX is a technique for symbolic regression. It is:

- **Fast** - runtime 5-60 seconds, depending on problem size
- **Scalable** - 1000 input variables, no problem!
- **Deterministic** - no need to "hope and pray".

## Installation

To install from PyPI, simply run:

```shell
pip install ffx
```

## Usage

FFX can either be run in stand-alone mode, or within your existing Python code using its own API or a Scikit-learn style API. It installs both a command-line utility `ffx` and the Python module `ffx`.

**Standalone**

```shell
ffx test train_X.csv train_y.csv test_X.csv test_y.csv
```

Use `ffx help` for more information on using the command-line utility.

**Python Module (run interface)**

The FFX Python module exposes a function, `ffx.run()`. The following snippet is a simple example of how to use FFX this way. Note that all arguments are expected to be of type `numpy.ndarray` or `pandas.DataFrame`.

```python
import numpy as np
import ffx

train_X = np.array( [ (1.5,2,3), (4,5,6) ] ).T
train_y = np.array( [1,2,3])

test_X = np.array( [ (5.241,1.23, 3.125), (1.1,0.124,0.391) ] ).T
test_y = np.array( [3.03,0.9113,1.823])

models = ffx.run(train_X, train_y, test_X, test_y, ["predictor_a", "predictor_b"])
for model in models:
    yhat = model.simulate(test_X)
    print(model)
```

**Scikit-Learn interface**

The FFX Python module also exposes a class, `ffx.FFXRegressor` which provides a Scikit-learn API, in particular `fit(X, y)`, `predict(X)`, and `score(X, y)` methods. In this API, all of the models produced by FFX (the whole Pareto front) are accessible after `fit()`ing as `_models`, but `predict()` and `score()` will use only the model of highest accuracy and highest complexity. Here is an example of usage.

```python
import numpy as np
import ffx

# This creates a dataset of 2 predictors
X = np.random.random((20, 2))
y = 0.1 * X[:, 0] + 0.5 * X[:, 1]

train_X, test_X = X[:10], X[10:]
train_y, test_y = y[:10], y[10:]

FFX = ffx.FFXRegressor()
FFX.fit(train_X, train_y)
print("Prediction:", FFX.predict(test_X))
print("Score:", FFX.score(test_X, test_y))
```

## Technical details

- Circuits-oriented description: [Slides](http://trent.st/content/2011-CICC-FFX-slides.ppt) [Paper](http://trent.st/content/2011-CICC-FFX-paper.pdf) (CICC 2011)
- AI-oriented description [Slides](http://trent.st/content/2011-GPTP-FFX-slides.pdf) [Paper](http://trent.st/content/2011-GPTP-FFX-paper.pdf) (GPTP 2011)

## References

1. McConaghy, FFX: Fast, Scalable, Deterministic Symbolic Regression Technology, _Genetic Programming Theory and Practice IX_, Edited by R. Riolo, E. Vladislavleva, and J. Moore, Springer, 2011.
2. McConaghy, High-Dimensional Statistical Modeling and Analysis of Custom Integrated Circuits, _Proc. Custom Integrated Circuits Conference_, Sept. 2011
