Brightway-presamples
====================

This library allows you to use pre-generated values ("presamples") in LCA calculations. It builds on top of the `Brightway LCA framework <https://brightwaylca.org/>`__.

Pre-generated arrays can be used in improve LCA calculations in many ways:

    * Seeded pre-sampled Monte Carlo values are reproducible
    * Pre-generated static or stochastic values can be generated by complex, non-linear models, capturing system dynamics more accurately
    * Pre-sampled Monte Carlo values can capture correlations between parameters, such as between characterization factors, or between input and outputs (e.g. fuel use and CO2 emissions)
    * Direct use of population data avoids losses from fitting data to distributions

`Brightway-presamples` also introduces the idea of *campaigns*, which organize presamples and allow for the systematic exploration of choices.

Use of presamples in Monte Carlo calculations
---------------------------------------------

The Brightway calculation library `bw2calc` already knows how to load and use presamples. Using presamples in a calculation is therefore as simple as passing a list of presamples directories or a `Campaign` object to the LCA class you want to use. Internally, the `bw2calc` library will build the needed matrices for the calculation it is doing, and then replace elements in the matrices with values from the supplied presample arrays.

.. warning:: Due to the way presamples are implemented and the use of sparse matrices, presamples values must replace numbers *already present* in the matrix to be modified. Presamples should replace existing matrix values, not add new values to existing matrices.

Presamples can be used in both static and stochastic LCA calculations. However, the functions to insert presample values will always pick randomly from the available values. Therefore, if you are using presamples in static calculations you probably want to use presamples with only one possible value for each matrix element.

Presamples types
----------------

There are two types of presamples - numbers that can be directly inserted into matrices used in LCA calculations, and named parameter values which can be used in either sensitivity analysis or to generate additional outputs. We call the first type "matrix presamples", and the second type "parameter presamples".

.. _matrix-presamples:

Matrix presamples
*****************

Matrix presamples are an array of numbers that can be directly inserted into one of the matrices used in LCA calculations, such as the technosphere matrix. Brightway-presamples allows you to insert values into any matrix, including matrices only used in LCA extensions such as regionalization. When building matrix presamples, therefore, you must not only specify the numbers and where they apply, but also the matrix to be modified. Brightway-presamples contains helper functions to make this easy for common matrix presamples, such as those used in the technosphere, biosphere, and characterization matrices.

.. _parameter-presamples:

Parameter presamples
********************

.. _presample-directories:

Presample directories
---------------------

Regardless of presample type, all presamples are stored the same way. Each collection of presamples is stored in a directory. More than one presample, and mopre than one type of presample, can be stored in the same directory. Most commonly, this directory is in the same location as other Brightway2 data, those it doesn't have to be. The directory has the following files:

* ``datapackage.json``: A JSON file following the `datpackage standard <https://frictionlessdata.io/specs/data-package/>`__ with the metadata for these presamples. This is the only file that is **required** for a presample directory.
* ``{name}.{index}.indices.npy``: A numpy `structured array  <https://docs.scipy.org/doc/numpy-1.13.0/user/basics.rec.html>`__ that gives the matrix row and column index values for the sample data.
* ``{name}.{index}.samples.npy``: A numpy array that gives the numeric data to be inserted in the matrices.
* ``{name}.{index}.names.json``: A JSON file listing the names of variable parameters.

``name`` will be the same for each file in the directory. For each ``samples`` file (i.e. for each ``index`` value), there will be either an ``indices`` or a ``names`` file.

The integrity of presample directories and their files are checked each time they are loaded.

Using ``Brightway-presamples``
==============================

Generating presamples
---------------------

TODO

Saving presamples
-----------------

Presamples are stored in :ref:`presample-directories`, and saved using the function ``create_presamples_package``.

.. autofunction:: presamples.packaging.create_presamples_package

``matrix_presamples``
*********************

In cases most cases, ``matrix_presamples`` is a list of ``(samples, indices, matrix label)``.

* ``samples`` should be a two-dimensional Numpy array.
* ``indices`` is an iterable with row and (usually) column indices, in the same order and of the same length as ``samples``, with the exact format depending on the matrix to be constructed. These indices tell us where exactly to insert the samples into the matrix.
*  ``matrix label`` is a string giving the name of the matrix to be modified in the LCA class. This string is normally one of ``('technosphere', 'biosphere', 'cf')``.

.. note:: If you used the function TODO, then your output is already in the correct form.

If the presamples are for the **technosphere** matrix, then ``indices`` should have the form ``[(input id, output id, type)]``. ``input id`` and ``output id`` are activity identifiers like ``("my database", "my code")``. The ``type`` is an exchange type, i.e. one of "production", "technosphere", "biosphere", or "substitution".

If the presamples are for the **biosphere** matrix, then ``indices`` should have the form ``[(flow id, activity id)]``. Both these ``id`` values should should be activity identifiers like ``("my database", "my code")``.

Inventory presamples can include values for both the technosphere and biosphere matrices; you can use the ``split_inventory_presamples`` to split them up.

.. autofunction:: bw2_presamples.packaging.split_inventory_presamples

If the presamples are for the **characterization** matrix, then ``indices`` should have the form ``[flow id]``. The ``flow id`` should should be an activity identifier like ``("my flow database", "my code")``.

``parameter_presamples``
************************

``parameter_presamples`` is a list of ``(samples, names)``.

* ``samples`` should be a two dimensional Numpy array.
* ``names`` is a python list of variables names (as strings) in the same order and of the same length as ``samples``.

Presamples for custom matrices
******************************

TODO: Fill this out and move to a subsection.

Matrices outside the three with built-in functions (technosphere, biosphere, cf) can be accommodated in two different ways. First, you can write a custom formatter function, based on existing formatters like ``format_biosphere_presamples``, and add this formatter to the ``FORMATTERS`` registry:

.. code-block:: python

    from presamples import FORMATTERS

    def my_formatter(indices):
        # do something with the indices
        return some_data

    FORMATTERS['my matrix type'] = my_formatter

Second, you can also specify the metadata needed to process indices manually. The following arguments can be specified in order, dtype=None, row_formatter=None, metadata=None)

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   technical

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`