First off, thanks for taking the time to contribute!
There are many ways you can help to improve pymrio.
- Update and improve the documentation and tutorials.
- File bug reports and describe ideas for enhancement.
- Add new functionality to the code.
Pymrio follows an "issue/ticket driven development". This means, before you start working file an issue describing the planned changes or comment on an existing one to indicate that you work on it. This allows us to discuss changes before you actually start and gives us the chance to identify synergies across ongoing work and avoid potential double work. When you have finished, use a pull request to inform me about the improvements and make sure all tests pass (see below). In the pull request you can use various phrases which automatically close the issue you have been working on.
Any contribution to the description of pymrio is of huge value, in particular I very much appreciate tutorials which show how you can use pymrio in actual research.
The pymrio documentation combines reStructuredText and Jupyter notebooks. The Sphinx Documentation has an excellent introduction to reStructuredText. Review the Sphinx docs to perform more complex changes to the documentation as well.
Use numpy style docstrings and follow pep8 style guide. The latter is a requirement to pass the tests before merging a pull request. Since pymrio is already used in research projects, please aim for keeping compatibility with previous versions.
Before filing a pull request, make sure your changes pass all tests. Pymrio uses the py.test package with the pytest-pep8 extension for testing. To run the tests install these two packages (and the Pandas dependency) and run
py.test -v -pep8
in the root of your local copy of pymrio.
In addition to the unit tests, the Jupyter notebook tutorials are also used for integration tests of the full software. Some of them (the EXIOBASE and Eora example) require a pre-download of the respective MRIOs to a specific folder. Also, most of the tutorials have POSIX path specifications. However, in case you update some integral part of Pymrio, please either also check if the notebooks run or specify that you did not test them in the pull request.
For testing the notebooks install the nbval extension for py.test . Pymrio includes a sanitizing file to handle changing timestamps and object ids of the notebooks. To test all notebooks run the following command in the pymrio root directory:
pytest --nbval --sanitize-with .notebook_test_sanitize.cfg
Pymrio includes a logging class which is used for documenting changes in the IO system through Pymrio. This is defined in tools/iometadata.py.
To use is import it by
from pymrio.tools.iometadata import MRIOMetaData
and than document changes by using the methods provided by the class.
All logs necessary only for development or later debugging should be logged by
import logging
logging.debug("Message")
In the python terminal you can show these debug messages by:
import logging logger = logging.getLogger() logger.setLevel(logging.DEBUG)
The versioning system follows http://semver.org/
Docstring should follow the numby docstring convention. See
- http://sphinx-doc.org/latest/ext/example_numpy.html
- https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt#docstring-standard
Pymrio is under active development. Open points include:
parser for other available MRIOs
- OPEN:EU (http://www.oneplaneteconomynetwork.org/)
improve test cases
wrapper for time series analysis
- calculate timeseries
- extract timeseries data
reorder sectors/regions
automatic sector aggregation (perhaps as a separate package similar to the country converter)
country parameter file (GDP, GDP PPP, Population, area) for normalization of results (similar to the pop vector currently implemented for EXIOBASE 2)
graphical output
- flow maps of impacts embodied in trade flows
- choropleth map for footprints
structural decomposition analysis