bw2data
=======

.. py:module:: bw2data


Subpackages
-----------

.. toctree::
   :maxdepth: 1

   /content/api/bw2data/backends/index
   /content/api/bw2data/bin/index
   /content/api/bw2data/search/index


Submodules
----------

.. toctree::
   :maxdepth: 1

   /content/api/bw2data/configuration/index
   /content/api/bw2data/data_store/index
   /content/api/bw2data/database/index
   /content/api/bw2data/errors/index
   /content/api/bw2data/fatomic/index
   /content/api/bw2data/filesystem/index
   /content/api/bw2data/ia_data_store/index
   /content/api/bw2data/logs/index
   /content/api/bw2data/meta/index
   /content/api/bw2data/method/index
   /content/api/bw2data/parameters/index
   /content/api/bw2data/project/index
   /content/api/bw2data/proxies/index
   /content/api/bw2data/query/index
   /content/api/bw2data/serialization/index
   /content/api/bw2data/sqlite/index
   /content/api/bw2data/updates/index
   /content/api/bw2data/utils/index
   /content/api/bw2data/validate/index
   /content/api/bw2data/weighting_normalization/index


Attributes
----------

.. autoapisummary::

   bw2data.calculation_setups
   bw2data.config
   bw2data.databases
   bw2data.dynamic_calculation_setups
   bw2data.geomapping
   bw2data.mapping
   bw2data.methods
   bw2data.normalizations
   bw2data.parameters
   bw2data.preferences
   bw2data.projects
   bw2data.weightings


Classes
-------

.. autoapisummary::

   bw2data.DataStore
   bw2data.IndexManager
   bw2data.Method
   bw2data.Normalization
   bw2data.ProcessedDataStore
   bw2data.Searcher
   bw2data.Weighting


Functions
---------

.. autoapisummary::

   bw2data.Database
   bw2data.convert_backend
   bw2data.get_activity
   bw2data.set_data_dir


Package Contents
----------------

.. py:class:: DataStore(name)

   Bases: :py:obj:`object`


   Base class for all Brightway2 data stores. Subclasses should define:

       * **metadata**: A :ref:`serialized-dict` instance, e.g. ``databases`` or ``methods``. The custom is that each type of data store has a new metadata store, so the data store ``Foo`` would have a metadata store ``foos``.
       * **validator**: A data validator. Optional. See bw2data.validate.




   .. py:method:: _get_metadata()


   .. py:method:: _set_metadata(value)


   .. py:method:: backup()

      Save a backup to ``backups`` folder.

      :returns: File path of backup.



   .. py:method:: copy(name)

      Make a copy of this object with a new ``name``.

      This method only changes the name, but not any of the data or metadata.

      :param \* *name*: Name of the new object.
      :type \* *name*: object

      :returns: The new object.



   .. py:method:: deregister()

      Remove an object from the metadata store. Does not delete any files.



   .. py:method:: load()

      Load the intermediate data for this object.

      :returns: The intermediate data.



   .. py:method:: register(**kwargs)

      Register an object with the metadata store. Takes any number of keyword arguments.



   .. py:method:: validate(data)

      Validate data. Must be called manually.



   .. py:method:: write(data)

      Serialize intermediate data to disk.

      :param \* *data*: The data
      :type \* *data*: object



   .. py:attribute:: _intermediate_dir
      :value: 'intermediate'



   .. py:attribute:: _metadata
      :value: None



   .. py:property:: filename
      Remove filesystem-unsafe characters and perform unicode normalization on ``self.name`` using :func:`.utils.safe_filename`.


   .. py:attribute:: metadata


   .. py:attribute:: name


   .. py:property:: registered


   .. py:attribute:: validator
      :value: None



.. py:class:: IndexManager(database_path, dir_name='whoosh')

   Bases: :py:obj:`object`


   .. py:method:: _format_dataset(ds)


   .. py:method:: add_dataset(ds)


   .. py:method:: add_datasets(datasets)


   .. py:method:: create()


   .. py:method:: delete_database()


   .. py:method:: delete_dataset(ds)


   .. py:method:: get()


   .. py:method:: update_dataset(ds)


   .. py:attribute:: path


.. py:class:: Method

   Bases: :py:obj:`bw2data.ia_data_store.ImpactAssessmentDataStore`

   .. autoapi-inheritance-diagram:: bw2data.Method
      :parts: 1
      :private-bases:


   A manager for an impact assessment method. This class can register or deregister methods, write intermediate data, process data to parameter arrays, validate, and copy methods.

   The Method class never holds intermediate data, but it can load or write intermediate data. The only attribute is *name*, which is the name of the method being managed.

   Instantiation does not load any data. If this method is not yet registered in the metadata store, a warning is written to ``stdout``.

   Methods are hierarchally structured, and this structure is preserved in the method name. It is a tuple of strings, like ``('ecological scarcity 2006', 'total', 'natural resources')``.

   The data schema for IA methods is:

   .. code-block:: python

           Schema([Any(
               [valid_tuple, maybe_uncertainty],         # site-generic
               [valid_tuple, maybe_uncertainty, object]  # regionalized
           )])

   where:
       * *valid_tuple* (tuple): A dataset identifier, like ``("biosphere", "CO2")``.
       * *maybe_uncertainty* (uncertainty dict or number): Either a number or an uncertainty dictionary.
       * *object* (object, optional) is a location identifier, used only for regionalized LCIA.

   :param \* *name*: Name of impact assessment method to manage.
   :type \* *name*: tuple


   .. py:method:: add_mappings(data)


   .. py:method:: process_data(row)


   .. py:method:: write(data, process=True)

      Serialize intermediate data to disk.

      Sets the metadata key ``num_cfs`` automatically.



   .. py:attribute:: _metadata


   .. py:attribute:: dtype_fields


   .. py:attribute:: validator


.. py:class:: Normalization(name)

   Bases: :py:obj:`bw2data.ia_data_store.ImpactAssessmentDataStore`

   .. autoapi-inheritance-diagram:: bw2data.Normalization
      :parts: 1
      :private-bases:


   LCIA normalization data - used to transform meaningful units, like mass or damage, into "person-equivalents" or some such thing.

   The data schema for IA normalization is:

   .. code-block:: python

           Schema([
               [valid_tuple, maybe_uncertainty]
           ])

   where:
       * ``valid_tuple`` is a dataset identifier, like ``("biosphere", "CO2")``
       * ``maybe_uncertainty`` is either a number or an uncertainty dictionary



   .. py:method:: add_mappings(data)

      Add each normalization flow (should be biosphere flows) to global mapping



   .. py:method:: process_data(row)

      Return values that match ``dtype_fields``, as well as number or uncertainty dictionary



   .. py:attribute:: _metadata


   .. py:attribute:: dtype_fields


   .. py:attribute:: validator


.. py:class:: ProcessedDataStore(name)

   Bases: :py:obj:`DataStore`

   .. autoapi-inheritance-diagram:: bw2data.ProcessedDataStore
      :parts: 1
      :private-bases:


   Brightway2 data stores that can be processed to NumPy arrays. In addition to ``metadata`` and (optionally) ``validator``, subclasses should define:

       * **dtype_fields**: A list of fields to construct a NumPy structured array, e.g. ``[('foo', np.int), ('bar', np.float)]``. Fields names **must** be bytestrings, not unicode (i.e. ``b"foo"`` instead of ``"foo"``). Uncertainty fields (``base_uncertainty_fields``) are added automatically.

   In order to use ``dtype_fields``, subclasses should override the method ``process_data``. This function takes rows of data, and returns the correct values for the custom dtype fields (as a tuple), **and** the ``amount`` field with its associated uncertainty. This second part is a little flexible - if there is no uncertainty, a number can be returned; otherwise, an uncertainty dictionary should be returned.

   Subclasses should also override ``add_mappings``. This method takes the entire dataset, and loads objects to :ref:`mapping` or :ref:`geomapping` as needed.




   .. py:method:: add_mappings(data)

      Add objects to ``mapping`` or ``geomapping``, if necessary.

      :param \* *data*: The data
      :type \* *data*: object



   .. py:method:: as_uncertainty_dict(value)

      Convert floats to ``stats_arrays`` uncertainty dict, if necessary



   .. py:method:: dtype_field_order(dtype=None)


   .. py:method:: filepath_processed()


   .. py:method:: process()

      Process intermediate data from a Python dictionary to a `stats_arrays <https://pypi.python.org/pypi/stats_arrays/>`_ array, which is a `NumPy <http://numpy.scipy.org/>`_ `Structured <http://docs.scipy.org/doc/numpy/reference/generated/numpy.recarray.html#numpy.recarray>`_ `Array <http://docs.scipy.org/doc/numpy/user/basics.rec.html>`_. A structured array (also called record array) is a heterogeneous array, where each column has a different label and data type.

      Processed arrays are saved in the ``processed`` directory.

      If the uncertainty type is no uncertainty, undefined, or not specified, then the 'amount' value is used for 'loc' as well. This is needed for the random number generator.

      Doesn't return anything, but writes a file to disk.





   .. py:method:: process_data(row)
      :abstractmethod:


      Translate data into correct order



   .. py:method:: validate(data)

      Validate data. Must be called manually.



   .. py:method:: write(data, process=True)

      Serialize intermediate data to disk.

      :param \* *data*: The data
      :type \* *data*: object



   .. py:attribute:: base_uncertainty_fields


   .. py:property:: dtype
      Returns both the generic ``base_uncertainty_fields`` plus class-specific ``dtype_fields``. ``dtype`` determines the columns of the :ref:`processed array <processing-data>`.


   .. py:attribute:: dtype_fields
      :value: None



.. py:class:: Searcher(database)

   Bases: :py:obj:`object`


   .. py:method:: search(string, limit=25, facet=None, proxy=True, boosts=None, filter=None, mask=None)


   .. py:attribute:: _database


.. py:class:: Weighting(name)

   Bases: :py:obj:`bw2data.ia_data_store.ImpactAssessmentDataStore`

   .. autoapi-inheritance-diagram:: bw2data.Weighting
      :parts: 1
      :private-bases:


   LCIA weighting data - used to combine or compare different impact categories.

   The data schema for weighting is a one-element list:

   .. code-block:: python

           Schema(All(
               [uncertainty_dict],
               Length(min=1, max=1)
           ))



   .. py:method:: process_data(row)

      Return an empty tuple (as ``dtype_fields`` is empty), and the weighting uncertainty dictionary.



   .. py:method:: write(data)

      Because of DataStore assumptions, need a one-element list



   .. py:attribute:: _metadata


   .. py:attribute:: dtype_fields
      :value: []



   .. py:attribute:: validator


.. py:function:: Database(name, backend=None)

   A method that returns a database class instance. The default database type is `SingleFileDatabase`. `JSONDatabase` stores each process dataset in indented JSON in a separate file. Database types are specified in `databases[database_name]['backend']`.

   New database types can be registered with the config object:

   .. code-block:: python

       config.backends['backend type string'] = MyNewBackendClass

   .. warning:: Registering new backends must be done each time you start the Python interpreter.

   To test whether an object is a database subclass, do:

   .. code-block:: python

       from bw2data.backends import LCIBackend
       isinstance(my_database, LCIBackend)



.. py:function:: convert_backend(database_name, backend)

   Convert a Database to another backend.

   bw2data currently supports the `default` and `json` backends.

   :param \* `database_name`: Name of database.
   :type \* `database_name`: unicode
   :param \* `backend`: Type of database. `backend` should be recoginized by `DatabaseChooser`.
   :type \* `backend`: unicode

   Returns `False` if the old and new backend are the same. Otherwise returns an instance of the new Database object.


.. py:function:: get_activity(key)

.. py:function:: set_data_dir(dirpath, permanent=True)

   Set the Brightway2 data directory to ``dirpath``.

   If ``permanent`` is ``True``, then set ``dirpath`` as the default data directory.

   Creates ``dirpath`` if needed. Also creates basic directories, and resets metadata.



.. py:data:: calculation_setups

.. py:data:: config

.. py:data:: databases

.. py:data:: dynamic_calculation_setups

.. py:data:: geomapping

.. py:data:: mapping

.. py:data:: methods

.. py:data:: normalizations

.. py:data:: parameters

.. py:data:: preferences

.. py:data:: projects

.. py:data:: weightings