UncertaintyWrapper 0.4.2
Uncertainty wrapper using estimated Jacobian

.. image:: https://travis-ci.org/BreakingBytes/UncertaintyWrapper.svg?branch=master
    :target: https://travis-ci.org/BreakingBytes/UncertaintyWrapper

UncertaintyWrapper
==================

Use ``@unc_wrapper`` decorator to wrap any Python callable to append the
covariance and Jacobian matrices to the return values. See documentation and
tests for usage and examples.

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

Use ``pip install UncertaintyWrapper`` to install from
`PyPI <https://pypi.python.org/pypi/UncertaintyWrapper>`_ or download a source
distribution, extract and use ``python setup.py install``.

Requirements
------------

* `NumPy <http://www.numpy.org/>`_

Optional Requirements
~~~~~~~~~~~~~~~~~~~~~

* `Nose <https://nose.readthedocs.org/en/latest/index.html>`_ for testing.
* `Sphinx <http://www.sphinx-doc.org/en/stable/>`_ to build documentation.
* `NREL SOLPOS <http://rredc.nrel.gov/solar/codesandalgorithms/solpos/>`_ for testing
* `AlgoPy <https://pythonhosted.org/algopy/>`_ for testing

Usage
-----

Example::

    from uncertainty_wrapper import unc_wraper
    import numpy as np

    @unc_wrapper
    def f(x):
        return np.exp(x)

    x, cov = np.array([[1.0]]), np.array([[0.1]])
    f(x, __covariance__=cov)

Returns::

    (array([[ 2.71828183]]),      # exp(1.0)
     array([[[ 0.73890561]]]),    # (delta-f)^2 = (df/dx)^2 * (delta-x)^2
     array([[[ 2.71828183]]]))    # df/dx = exp(x)


History
-------
Releases are named after
`geological eons, periods and epochs <https://en.wikipedia.org/wiki/Geologic_time_scale>`_.

v0.4.2 Terreneuvian Series
~~~~~~~~~~~~~~~~~~~~~~~~~~
* futurize
* remove pint

`v0.4.1 <https://github.com/BreakingBytes/UncertaintyWrapper/releases/tag/v0.4.1>`_ `Paleozoic Era <https://en.wikipedia.org/wiki/Paleozoic>`_
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* Jagged arrays of covariance keys work now.
* simplify

`v0.4 <https://github.com/BreakingBytes/UncertaintyWrapper/releases/tag/v0.4>`_ `Phanerozoic Era <https://en.wikipedia.org/wiki/Phanerozoic>`_
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* Fixes #5, ``ValueError`` if covariance keys have multiple observations
* fix covariance cross terms not scaled correctly

`v0.3.3 <https://github.com/BreakingBytes/UncertaintyWrapper/releases/tag/v0.3.3>`_ `Neoproterozoic Era <https://en.wikipedia.org/wiki/Neoproterozoic>`_
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* Fixes #4, ``ValueError`` if just one observation

`v0.3.2 <https://github.com/BreakingBytes/UncertaintyWrapper/releases/tag/v0.3.2>`_ `Mesoproterozoic Era <https://en.wikipedia.org/wiki/Mesoproterozoic>`_
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* Fixes #2, don't need to tile scalar x for multiple observations
* Fixes #3, use sparse matrices for dot product instead of dense
* uses pvlib example instead of proprietary solar_utils


`v0.3.1 <https://github.com/BreakingBytes/UncertaintyWrapper/releases/tag/v0.3.1>`_ `Paleoproterozoic Era <https://en.wikipedia.org/wiki/Paleoproterozoic>`_
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* Fixes #1 works with Pint's @ureg.wraps()
* Use indices for positional arguments. Don't use inspect.argspec since not
  guaranteed to be the same for wrapped or decorated functions
* Test Jacobian estimate for IV with `AlgoPy <https://pythonhosted.org/algopy/>`_
* Show Jacobian errors plot in getting started docs.


`v0.3 <https://github.com/BreakingBytes/UncertaintyWrapper/releases/tag/v0.3>`_ `Proterozoic Eon <https://en.wikipedia.org/wiki/Proterozoic>`_
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* new ``unc_wrapper_args()`` allows selection of independent variables that the
  partial derivatives are with respect to and also grouping those arguments
  together so that in the original function they can stay unpacked.
* return values are grouped correctly so that they can remain unpacked in
  original function. These allow Uncertainty Wrapper to be used with
  `Pint's wrapper <http://pint.readthedocs.org/en/latest/wrapping.html>`_
* covariance now specified as dimensionaless fraction of square of arguments
* more complex tests: IV curve and solar position (requires
  `NREL's solpos <http://rredc.nrel.gov/solar/codesandalgorithms/solpos/>`_)


`v0.2.1 <https://github.com/BreakingBytes/UncertaintyWrapper/releases/tag/v0.2>`_ `Eoarchean Era <https://en.wikipedia.org/wiki/Eoarchean>`_
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* update documentation


`v0.2 <https://github.com/BreakingBytes/UncertaintyWrapper/releases/tag/v0.2>`_ `Archean Eon <https://en.wikipedia.org/wiki/Archean>`_
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* Fix nargs and nf order mixup in Jacobian
* add more complex test
* fix tile cov by nobs
* move partial derivative to subfunction
* try threading, but same speed, and would only work with NumPy anyway


`v0.1 <https://github.com/BreakingBytes/UncertaintyWrapper/releases/tag/v0.1>`_ `Hadean Eon <https://en.wikipedia.org/wiki/Hadean>`_
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* adds covariance to output
* allows __covariance__ to be passed as input
* uses estimate Jacobian based on central finite difference method