Data Fitting with SciPy
=======================

|PyPI Version| |MIT License| |Coverage Status| |Build Status|

Check out the `example fits on
Fitalyzer <http://io.evansosenko.com/fitalyzer/?firebase=scipy-data-fitting>`__.
See the `Fitalyzer README <https://github.com/razor-x/fitalyzer>`__ for
details on how to use Fitalyzer for visualizing your fits.

Documentation
-------------

Documentation generated from source with
`pdoc <https://pypi.python.org/pypi/pdoc/>`__ for the latest version is
hosted at
`packages.python.org/scipy-data\_fitting/ <http://packages.python.org/scipy-data_fitting/>`__.

To get started quickly, check out the
`examples <https://github.com/razor-x/scipy-data_fitting/tree/master/examples>`__.

Then, refer to the source documentation for details on how to use each
class.

Basic usage
-----------

.. code:: python

    from scipy_data_fitting import Data, Model, Fit, Plot

    # Load data from a CSV file.
    data = Data('linear')
    data.path = 'linear.csv'
    data.error = (0.5, None)

    # Create a linear model.
    model = Model('linear')
    model.add_symbols('t', 'v', 'x_0')
    t, v, x_0 = model.get_symbols('t', 'v', 'x_0')
    model.expressions['line'] = v * t + x_0

    # Create the fit using the data and model.
    fit = Fit('linear', data=data, model=model)
    fit.expression = 'line'
    fit.independent = {'symbol': 't', 'name': 'Time', 'units': 's'}
    fit.dependent = {'name': 'Distance', 'units': 'm'}
    fit.parameters = [
        {'symbol': 'v', 'guess': 1, 'units': 'm/s'},
        {'symbol': 'x_0', 'value': 1, 'units': 'm'},
    ]

    # Save the fit result to a json file.
    fit.to_json(fit.name + '.json', meta=fit.metadata)

    # Save a plot of the fit to an image file.
    plot = Plot(fit)
    plot.save(fit.name + '.svg')
    plot.close()

Controlling the fitting process
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The above example will fit the line using the default algorithm
```scipy.optimize.curve_fit`` <http://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.curve_fit.html>`__.

For a linear fit, it may be more desirable to use a more efficient
algorithm.

For example, to use
```numpy.polyfit`` <http://docs.scipy.org/doc/numpy/reference/generated/numpy.polyfit.html>`__,
one could set a ``fit_function`` and allow both parameters to vary,

.. code:: python

    fit.parameters = [
        {'symbol': 'v', 'guess': 1, 'units': 'm/s'},
        {'symbol': 'x_0', 'guess': 1, 'units': 'm'},
    ]
    fit.options['fit_function'] = lambda f, x, y, p0, **op: (numpy.polyfit(x, y, 1), )

Controlling the fitting process this way allows, for example,
incorporating error values and computing and returning goodness of fit
information.

See
```scipy_data_fitting.Fit.options`` <http://packages.python.org/scipy-data_fitting/#scipy_data_fitting.Fit.options>`__
for further details on how to control the fit and also how to use
`lmfit <http://lmfit.github.io/lmfit-py/>`__.

Installation
------------

This package is registered on the Python Package Index (PyPI) at
`pypi.python.org/pypi/scipy-data\_fitting <https://pypi.python.org/pypi/scipy-data_fitting>`__.

Add this line to your application's ``requirements.txt``:

::

    scipy-data_fitting

And then execute:

.. code:: bash

    $ pip install -r requirements.txt

Or install it yourself as:

.. code:: bash

    $ pip install scipy-data_fitting

Depending on your system configuration, you may need to run the above
commands with ``sudo``. Alternatively, you may want to use a
`virtualenv <http://www.virtualenv.org/>`__, which is beyond the scope
of this documentation.

Note that the large scientific packages such as NumPy, SciPy, and
matplotlib may also be available via your system's package manager.

To live on the bleeding edge, instead of the package name
``scipy-data_fitting``, you can use this repository directly with

::

    git+https://github.com/razor-x/scipy-data_fitting.git@master#egg=scipy-data_fitting

Note about dependency versions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This package intentionally does not specify dependency versions. Thus,
pip will use whatever required packages are currently installed or fetch
the latest available version for missing dependencies.

If you want to control what package versions are used, you should
specify them explicitly in your project's own ``requirements.txt``.

Development
-----------

Source Repository
~~~~~~~~~~~~~~~~~

The `source <https://github.com/razor-x/scipy-data_fitting>`__ is hosted
at GitHub. Fork it on GitHub, or clone the project with

.. code:: bash

    $ git clone https://github.com/razor-x/scipy-data_fitting.git

Install dependencies with

.. code:: bash

    $ pip install -r requirements.txt

and install the package in development mode with

.. code:: bash

    $ python setup.py develop

Depending on your system configuration, you may need to run the above
command with ``sudo`` or use a
`virtualenv <http://www.virtualenv.org/>`__.

Note that the large scientific packages such as NumPy, SciPy, and
matplotlib may also be available via your system's package manager.

Documentation
~~~~~~~~~~~~~

Generate documentation with pdoc by running

.. code:: bash

    $ make docs

Tests
~~~~~

Run the tests with

.. code:: bash

    $ make tests

Examples
~~~~~~~~

Run an example with

.. code:: bash

    $ python examples/example_fit.py

or run all the examples with

.. code:: bash

    $ make examples

License
-------

This code is licensed under the MIT license.

Warranty
--------

This software is provided "as is" and without any express or implied
warranties, including, without limitation, the implied warranties of
merchantibility and fitness for a particular purpose.

.. |PyPI Version| image:: http://img.shields.io/pypi/v/scipy-data_fitting.svg?style=flat
   :target: https://pypi.python.org/pypi/scipy-data_fitting
.. |MIT License| image:: http://img.shields.io/badge/license-MIT-red.svg?style=flat
   :target: ./LICENSE.txt
.. |Coverage Status| image:: http://img.shields.io/coveralls/razor-x/scipy-data_fitting.svg?style=flat
   :target: https://coveralls.io/r/razor-x/scipy-data_fitting
.. |Build Status| image:: http://img.shields.io/travis/razor-x/scipy-data_fitting.svg?style=flat
   :target: https://travis-ci.org/razor-x/scipy-data_fitting
