Quick Start - MBravoS/scicm GitHub Wiki

Installation

As mentioned in the README, installing SciCM is straightforward using pip, either from PyPI or directly from GitHub:

>pip install scicm
>pip install git+https://github.com/MBravoS/splotch.git@master

Note, there are plans to also add scicm to conda-forge in the near future.

Using the colour maps

Upon importing, all colour maps are registered with matplotlib, so they are easily accessible by passing the corresponding name (e.g. cmap='scicm.Stone') to any function that takes a colour map argument (cmap or c in some cases such as plt.scatter()). Reversed versions of each colour map follow the same syntax as matplotlib, e.g., cmap='scicm.Stone_r'.

Diverging colour maps are unique in that they have duplicated access to their reverse forms, enabled by the fact that they are symmetric in lightness, with cmap='scicm.BkR_r' being equivalent to cmap='scicm.RkB'. Although perhaps redundant, this is more user-friendly than remembering the correct ordering for the colour combinations, so yes, cmap='scicm.RkB_r' is the same as cmap='scicm.BkR'.

The colour map objects are also directly accessible via the scicm.cm submodule. For example, scicm.cm.Stone returns the colour map object for the Stone colour map. The following code snippet shows these different call methods in practice:

import scicm
import numpy as np
import matplotlib.pyplot as plt

# Generating random data
rng=np.random.default_rng()
x=rng.multivariate_normal((0,0),((0.5,0.1),(0.1,0.3)),10000)
y=x[:,1]
x=x[:,0]

# Creating figure
fig,axes=plt.subplots(nrows=2,ncols=2,figsize=(12,12),gridspec_kw=dict(wspace=0.0,hspace=0.0))
axes[0,0].hexbin(x,y,lw=0,cmap='scicm.Stone',gridsize=80)
axes[0,1].hexbin(x,y,lw=0,cmap='scicm.Stone_r',gridsize=80)
axes[1,0].hexbin(x,y,lw=0,cmap=scicm.cm.BkR,gridsize=80)
axes[1,1].hexbin(x,y,lw=0,cmap='scicm.RkB',gridsize=80)
for ax in axes.flatten():
    ax.set_xlim(np.min(x),np.max(x))
    ax.set_ylim(np.min(y),np.max(y))
    ax.set_axis_off()
plt.show()

Using the colour map manipulation tools

SciCM also includes three tools for colour map manipulation, all part of the scicm.tools submodule. All of these functions accept colour map objects or strings for names that are registered with matplotlib. The simplest tool is scicm.tools.crop, which takes one colour map and returns a cropped version of it. In the following example, we take a crop of the matplotlib magma colour map.

shortMagma=scicm.tools.crop('magma',0.4,1.0)

fig,axes=plt.subplots(nrows=1,ncols=2,figsize=(12,6),gridspec_kw=dict(wspace=0.0,hspace=0.0))
axes[0].hexbin(x,y,lw=0,cmap='magma',gridsize=40)
axes[0].set_title('magna',fontsize=25,path_effects=[pe.withStroke(linewidth=2,foreground='w')])
axes[1].hexbin(x,y,lw=0,cmap=shortMagma,gridsize=40)
axes[1].set_title('shortened magna',fontsize=25,path_effects=[pe.withStroke(linewidth=2,foreground='w')])
for ax in axes.flatten():
    ax.set_xlim(np.min(x),np.max(x))
    ax.set_ylim(np.min(y),np.max(y))
    ax.set_axis_off()
plt.tight_layout()
plt.show()

Another tool is scicm.tools.merge, which takes n number of colour maps and transitions from one to the next at the specified n-1 transition points. It is important to note that the product of merging two perceptually uniform colour maps will likely not be perceptually uniform, so particular care must be taken when using this tool. For the example here, we are taking SciCM's BgreyY and PgreyG colour maps and merging them to produce a colour map that goes from blue to grey to green:

BgreyG=scicm.tools.merge(['scicm.BgreyY','scicm.PgreyG'],[0.5])

fig,axes=plt.subplots(nrows=1,ncols=3,figsize=(18,6),gridspec_kw=dict(wspace=0.0,hspace=0.0))
axes[0].hexbin(x,y,lw=0,cmap='scicm.BgreyY',gridsize=40)
axes[0].set_title('scicm.BgreyY',fontsize=25,path_effects=[pe.withStroke(linewidth=2,foreground='w')])
axes[1].hexbin(x,y,lw=0,cmap=BgreyG,gridsize=40)
axes[1].set_title('BgreyG',fontsize=25,path_effects=[pe.withStroke(linewidth=2,foreground='w')])
axes[2].hexbin(x,y,lw=0,cmap='scicm.PgreyG',gridsize=40)
axes[2].set_title('scicm.PgreyG',fontsize=25,path_effects=[pe.withStroke(linewidth=2,foreground='w')])
for ax in axes.flatten():
    ax.set_xlim(np.min(x),np.max(x))
    ax.set_ylim(np.min(y),np.max(y))
    ax.set_axis_off()
plt.tight_layout()
plt.show()

The last tool is scicm.tools.stitch, which is a generalised version of scicm.tools.merge. It allows one to control the range taken from each colour map, which is then compressed or stretched to span the specified range in the output colour map. Even more so than with scicm.tools.merge, this tool can easily lead to perceptually non-uniform colour maps, for those interested in using this tool we suggest first reading our design on colour map manipulation (coming soon). Here we give as an example the creation of a version of SciCM's BkG with reduced dynamic range, using as source the RgreyB and PgreyG colour maps:

diverging_BgreyG=scicm.tools.stitch(['scicm.RgreyB_r','scicm.PgreyG'],[0,0.5],[0.5,1](/MBravoS/scicm/wiki/0,0.5],[0.5,1),[0.5],
                                    name_newcmap='custom.diverging_BgreyG')

fig,axes=plt.subplots(nrows=2,ncols=2,figsize=(12,12),gridspec_kw=dict(wspace=0.0))
axes[0,0].hexbin(x,y,lw=0,cmap='scicm.RgreyB_r',gridsize=40)
axes[0,0].set_title('scicm.RgreyB_r',fontsize=25,path_effects=[pe.withStroke(linewidth=2,foreground='w')])
axes[1,0].hexbin(x,y,lw=0,cmap='custom.diverging_BgreyG',gridsize=40)
axes[1,0].set_title('custom.diverging_BgreyG',fontsize=25,path_effects=[pe.withStroke(linewidth=2,foreground='w')])
axes[0,1].hexbin(x,y,lw=0,cmap='scicm.PgreyG',gridsize=40)
axes[0,1].set_title('scicm.PgreyG',fontsize=25,path_effects=[pe.withStroke(linewidth=2,foreground='w')])
axes[1,1].hexbin(x,y,lw=0,cmap='scicm.BkG',gridsize=40)
axes[1,1].set_title('scicm.BkG',fontsize=25,path_effects=[pe.withStroke(linewidth=2,foreground='w')])
for ax in axes.flatten():
    ax.set_xlim(np.min(x),np.max(x))
    ax.set_ylim(np.min(y),np.max(y))
    ax.set_axis_off()
plt.tight_layout()
plt.show()