<commit_before>Pandarus
========

Pandarus is a GIS software toolkit for regionalized life cycle assessment. It is designed to work with `brightway LCA framework <https://brightwaylca.org>`__, `brightway2-regional <https://bitbucket.org/cmutel/brightway2-regional>`__, and `Constructive Geometries <https://bitbucket.org/cmutel/constructive-geometries>`__. A separate library, `pandarus-remote <https://bitbucket.org/cmutel/pandarus_remote>`__, provides a web API to run Pandarus on a server.

Why Pandarus?
-------------

The software matches two different maps against each other, and `Pandarus was a bit of a matchmaker himself <http://en.wikipedia.org/wiki/Pandarus>`_. Plus, ancient names are 200% more science-y.

Calculating areas
-----------------

Because Pandarus was designed for global data sets, the `Mollweide projection <http://en.wikipedia.org/wiki/Mollweide_projection>`_ is used as the default equal-area projection for calculating areas (in square meters). Although no projection is perfect, the Mollweide has been found to be a reasonable compromise (e.g. [1]_).

.. [1] <NAME>., and <NAME>., (2000) `A comparison of equal-area map projections for regional and global raster data <http://cegis.usgs.gov/projection/pdf/nmdrs.usery.prn.pdf>`_

Capabilities
============

Matching two vector datasets
----------------------------

Pandarus can match two vector datasets, generating a new vector dataset which includes each possible combination of a spatial unit in the first dataset with a spatial unit in the second dataset. This functionality is used in calculating which characterization factors to apply to an emission in a given region.

.. image:: images/map.png
    :align: center

.. automethod:: pandarus.calculate.Pandarus.intersect

Calculating the areas of spatial units
--------------------------------------

Pandarus can calculate the area of each spatial unit in a vector dataset. This functionality is used for normalization by total area when matching characterization factors to emissions in a given region.

.. image:: images/map.png
    :align: center

.. automethod:: pandarus.calculate.Pandarus.areas

Calculating raster statistics against a vector dataset
------------------------------------------------------

Pandarus can calculate mask a raster with each feature from a vector dataset, and calculate the min, max, and average values from the intersected raster cells. This functionality is provided by a patched version of `rasterstats <https://github.com/perrygeo/python-rasterstats>`__.

.. image:: images/map.png
    :align: center

.. automethod:: pandarus.calculate.Pandarus.rasterstats

Cleaning and vectorizing raster files
-------------------------------------

Pandarus provides some utility functions to help manage raster files, which are not always provided with rich and correct metadata.

.. autofunction:: pandarus.clean_raster

.. autofunction:: pandarus.round_raster

.. autofunction:: pandarus.convert_to_vector

Installation
============

Pandarus can be installed directly from `PyPi <https://pypi.python.org/pypi>`_ using `pip` or `easy_install`, e.g.

.. code-block:: bash

    pip install pandarus

However, it is easy to run into errors if libraries are compiled against different versions of GDAL. One way to get an installation that is almost guaranteed is to use `Conda <https://conda.io/miniconda.html>`__:

.. code-block:: bash

    conda config --add channels conda-forge cmutel
    conda create -n pandarus python=3.5
    source activate pandarus
    conda install pandarus
<commit_msg>Clean up some docs<commit_after>Pandarus
========

Pandarus is a GIS software toolkit for regionalized life cycle assessment. It is designed to work with `brightway LCA framework <https://brightwaylca.org>`__, `brightway2-regional <https://bitbucket.org/cmutel/brightway2-regional>`__, and `Constructive Geometries <https://bitbucket.org/cmutel/constructive-geometries>`__. A separate library, `pandarus-remote <https://bitbucket.org/cmutel/pandarus_remote>`__, provides a web API to run Pandarus on a server.

Why the name Pandarus?
----------------------

The software matches two different maps against each other, and `Pandarus was a bit of a matchmaker himself <http://en.wikipedia.org/wiki/Pandarus>`_. Plus, ancient names are 200% more science-y.

Calculating areas
-----------------

Because Pandarus was designed for global data sets, the `Mollweide projection <http://en.wikipedia.org/wiki/Mollweide_projection>`_ is used as the default equal-area projection for calculating areas (in square meters). Although no projection is perfect, the Mollweide has been found to be a reasonable compromise (e.g. [1]_).

.. [1] <NAME>., and <NAME>., (2000) `A comparison of equal-area map projections for regional and global raster data <http://cegis.usgs.gov/projection/pdf/nmdrs.usery.prn.pdf>`_

Usage example
-------------

In addition to this documentation, there is also a Jupyter notebook `usage example <https://github.com/cmutel/pandarus/blob/master/docs/usage_example.ipynb>`__.

Capabilities
============

Most Pandarus capabilities are managed through the ``Pandarus`` object.

.. autoclass:: pandarus.Pandarus
    :noindex:

Matching two vector datasets
----------------------------

Pandarus can match two vector datasets, generating a new vector dataset which includes each possible combination of a spatial unit in the first dataset with a spatial unit in the second dataset. This functionality is used in calculating which characterization factors to apply to an emission in a given region.

.. image:: images/map.png
    :align: center

.. automethod:: pandarus.Pandarus.intersect
    :noindex:

Calculating the areas of spatial units
--------------------------------------

Pandarus can calculate the area of each spatial unit in a vector dataset. This functionality is used for normalization by total area when matching characterization factors to emissions in a given region.

.. image:: images/map.png
    :align: center

.. automethod:: pandarus.calculate.Pandarus.areas
    :noindex:

Calculating raster statistics against a vector dataset
------------------------------------------------------

Pandarus can calculate mask a raster with each feature from a vector dataset, and calculate the min, max, and average values from the intersected raster cells. This functionality is provided by a patched version of `rasterstats <https://github.com/perrygeo/python-rasterstats>`__.

.. image:: images/map.png
    :align: center

.. automethod:: pandarus.calculate.Pandarus.rasterstats
    :noindex:

Cleaning and vectorizing raster files
-------------------------------------

Pandarus provides some utility functions to help manage raster files, which are not always provided with rich and correct metadata.

.. autofunction:: pandarus.clean_raster
    :noindex:

.. autofunction:: pandarus.round_raster
    :noindex:

.. autofunction:: pandarus.convert_to_vector
    :noindex:

Installation
============

Pandarus can be installed directly from `PyPi <https://pypi.python.org/pypi>`_ using `pip` or `easy_install`, e.g.

.. code-block:: bash

    pip install pandarus

However, it is easy to run into errors if libraries are compiled against different versions of GDAL. One way to get an installation that is almost guaranteed is to use `Conda <https://conda.io/miniconda.html>`__:

.. code-block:: bash

    conda config --add channels conda-forge cmutel
    conda create -n pandarus python=3.5
    source activate pandarus
    conda install pandarus

{'fraction_non_alphanumeric': 0.13354573211204035, 'fraction_numerical': 0.0034514801539891147, 'mean_word_length': 3.4422169811320753, 'pattern_counts': {'":': 0, '<': 28, '<?xml version=': 0, '>': 28, 'https://': 15, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4175224', 'n_tokens_mistral': 2112, 'n_tokens_neox': 1971, 'n_words': 817}