Commits

Chris Mutel committed ae319ab

Add more documentation and split into different files

Comments (0)

Files changed (12)

bw2data/database.py

             config.dir, directory, name)).st_mtime)) for name in files])
 
     def process(self, version=None):
-        """Process intermediate data from a Python dictionary to a `NumPy <http://numpy.scipy.org/>`_ `Structured <http://docs.scipy.org/doc/numpy/reference/arrays.classes.html#record-arrays-numpy-rec>`_ `Array <http://docs.scipy.org/doc/numpy/user/basics.rec.html>`_. A structured array (also called record arrays) is a heterogeneous array, where each column has a different label and data type. These structured arrays act as a standard data format for LCA and Monte Carlo calculations, and are the native data format for the Stats Arrays package.
+        """
+Process intermediate data from a Python dictionary to a `NumPy <http://numpy.scipy.org/>`_ `Structured <http://docs.scipy.org/doc/numpy/reference/arrays.classes.html#record-arrays-numpy-rec>`_ `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. These structured arrays act as a standard data format for LCA and Monte Carlo calculations, and are the native data format for the Stats Arrays package.
 
-        Processed arrays are saved in the ``processed`` directory.
+Processed arrays are saved in the ``processed`` directory.
 
-        Args:
-            * *version* (int, optional): The version of the database to process
+The structure for processed inventory databases is:
+
+================ ======== ===================================
+Column name      Type     Description
+================ ======== ===================================
+uncertainty_type uint8    integer type defined in `stats_toolkit.uncertainty_choices`
+input            uint32   integer value from `Mapping`
+output           uint32   integer value from `Mapping`
+geo              uint32   integer value from `GeoMapping`
+row              uint32   column filled with `NaN` values, used for matrix construction
+col              uint32   column filled with `NaN` values, used for matrix construction
+type             uint8    integer type defined in `bw2data.utils.TYPE_DICTIONARY`
+amount           float32  location parameter, e.g. mean
+sigma            float32  shape parameter, e.g. std
+minimum          float32  minimum bound
+maximum          float32  maximum bound
+negative         bool     `amount` < 0
+================ ======== ===================================
+
+See also `NumPy data types <http://docs.scipy.org/doc/numpy/user/basics.types.html>`_.
+
+Args:
+    * *version* (int, optional): The version of the database to process
+
+Doesn't return anything, but writes a file to disk.
 
         """
         data = self.load(version)

bw2data/io/import_ecospold.py

 class Ecospold1Importer(object):
     """Import inventory datasets from ecospold XML format.
 
-    Does not have any arguments; instead, instantiate the class, and then import using the ``importer`` method, i.e. ``Ecospold1Importer().importer(filepath)``."""
+    Does not have any arguments; instead, instantiate the class, and then import using the ``importer`` method, i.e. ``Ecospold1Importer().importer(filepath)``.
+
+    """
     def importer(self, path, name, depends=["biosphere"]):
         """Import an inventory dataset, or a directory of inventory datasets.
 

bw2data/io/import_method.py

 class EcospoldImpactAssessmentImporter(object):
     """Import impact assessment methods and weightings from ecospold XML format.
 
-Does not have any arguments; instead, instantiate the class, and then import using the ``importer`` method, i.e. ``EcospoldImpactAssessmentImporter().importer(filepath)``."""
+Does not have any arguments; instead, instantiate the class, and then import using the ``importer`` method, i.e. ``EcospoldImpactAssessmentImporter().importer(filepath)``.
+
+    """
     def importer(self, path):
         """Import an impact assessment method, or a directory of impact assessment methods.
 
         The flow logic is relatively complex, because:
-            #. We have to make sure the ``number`` attribute is not just a sequential list
-            #. Even if valid biosphere ``number``s are provided, we can't believe them.
+            #. We have to make sure the ``number`` attribute is not just a sequential list.
+            #. Even if a valid biosphere ``number`` is provided, we can't believe it.
 
         Here is the flow logic graphic:
 

bw2data/method.py

             raise MissingIntermediateData("Can't load intermediate data")
 
     def process(self):
-        """Process intermediate data from a Python dictionary to a `NumPy <http://numpy.scipy.org/>`_ `Structured <http://docs.scipy.org/doc/numpy/reference/arrays.classes.html#record-arrays-numpy-rec>`_ `Array <http://docs.scipy.org/doc/numpy/user/basics.rec.html>`_. A structured array (also called record arrays) is a heterogeneous array, where each column has a different label and data type. These structured arrays act as a standard data format for LCA and Monte Carlo calculations, and are the native data format for the Stats Arrays package.
+        """
+Process intermediate data from a Python dictionary to a `NumPy <http://numpy.scipy.org/>`_ `Structured <http://docs.scipy.org/doc/numpy/reference/arrays.classes.html#record-arrays-numpy-rec>`_ `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. These structured arrays act as a standard data format for LCA and Monte Carlo calculations, and are the native data format for the Stats Arrays package.
 
-        Processed arrays are saved in the ``processed`` directory.
+Processed arrays are saved in the ``processed`` directory.
 
-        Although it is not standard to provide uncertainty distributions for impact assessment methods, the structured array includes uncertainty fields.
+Although it is not standard to provide uncertainty distributions for impact assessment methods, the structured array includes uncertainty fields.
+
+The structure for processed inventory databases is:
+
+================ ======== ===================================
+Column name      Type     Description
+================ ======== ===================================
+uncertainty_type uint8    integer type defined in `stats_toolkit.uncertainty_choices`
+flow             uint32   integer value from `Mapping`
+index            uint32   column filled with `NaN` values, used for matrix construction
+geo              uint32   integer value from `GeoMapping`
+amount           float32  location parameter, e.g. mean
+sigma            float32  shape parameter, e.g. std
+minimum          float32  minimum bound
+maximum          float32  maximum bound
+negative         bool     `amount` < 0
+================ ======== ===================================
+
+See also `NumPy data types <http://docs.scipy.org/doc/numpy/user/basics.types.html>`_.
+
+Doesn't return anything, but writes a file to disk.
 
         """
         data = pickle.load(open(os.path.join(
 # The short X.Y version.
 version = '0.9'
 # The full version, including alpha/beta/rc tags.
-release = '0.9.0-alpha'
+release = '0.9.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/configuration.rst

+.. _configuration:
+
+Configuration
+*************
+
+The configuration for brightway2 is implemented as a singleton class that is created when ``brightway2`` is imported.
+
+.. autoclass:: bw2data._config.Config
+    :members:

docs/database.rst

+Database
+********
+
+.. _database:
+
+.. autoclass:: bw2data.Database
+    :members:
 -----------------
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
 
    querying
    technical
+Import and Export
+*****************
+
+.. autoclass:: bw2data.io.BW2PackageImporter
+    :members:
+
+.. autoclass:: bw2data.io.BW2PackageExporter
+    :members:
+
+.. autoclass:: bw2data.io.EcospoldImporter
+    :members:
+
+.. autoclass:: bw2data.io.EcospoldImpactAssessmentImporter
+    :members:

docs/metadata.rst

+Metadata
+********
+
+.. _databases:
+
+.. autoclass:: bw2data.meta.Databases
+    :members:
+    :inherited-members:
+
+.. _methods:
+
+.. autoclass:: bw2data.meta.Methods
+    :members:
+    :inherited-members:
+
+.. _mapping:
+
+.. autoclass:: bw2data.meta.Mapping
+    :members:
+    :inherited-members:
+
+.. _geomapping:
+
+.. autoclass:: bw2data.meta.GeoMapping
+    :members:
+    :inherited-members:
+Method
+******
+
+.. _method:
+
+.. autoclass:: bw2data.Method
+    :members:

docs/technical.rst

 * bw2analyzer: Functions for analyzing the results of LCA calculations, including contribution and sensitivity analysis.
 * bw2ui: Two different user interfaces for Brightway2. Brightway2 is pure Python, and can be used by other programs or in an ipython notebook. For people who aren't as comfortable programming in Python, this packages provides a command line interface for work in the terminal, and a web interface.
 
-Configuration
-=============
+Reference
+=========
 
-The configuration for brightway2 is implemented as a singleton class that is created when ``brightway2`` is imported.
+.. toctree::
+   :maxdepth: 2
 
-.. autoclass:: bw2data._config.Config
-    :members:
-
-Metadata
-========
-
-.. autoclass:: bw2data.meta.Databases
-    :members:
-    :inherited-members:
-
-.. autoclass:: bw2data.meta.Methods
-    :members:
-    :inherited-members:
-
-.. autoclass:: bw2data.meta.Mapping
-    :members:
-    :inherited-members:
-
-.. autoclass:: bw2data.meta.GeoMapping
-    :members:
-    :inherited-members:
-
-Database
-========
-
-.. autoclass:: bw2data.Database
-    :members:
-
-Method
-======
-
-.. autoclass:: bw2data.Method
-    :members:
-
-Import and Export
-=================
-
-.. autoclass:: bw2data.io.BW2PackageImporter
-    :members:
-
-.. autoclass:: bw2data.io.BW2PackageExporter
-    :members:
-
-.. autoclass:: bw2data.io.EcospoldImporter
-    :members:
-
-.. autoclass:: bw2data.io.EcospoldImpactAssessmentImporter
-    :members:
+   configuration
+   metadata
+   database
+   method
+   io