Metadata-Version: 2.1
Name: pytest-bootstrap
Version: 0.2.1
Summary: UNKNOWN
Home-page: UNKNOWN
License: UNKNOWN
Platform: UNKNOWN
Classifier: Framework :: Pytest
Description-Content-Type: text/x-rst
Provides-Extra: tests
Provides-Extra: docs

🧪 pytest-bootstrap
===================

.. image:: https://github.com/tillahoffmann/pytest-bootstrap/actions/workflows/main.yml/badge.svg
  :target: https://github.com/tillahoffmann/pytest-bootstrap/actions/workflows/main.yml
  :alt: Build status.
.. image:: https://readthedocs.org/projects/pytest-bootstrap/badge/?version=latest
  :target: https://pytest-bootstrap.readthedocs.io/en/latest/?badge=latest
  :alt: Documentation status.
.. image:: https://img.shields.io/pypi/v/pytest-bootstrap
  :target: https://pypi.org/project/pytest-bootstrap/
  :alt: PyPI package version.

Scientific software development often relies on stochasticity, e.g. for `Monte Carlo <https://en.wikipedia.org/wiki/Monte_Carlo_integration>`_ integration or simulating the `Ising model <https://en.wikipedia.org/wiki/Ising_model>`_. Testing non-deterministic code is difficult. This package offers a bootstrap test to validate stochastic algorithms, including multiple hypothesis correction for vector statistics. It can be installed by running :code:`pip install pytest-bootstrap`.

Example
-------

Suppose we want to implement the expected value of `log-normal distribution <https://en.wikipedia.org/wiki/Log-normal_distribution>`_ with location parameter :code:`\mu` and scale parameter :code:`\sigma`.

.. code-block:: python

  >>> import numpy as np
  >>>
  >>> def lognormal_expectation(mu, sigma):
  ...   return np.exp(mu + sigma ** 2 / 2)
  >>>
  >>> def lognormal_expectation_wrong(mu, sigma):
  ...   return np.exp(mu + sigma ** 2)

We can validate our implementation by simulating from a lognormal distribution and comparing with the bootstrapped mean.

.. code-block:: python

  >>> from pytest_bootstrap import bootstrap_test
  >>>
  >>> mu = -1
  >>> sigma = 1
  >>> reference = lognormal_expectation(mu, sigma)
  >>> x = np.exp(np.random.normal(mu, sigma, 1000))
  >>> result = bootstrap_test(x, np.mean, reference)

This returns a summary of the test, such as the bootstrapped statistics.

.. code-block:: python

  >>> result.keys()
  dict_keys(['alpha', 'alpha_corrected', 'reference', 'lower', 'upper',
             'z_score', 'median', 'iqr', 'tol', 'statistics'])

Comparing with our incorrect implementation reveals the bug.

.. code-block:: python

  >>> reference_wrong = lognormal_expectation_wrong(mu, sigma)
  >>> result = bootstrap_test(x, np.mean, reference_wrong)
  Traceback (most recent call last):
    ...
  pytest_bootstrap.BootstrapTestError: {'alpha': 0.01, reference: 1.0, ...

Visualising the bootstrapped distribution can help identify discrepancies between the bootstrapped statistics and the theoretical reference value.

:code:``
  :caption: Histogram of bootstrapped means reveals the erroneous implementation of the log-normal mean.

A comprehensive set of examples can be found in `the tests <https://github.com/tillahoffmann/pytest-bootstrap/blob/main/tests/test_pytest_bootstrap.py>`_.

Interface
---------

:code:`.. automodule:: pytest_bootstrap`
  :members:


