⚠️ This plugin is in hibernation state. It is available as a showcase, but not actively developed. If you are interested in a collaboration on this topic, please contact us at climate-action@heigit.org.
The purpose of this plugin is to estimate carbon flows from land use and land cover (LULC) change, given a selected area of interest and analysis period. The plugin provides maps of the LULC classification at the beginning and at the end of the analysis period, as well as maps of the LULC changes. Additionally, tables and plots with information on the LULC change areas and carbon flows from LULC change are produced. For more documentation see the climate action website or the purpose, methodology and sources files in the resources directory.
Use git to clone this repository to your computer.
Create a new branch by running git checkout -b <my_new_branch_name>.
After you have finished your implementation, you can create a merge request to the main branch that can be reviewed by the CA team.
We highly encourage you to create smaller intermediate MRs for review!
We use poetry as an environment management system. Make sure you have it installed. Apart from some base dependencies, there is only one fixed dependency for you, which is the climatoology package that holds all the infrastructure functionality. Make sure you have read-access to the climatoology repository (i.e. you can clone it).
DOCKER_BUILDKIT=1 docker build --secret id=CI_JOB_TOKEN . --tag repo.heigit.org/climate-action/ghg-emission-from-lulc-change:develTo mimic the build behaviour of the CI you have to add --build-arg CI_COMMIT_SHORT_SHA=$(git rev-parse --short HEAD)
to the above command.
Now run
poetry install --no-root
and you are ready to code within your poetry environment.
We use pytest as a testing engine.
Ensure all tests are passing by running poetry run pytest.
To get a coverage report of how much of your code is run during testing, execute
poetry run pytest --ignore test/core/ --cov.
We ignore the test/core/ folder when assessing coverage because the core tests run the whole plugin to be sure
everything successfully runs with a very basic configuration.
Yet, they don't actually test functionality and therefore artificially inflate the test coverage results.
To get a more detailed report including which lines in each file are not tested,
run poetry run pytest --ignore test/core/ --cov --cov-report term-missing
It is important that the code created by the different plugin developers adheres to a certain standard.
We use ruff for linting and formatting the code as part of our pre-commit hooks.
Please activate pre-commit by running poetry run pre-commit install.
It will now run automatically before each commit and apply fixes for a variety of lint errors to your code.
Note that we have increased the maximum number of characters per line to be 120 to make better use of large modern displays.
If you want to keep short lines explicitly seperate (e.g. in the definition of functions or list) please use "magic trailing commas".
Using the environment variable LOG_Level you can adjust the amount of log messages produced by the plugin.
Please make sure to use logging throughout your plugin.
This will make debugging easier at a later stage.
We have seperated the code into multiple files by their functionality. We will go through these files step by step.
Tests in test_plugin.py
Test driven development is highly encouraged.
- The first test confirms that the plugin announcement is working as expected (
test_plugin_info_request). - The second test ensures that the computation runs as expected in a test environment (
test_plugin_compute_request).
These tests ensure that the development contract is met.
Tests in conftest.py
This file contains fixtures where the expected compute input is given (expected_compute_input) and the LULC utility (lulc_utility_mock) is mocked.
The files test_emissions.py and test_utils.py contain tests of the functions in the files emissions.py and utils.py.
Operator in operator_worker.py
This is the heart of the plugin where the emission estimation happens. The most important functions are the info function and the compute function. The info function simply returns information about the plugin. The compute function estimates the carbon flows and returns the outputs of the operator as a list of artifacts.
Input parameters in input.py
The input parameters are defined here and some validation on them is done.
Other Python files in ghg_lulc
- The file emissions.py contains the functions of the emission calculator.
- The file utils.py contains mischellaneous functions.
- The file artifact.py contains the functions that create the artifacts.
To release a new plugin version
- Update the CHANGELOG.md. It should already be up to date but give it one last read and update the heading above this upcoming release
- Decide on the new version number. We suggest you adhere to the Semantic Versioning scheme, based on the changes since the last release. You can think of your plugin methods (info method, input parameters and artifacts) as the public API of your plugin.
- Update the version attribute in the pyproject.toml (e.g. by running
poetry version {patch|minor|major}) - Create a release on GitLab, including a changelog
To build docker images, you need to give the engine access to the climatoology repository.
Create a file CI_JOB_TOKEN that contains your personal access token to the climatoology repository.
The tool is also Dockerised. Images are automatically built and deployed in the CI-pipeline.
In case you want to manually build and run locally (e.g. to test a new feature in development), execute
docker build --secret id=CI_JOB_TOKEN . --tag repo.heigit.org/climate-action/ghg-emission-from-lulc-change:develNote that this will overwrite any existing image with the same tag (i.e. the one you previously pulled from the Climate Action docker registry).
To mimic the build behaviour of the CI you have to add --build-arg CI_COMMIT_SHORT_SHA=$(git rev-parse --short HEAD)
to the above command.
If you have the Climate Infrastructure running (see Development Setup) you can now run the container via
docker run --rm --network=host --env-file .env.base --env-file .env repo.heigit.org/climate-action/ghg-emission-from-lulc-change:develDeployment is handled by the GitLab CI automatically. If for any reason you want to deploy manually (and have the required rights), after building the image, run
docker image push repo.heigit.org/climate-action/ghg-emission-from-lulc-change:develContributions are welcome. Feel free to create a merge request and contact the CA team.
You can find more information about the methodology of the plugin in the documentation.