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.
Working on the documentation¶
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.
Changing the code base¶
All code contribution must be provided as pull requests connected to a filed issue. Please set-up pull requests against the master branch of the repository. Use numpy style docstrings and lint using black and isort, and follow the pep8 style guide. Passing the black and isort liter is a requirement to pass the tests before merging a pull request.
pip install black isort isort --project pymrio --profile black . black .
Check the “script” part in .travis.yml to check the required tests. If you are using Conda you can build a development environment from environment_dev.yml which includes all packages necessary for development, testing and running.
Since pymrio is already used in research projects, please aim for keeping compatibility with previous versions.
Running and extending the tests¶
Before filing a pull request, make sure your changes pass all tests. Pymrio uses the py.test package for testing. To run the tests either activate the environment_dev.yml file (if you are using Anaconda) or install the test requirments defined in requirments_test.txt.
coverage erase isort --profile black --check-only . coverage run -m pytest --black -vv . coverage report
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
Debugging and logging¶
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)
Documentation and docstrings¶
Docstring should follow the numby docstring convention. See
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
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)
- flow maps of impacts embodied in trade flows
- choropleth map for footprints
structural decomposition analysis