Ctrl+K

Contribute Colormaps

Contribute Colormaps#

Do you want to contribute your own colormap to the pycolorbar archive ? Great! You are in the right place !

Here below we provide a detailed description of the steps to follow to contribute your colormap configuration to pycolorbar:

Before going down the road, please also have a look at the Contributors Guidelines.

Step 1: Fork, clone and install the pycolorbar repository#

  1. Go to the pycolorbar repository, fork the repository on your GitHub account and then clone the forked repository:

    git clone https://github.com/<your_username>/pycolorbar.git

  2. Go inside the pycolorbar directory where you have cloned the repository and install the pycolorbar python package in editable mode following the guidelines reported in the Installation for Contributors.

  3. Create a new branch:

    git checkout -b "add-colormaps-<name>"

  4. Set the remote upstream branch:

    git push --set-upstream origin "add-colormaps-<name>"

  5. Every time you will now git add * and git commit -m <describe-your-change> your changes, you will be able to push them to your forked repository with:

    git push

  6. When you want to show your changes to the pycolorbar maintainers, you will need to open a Pull Request. To do so, go to the GitHub pycolorbar repository, open the Pull Request and ask for a review.

    For more information on GitHub Pull Requests, read the “Create a pull request documentation”.

    If you struggle with this process, do not hesitate to raise an issue or ask in the pycolorbar Slack Workspace so that we can help !

Step 2: Define and save the colormap configurations#

To start defining your colormap configuration YAML files, please refers to the Introduction to Univariate Colormaps documentation.

Consider adding relevant colormap categories within the category field of the auxiliary subdictionary. These categories help differentiate between colormaps based on:

  • the type of colormap: cyclic, diverging, sequential, qualitative, perceptual.

  • the variables for which the colormap is commonly used (i.e. elevation, bathymetry, precipitation, temperature, etc.).

  • the author or source agency of the colormap (i.e. brewer, crameri, meteoswiss, nasa, etc.).

Additionally, in the auxiliary subdictionary, you can specify custom fields such as comments, references, url, author, license.

Once your colormap configurations are finalized, save the configuration YAML files in the pycolorbar/etc/colormaps directory.

Before proceeding, please review the existing directories within pycolorbar/etc/colormaps. If it seems appropriate, create a new directory and place your colormap configuration YAML files inside it.

Note

Guidelines for the naming of the colormap configuration YAML files:

  • The colormap name must not end with _r.

  • Usage of dash (-) and underscore (_) is allowed.

  • If you’re adding colormap configurations of a specific author (i.e. brewer, crameri), consider naming the new directory after the original author.

  • If you’re adding colormap configurations of a specific variable (i.e. precipitation, temperature), consider naming the new directory after the variable.

Step 3: Test the configurations validity#

When you are done with the editing your colormaps YAML files, please verify that the colormap configurations you added are valid.

To test the validity of the colormap configurations, you can execute the following command in your terminal:

python -c "import pycolorbar; pycolorbar.check_colormap_archive()"

or alternatively you can run the check_colormap_archive function in python:

import pycolorbar

pycolorbar.check_colormap_archive()

If these commands do not raise errors, congratulations ! Your colormap configurations are valid.

Step 4: Submit your colormaps#

You are now ready to open a Pull Request and submit your colormaps to the pycolorbar archive.

Your Pull Requests will be merged as soon as a pycolorbar maintainer can check your work, and the colormap will be available to the pycolorbar community.

Contents