1. Chris Mutel
  2. brightway2

Commits

Chris Mutel  committed f320701

0.11. Add tutorials to docs, and misc. cleanups

  • Participants
  • Parent commits 51d17ec
  • Branches default

Comments (0)

Files changed (10)

File brightway2/__init__.py

View file
  • Ignore whitespace
 from bw2data import *
 from bw2calc import *
 
-__version__ = (0, 10)
+__version__ = (0, 11)

File docs/conf.py

View file
  • Ignore whitespace
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '0.11'
+# The full version, including alpha/beta/rc tags.
+release = '0.11'
+
 import sys
 from os.path import abspath, dirname
 
 project = u'Brightway2'
 copyright = u'2013, Chris Mutel'
 
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-#
-# The short X.Y version.
-version = '0.10'
-# The full version, including alpha/beta/rc tags.
-release = '0.10'
-
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #language = None

File docs/faq.rst

View file
  • Ignore whitespace
     * `WingWare <http://wingware.com/>`_
 
 See also the `discussion on the Python wiki <https://wiki.python.org/moin/IntegratedDevelopmentEnvironments>`_ and a `long StackOverflow discussion <http://stackoverflow.com/questions/81584/what-ide-to-use-for-python/>`_.
+
+Why Brightway 2?
+----------------
+
+Brightway version 1 was a set of programs written during the PhD of Chris Mutel. In the end, there wasn't that much that could be re-used from this research code, other than the name. Brightway2 is a completely new software framework designed to avoid the fate of Brightway version 1. See also the `blog post on technical motivation <http://chris.mutel.org/brightway2-technical-motivation.html>`_.

File docs/index.rst

View file
  • Ignore whitespace
 Documentation
 =============
 
-Table of contents:
+Documentation is available on several levels. First, this general documentation gives an overview to the main ideas and structures in Brightway2. The actual code is split into several different :ref:`packages` - e.g data, calculations, analysis - and each package has documentation that gives more specific details on its functions. Finally, there are a set of ipython notebook :ref:`tutorials` and :ref:`examples` that can be read or downloaded and run, and provide more practical advice on applying Brightway2.
+
+Table of contents
+=================
 
 .. toctree::
    :maxdepth: 2

File docs/installation.rst

View file
  • Ignore whitespace
 Install Brightway2 using ``pip``:
 
 .. code-block:: bash
+
     pip install brightway2
 
 See also `pip packages in anaconda <http://stackoverflow.com/questions/18640305/how-to-keep-track-of-pip-installed-packages-in-an-anaconda-conda-env>`_.

File docs/key-concepts.rst

View file
  • Ignore whitespace
      [(u'biosphere', u'b0a29177e77471a49b5a7d6a88212bf8'), 32000, u'GLO'],
      [(u'biosphere', u'72c1cf2fee31a2cb6cdc39abda29a0df'), 32000, u'GLO']]
 
-Each list elements has three components.
+Each list elements has two required components and a third optional component.
     #. A reference to a biosphere flow, e.g. ``(u'biosphere', u'21c70338ff2e1cdc8e468f4c90f113a1')``.
-    #. The numeric characterization factor.
-    #. A location, which is used because Brightway2 will soon gain the ability to do regionalized LCA.
-
-The current format does not include fields for characterizing the uncertainty of the characterization factors, but the processed characterization matrices do, and it is anticipated that this functionality will be added relatively soon.
+    #. The numeric characterization factor. This can either be a number, or a uncertainty dictionary (see :ref:`uncertainty-type`).
+    #. An optional location, used for regionalized impact assessment. The global location ``GLO`` is given as a default is not location is specified.
 
 .. note::
     LCIA method documents can be validated with ``bw2data.validate.ia_validator(my_data)``, or ``Method(("my", "method", "name")).validate(my_data)``.
         {
             "metadata": {
                 "name": [list, of, names],
-                "description": description,
-                "num_cfs": number of cfs,
+                "description": (optional) description,
                 "abbreviation": abbreviation of method name,
-                "unit": unit of impact assessment method
+                "unit": (optional) unit of impact assessment method
             },
             "cfs": [
                 {
                     "database": database name, e.g. biosphere,
                     "code": code of the biosphere flow,
-                    "location": location where the characterization factor is valid (optional),
-                    "amount": characterization factor amount,
-                    "uncertainty type": integer uncertainty type,
-                    "sigma": uncertainty parameter,
-                    "maximum": uncertainty parameter,
-                    "minimum": uncertainty parameter
+                    "location": location where the characterization factor is valid,
+                    "amount": characterization factor (number or uncertainty dictionary),
                 }
             ]
         }
     ]
+
+.. warning:: The bw2package format is expected to change soon, to become more generic. This new format will be fixed for future compatibility.

File docs/packages.rst

View file
  • Ignore whitespace
+.. _packages:
+
 Brightway2 packages
 *******************
 

File docs/tutorials.rst

View file
  • Ignore whitespace
+Tutorials and Examples
+**********************
+
+.. _tutorials:
+
 Tutorials
-*********
+=========
 
-Getting started
-===============
+There is a tutorial that will take you from a beginner to a Brightway2 pro in five steps. You should read this documentation, and at least be familiar with the specific package documentation, to get the most out of tutorial.
 
-<insert online tutorial here>
+The tutorial notebooks are most effective when downloaded and executed - that is the power of IPython notebooks! Run them, change them, and play around. Learn by making mistakes. Brightway2 allows you to pretty easily delete your data directory and start again.
 
-The command line interface
-==========================
+    * `Tutorial 1 - Getting Started <http://nbviewer.ipython.org/url/brightwaylca.org/tutorials/Tutorial%201%20-%20Getting%20Started.ipynb>`_
+    * `Tutorial 2 - Working with Data <http://nbviewer.ipython.org/url/brightwaylca.org/tutorials/Tutorial%202%20-%20Working%20with%20data.ipynb>`_
+    * `Tutorial 3 - LCA Calculations <http://nbviewer.ipython.org/url/brightwaylca.org/tutorials/Tutorial%203%20-%20Basic%20LCA%20Calculations.ipynb>`_
+    * `Tutorial 4 - Meta-analysis <http://nbviewer.ipython.org/url/brightwaylca.org/tutorials/Tutorial%204%20-%20Meta-analysis.ipynb>`_
+    * `Tutorial 5 - Defining a New Matrix <http://nbviewer.ipython.org/url/brightwaylca.org/tutorials/Tutorial%205%20-%20Defining%20A%20New%20Matrix.ipynb>`_
 
-The following commands are available:
+.. _examples:
 
-    * ``bw2-controller.py list databases``: List all installed databases
-    * ``bw2-controller.py list methods``: List all installed methods
-    * ``bw2-controller.py details <name>``: Give details on inventory database ``<name>``. If the database name has spaces in it, it should be quoted, like this: ``"name with spaces"``.
-    * ``bw2-controller.py copy <name> <newname>``: Copy inventory database ``<name>`` to new name ``<newname>``.
-    * ``bw2-controller.py backup <name>``: Make a backup copy of inventory database ``<name>``.
-    * ``bw2-controller.py validate <name>``: Validate the data in inventory database ``<name>``.
-    * ``bw2-controller.py versions <name>``: List the versions available of inventory database ``<name>``.
-    * ``bw2-controller.py revert <name> <revision>``: Revert inventory database ``<name>`` to version number ``<revision>``.
-    * ``bw2-controller.py remove <name>``: Deregister inventory database ``<name>``. Does not delete data, only removes it from the Brightway2 register.
-    * ``bw2-controller.py import <path> <name>``: Import a set of inventory data in the Ecospold data format from location ``<path>`` to inventory database ``<name>``.
-    * ``bw2-controller.py export <name> [--include-dependencies]``: Export inventory database ``<name>`` to a bw2package format. If ``--include-dependencies`` is part of the command, the bw2package will include the dependent databases as well.
-    * ``bw2-controller.py setup``: Do the initial setup for when Brightway2 is first installed.
+Examples
+========
 
-Other online examples
-=====================
+While the examples are given as IPython notebooks, they might use data sources or computational resources which are not available to everyone, and therefore not all of them can be easily rerun on your local machine.
 
-<insert link to examples page here>
+**This section will be filled in when the example are cleaned up a bit**.

File requirements.txt

View file
  • Ignore whitespace
 requests
 scipy
 voluptuous
-bw2calc>=0.10.1
-bw2ui>=0.7
-bw2analyzer>=0.4
-bw2data>=0.10.1
-bw-stats-toolkit>=0.7
+bw2calc
+bw2ui
+bw2analyzer
+bw2data
+stats_arrays>=0.2.2

File setup.py

View file
  • Ignore whitespace
     "fuzzywuzzy",
     "flask",
     "docopt",
-    "bw2calc>=0.10.1",
-    "bw2ui>=0.7",
-    "bw2analyzer>=0.4",
-    "bw2data>=0.10.1",
+    "bw2calc",
+    "bw2ui",
+    "bw2analyzer",
+    "bw2data",
     "requests>=1.1.0",
     "stats_arrays>=0.2.2",
 ]
 
 setup(
     name='brightway2',
-    version="0.10",
+    version="0.11",
     packages=["brightway2"],
     author="Chris Mutel",
     author_email="cmutel@gmail.com",
     url="https://bitbucket.org/cmutel/brightway2",
     long_description=open('README.rst').read(),
     classifiers=[
-        'Development Status :: 4 - Beta',
+        'Development Status :: 5 - Production/Stable',
         'Intended Audience :: End Users/Desktop',
         'Intended Audience :: Developers',
         'Intended Audience :: Science/Research',