matplotlib / cmocean

Colormap setup for standardizing commonly-plotting oceanographic variables.

cmocean

Documentation available: http://matplotlib.org/cmocean/.

We have a paper with guidelines to colormap selection for your application and a description of the cmocean colormaps: Thyng, K. M., Greene, C. A., Hetland, R. D., Zimmerle, H. M., & DiMarco, S. F. (2016). True colors of oceanography. Oceanography, 29(3), 10. link: http://tos.org/oceanography/assets/docs/29-3_thyng.pdf

Besides Python, the cmocean colormaps are also available:

• For MATLAB by Chad Greene
• For R cmocean, which includes ggplot2 compatible functions. Also included in Oce: an oceanographic analysis package by Dan Kelley and Clark Richards.
• For Julia, included in Plots.jl and Makie.jl
• For Ocean Data Viewer
• For Generic Mapping Tools (GMT) at cpt-city and on github
• For Paraview inspired by Phillip Wolfram
• In Plotly
• Chad Greene's Antarctic Mapping Tools in Matlab uses cmocean
• For Tableau as a preferences file on github
• For ImageJ as LUTs
• For ncview via ncmaps.
• For SeaDAS, and should work with BEAM/SNAP as well.

To install: pip install cmocean

To install with Anaconda: conda install -c conda-forge cmocean

If you want to be able to use the plots submodule, you can instead install with:

pip install "cmocean[plots]"

which will also install viscm and colorspacious.

cmocean's Issues

Some docs images

Import cmocean does not import plots

Thanks for the great work. It's a wonderful module!

I tried installing cmocean through anaconda and pip, for both python2 and python3.

However, a simple call import cmocean doesn't import the plots. So the example shown on the documentation page can't be reproduced. I tried to locate the package, and found that plots.py is there, just not in the __init__.py. Was this intentional?

Also, it seems that, cmocean requires thecolorspacious module, whose dependency has not been checked with either pip or conda.

Cheers,

Add example image for amp

cmocean colormaps for Tableau

I ported the cmocean colormaps to xml flavored preferences file for Tableau and am providing them as a link for you if you want to include them in your database of programs with the colormaps available.

https://github.com/shaunwbell/cmocean_tableau

Cheers

cmocean requires skimage

Loving the work here, and looking forward to trying it out when I get my hands on some Temperature data tomorrow (and looking forward to the speed colourmaps).

Just one thing, why the dependency on skimage? What do the imports in __init__.py accomplish?

Traceback (most recent call last):
  File "process.py", line 2, in <module>
    import cmocean
  File "/home/jack/Projects/matplotlib/cmocean/cmocean/__init__.py", line 11, in <module>
    import plots
  File "/home/jack/Projects/matplotlib/cmocean/cmocean/plots.py", line 9, in <module>
    from skimage import color
ImportError: No module named skimage

Future incompatibility with MPL

Just wanted to warn you about the pending deprecation of some functions in the matplotlib.cm namespace that are used in cmocean, like register_cmap

matplotlib/matplotlib#23668

If it's any help, here's the patch I wrote to adapt to these deprecations in yt
yt-project/yt#4089

I can also submit a PR here if you lack time for this.

cmocean available in ncview (via ncmaps)

Dear cmocean team,

Thank you for the cmocean colormaps. For your information, they are included in our package ncmaps. ncmaps brings scientific colormaps to ncview.

If you think it is appropriate, you could list ncmaps at the bottom of your README? E.g.

• For ncview via ncmaps.

cmocean makes unwanted font changes

The current version of cmocean makes unwanted changes to font sizes/styles. As the purpose of the package is to provide nice color maps, using "import cmocean" to import the color maps should not have any side effects.

It looks like the problem is the mpl.rcParams[...] lines at the top of cmocean/plots.py. Is it possible to reorganise that code such that it does not make any font changes under normal use?

FileNotFoundError at import with `cmocean==4.0.1`

Latest version of cmocean (4.0.1) fails at import, throwing a FileNotFoundError (thermal_i-rgb.txt).

Minimum reproducible code

import cmocean

Traceback:

Traceback (most recent call last):
  File "/home/user/cmocean_issue.py", line 1, in <module>
    import cmocean as cm
  File "/home/user/venv/lib/python3.11/site-packages/cmocean/__init__.py", line 11, in <module>
    from . import cm, tools, data
  File "/home/user/venv/lib/python3.11/site-packages/cmocean/cm.py", line 64, in <module>
    rgb_i = np.loadtxt(os.path.join(datadir, 'inverted', cmapname + '_i-rgb.txt'))
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/user/venv/lib/python3.11/site-packages/numpy/lib/npyio.py", line 1373, in loadtxt
    arr = _read(fname, dtype=dtype, comment=comment, delimiter=delimiter,
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/user/venv/lib/python3.11/site-packages/numpy/lib/npyio.py", line 992, in _read
    fh = np.lib._datasource.open(fname, 'rt', encoding=encoding)
         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/user/venv/lib/python3.11/site-packages/numpy/lib/_datasource.py", line 193, in open
    return ds.open(path, mode, encoding=encoding, newline=newline)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/user/venv/lib/python3.11/site-packages/numpy/lib/_datasource.py", line 533, in open
    raise FileNotFoundError(f"{path} not found.")
FileNotFoundError: /home/user/venv/lib/python3.11/site-packages/cmocean/rgb/inverted/thermal_i-rgb.txt not found.

Versions and other info

• python==3.11.8
• matplotlib==3.8.4
• cmocean==4.0.1

requirements.txt file is missing in 0.2.1

The 0.2.1 cmocean version cannot be installed with pip because requirements.txt file is not found. I checked the tar.gz archive and instead of requirements.txt I found a file, requires.txt. Please fix this issue because cmocean provides amazing colormaps, and users cannot install it.

Add inverting functionality?

I am hoping to get some thoughts on adding functionality for cmocean colormaps with inverted lightness. Here is an example of what this looks like:

This functionality is included in the MATLAB cmocean toolbox and some of my collaborators have made good use of it. A specific use case cited in the MATLAB example is using diverging colormaps on light backgrounds.

I see three ways this could be added:

1. Include _i or _inverted colormaps in the cm.py file for direct access by users.
2. Include an invert_lightness function in the tools.py file.
3. Allow negative alpha values in the cmocean.tools.lighten to be interpreted as inverting lightness

One issue is that the solution I have for inverting lightness requires an additional dependency, colorspacious. Although this is already a dependency for the "cmocean[plots]" install, so perhaps not a huge leap.

Python 3.4.3 - pip install cmocean fails

Hi, my name is Mario Luiz Mascagni. I'm new on GitHub and Python environments.
I've been trying to install cmocean, using pip 8.0.2, but without success.
I create a python virtual environment and I installed numpy and matplotlib; and then, I create the requirements.txt file for both using the "pip freeze" command; but when I try to install cmocean, it gives the following error:
File "/tmp/pip-build-hfgikas4/cmocean/setup.py", line 30, in
with open('requirements.txt') as f:
FileNotFoundError: [Errno 2] No such file or directory: 'requirements.txt'

I have no idea why the script setup.py isn't finding the "requirements.txt" file. I checked the cmocean-0.2.1.tar.gz file and it seems to be there.
Can someone help me please?

numpy v2.0 compatibility

When testing with this package as a dependency and numpy 2.0 dev version, I'm getting the following error:

[rest of log shortened]
/opt/hostedtoolcache/Python/3.9.18/x64/lib/python3.9/site-packages/cmocean/tools.py:12: in <module>
    _string_types = (str, np.str_, np.unicode_)
/opt/hostedtoolcache/Python/3.9.18/x64/lib/python3.9/site-packages/numpy/__init__.py:396: in __getattr__
    raise AttributeError(
E   AttributeError: `np.unicode_` was removed in the NumPy 2.0 release. Use `np.str_` instead.

Can the np.unicode_ be removed in these lines?

cmocean/cmocean/tools.py

Lines 11 to 14 in 4b627ff

	if sys.version_info > (3,):
	_string_types = (str, np.str_, np.unicode_)
	else:
	_string_types = (basestring, np.str_, np.unicode_)

tag release

Hey, can you tag the latest commit for release so that conda (& pip?) can find it?

Colormaps for wave parameters

Great work on the colormaps !

Are you planning to add colormaps for wave parameters such as wave height, period and direction ?

Thanks

Example hypoxia map

Does the oxygen palette have a brightness peak?

These colour palettes are wonderful. Thanks hugely for developing them, and be prepared to start seeing them in the literature!

With permission, I have copied the coefficients (as they were yesterday) into the oce R package and made a diagram (below) to illustrate the palettes. The oxygen one seems a bit strange to me because of two very sharp transitions. These are also quite striking when printed in black and white. Is this behaviour chosen to mimic something done in the literature? If so, that's great. But it seemed odd to me, so I thought I might point it out.

PS. the others all look very nice in black and white, with a bright band in diverging but smooth gradation in the others (except phase, which is of course flat in grayscale).

Possible to set number of levels on colormap?

Hopefully I'm not missing something obvious here. I often set the number of levels when using matplotlib colormaps:
cmap = plt.get_cmap('jet',10)
Is there a way to do this with the cmocean colormaps?

Automatic registration of colormaps

How about registering your colormaps using matplotlib.cm.register_cmap, perhaps wit a name like 'cmaocean_' for the colormap, when importing the module?

cmap alteration

I plan to use your colormaps as much as possible. However, it is for instance hard to draw lines onto filled objects since the colormaps goes generally from very dark to very white, or the reverse: black lines or white lines or texts are not that visible around extremess.

How about the possibility to alterate a colormap when calling the cmap() function, keeping them perceptually uniform.
Here is probably an example of alteration that allow to plot dark lines that are always visible:
http://www.ifremer.fr/vacumm/tests/test_color_whiten.html

Mapping between old and new cmap names?

I just noticed that the names of the colormaps have changed. Is there a simple list of old and new colormap names? I'm looking through the commit that affected the documentation, but I just figured that a list would be easier for those in my situation. Alternatively, it would be great if old names still worked, but maybe just emitted a deprecation notice until one more version change; I suddenly found myself with quite a few broken map configurations today.

Upload to PyPI

Could we get this released on PyPI?

Wrong `__version__` in `__init__.py`

Hi,

I've noticed the wrong version number set for __version__ in __init.py__.

One solution would be to use importlib.metadata.version('cmocean') to always the correct version number taken from the setup.py.

If that is something wanted, I am happy to do a PR for it :)

landing page has no install directions...

I don't see any install directions at https://matplotlib.org/cmocean/. Once could guess that its pip install cmocean, or conda install cmocean, but it'd be nice to say...

Phase, but with grey

Hello,

Apologies, this is more of a discussion than an issue but I didn't know where else to ask.

tl;dr: Would it be meaningful to create a version of the phase colormap that goes through the appropriate grey at the center of the scale?

Rationale: I work a lot with complex valued data. I find it useful to plot this using the phase colormap or similar to represent the phase, and then scale the intensity/luminance by the magnitude of my data. However, my field is used to looking at greyscale magnitude images only. Hence I've long wondered if the two couldn't be combined, whereby positive real values would still use greyscale, and then any data that has non-zero phase would have the hue shifted. As the phase colormap has a flat lightness value, couldn't the central blue-ish color be swapped out for grey? I suspect I'm forgetting some color theory as to why this is a bad idea. Thanks for any insights anyone can provide.

issue with pip install (python2)

Hi,

Pip install fails for python2 install because of missing Readme file:

long_description=open('README.md').read(),

sudo pip2 install cmocean
Collecting cmocean
  Downloading https://files.pythonhosted.org/packages/0a/da/302ed3bb245833042961138521e4fa3cb9670aef40d90f32a9a1da83e7a5/cmocean-1.2.tar.gz (260kB)
    100% |████████████████████████████████| 266kB 2.5MB/s 
    Complete output from command python setup.py egg_info:
    Traceback (most recent call last):
      File "<string>", line 1, in <module>
      File "/tmp/pip-install-kSlGW9/cmocean/setup.py", line 35, in <module>
        long_description=open('README.md').read(),
    IOError: [Errno 2] No such file or directory: 'README.md'
    
    ----------------------------------------
Command "python setup.py egg_info" failed with error code 1 in /tmp/pip-install-kSlGW9/cmocean/

ImportError: No module named 'cm'

Installing from PyPi did not work, so I installed from github as the following:

wget https://github.com/matplotlib/cmocean/archive/master.zip
unzip master.zip
pip install --user cmocean-master/

Then, the error message on import:

In [1]: import cmocean
---------------------------------------------------------------------------
ImportError                               Traceback (most recent call last)
<ipython-input-1-19d3b496f197> in <module>()
----> 1 import cmocean

/Users/andrew/Library/Python/3.5/lib/python/site-packages/cmocean/__init__.py in <module>()
      7 
      8 # from cmocean import *
----> 9 import cm
     10 import tools
     11 import plots

ImportError: No module named 'cm'

Nice work on the documentation, looks great!

Docs images

Add example image for deep

by Iury Sousa

Submodule plots is in `__all__` but not imported in `__init__.py`

Hi,

This might be deliberate but it seems that the submodule plots is not imported in the __init__.py but is included in __all__.
I can see there are some optional dependencies for some of the functions but their imports are only inside the concerned functions.

That means that if someone wants to use the plots submodule they would need to explicitly import it, which seems a bit strange when the documentation has this:

import cmocean
cmocean.plots.plot_gallery()

Which currently gives:

AttributeError: module 'cmocean' has no attribute 'plots'

discussing the "ice" colormap

Dear cmocean community,

Apologies, this is a rather long text.

My work involves plotting maps of sea ice. Because it is easily available and scientific, I have been using cmocean's "ice" quite a lot in the past. But some of its intrinsic characteristics have also led me look for alternatives. This post is to discuss the "ice" colormap for plotting sea ice fields (from models or satellite data).

By far, the key sea-ice variable we see plotted with cmocean.ice is sea-ice concentration (or sea-ice area fraction): the fraction of an ocean area that is covered with sea ice. A sea-ice concentration of 0 means there is no ice (only ocean). A sea-ice concentration of 1 means there is only ice (no ocean visible from above). A sea-ice concentration of 0.7 really means 0.7 ice on top of 0.3 ocean.

In our common imagination / representation ice is white and ocean is blue. A scientific colormap for sea-ice concentration should thus run from blue to white.

However, cmocean's 'ice' runs from very dark blue (almost black) to very light blue (almost white).

To me, the main issue with cmocean.ice when plotting sea-ice concentration (which is what we use it for 99% of the time) is that the high-end of the colormap is quite far from white. This is really blueish. Areas with a sea-ice concentration of 1 (as given by a forecast model or a satellite) do not look like fully ice-covered when plotted with cmocean.ice, because they are slightly blue, a color that is associated with some fraction of ocean (thus a sea-ice concentration below 1).

A second issue is that the low-end of the colormap is very dark, almost pitch black. This is sub-optimal for two reasons:

• a common representation is that the ocean is blue, not black.
• sea-ice concentration is the linear weigthing between no ice (ocean) and only ice (white). But the 'ice' colormap starts from black, runs through blues, and ends (close to) white. To me this does not convey well the linear mixing of more and more ice on top of the ocean. If we start from a black ocean, we should not be adding blue when adding ice, we should be adding white (and the colormap would be much closer to "gray".

Below are 3 maps of sea-ice concentration using 1) cmocean's ice,

2) matplotlib's Blues_r,

and 3) matplotlib's PuBu_r.

You can see for yourself the differences, and in particular how cmocean's ice does not end in white, which results in a general perception of less sea-ice concentration (more melt).

Personnaly I tend to prefer the third map (PuBu_r) because of the color of the ocean. But the main problem with Blues_r and PuBu_r is that they are NOT scientific colormaps (see matplotlib's doc), and we should be using scientific colormaps for scientific data.

All in all, I want to discuss the cmocean's "ice" colormap with the community. I do not know why it was designed this way, there are certainly very good reasons. This colormap is maybe perfect for other cryospheric applications (land ice? mountain glaciers? snow?) but for sea ice and in particular sea-ice concentration it is not optimal.

Another question to the cmocean developers is if there are routines in the cmocean package I could use to tweak the ice colormap to have the desired characteristics above (starting from a blue, ending much closer to white).

Finally, if it comes to this, should we collectively design a new scientific colormap for sea-ice concentration (how?) and could the new colormap enter future versions of cmocean if there is a broader interest.

Thank you for reading so far,
Thomas

Minor installation and documentation issues with the plots submodule

I have cmocean 2.0 installed in a python 3.7 environment under Miniconda.

The "pip install cmocean[plots]" trick does not carry over to conda, i.e. "conda install cmocean[plots]" has exactly the same effect as "conda install cmocean": it installs cmocean only.

The main web site (https://matplotlib.org/cmocean/) suggests running the plot gallery with
import cmocean cmocean.plots.plot_gallery()

This does not work for me. However I can run the plot_gallery function by first installing colorspacious and then running this code:
from cmocean import plots as cmplots cmplots.plot_gallery()

I therefore suggest:

• Making colorspacious a dependency of cmocean on conda-forge. And maybe also viscm
• Modifying the plot_gallery demonstration code on the front page to use the "from cmocean import plots" idiom. (This is widely used by other packages.)