Legs API
- class domutils.legs.legs.PalObj(range_arr=None, dark_pos=None, color_arr=None, n_col=None, map_f_arr=None, solid=None, over_high=None, under_low=None, over_under=None, excep_val=None, excep_tol=None, excep_col=None)
A class for intuitive construction of color palettes
Easy construction of qualitative, semi-quantitative, categorical and divergent color mappings
Guarantees that a color is assigned for data values between -infinity and +infinity
Explicit handling of colors at and/or exceeding end points
Supports any number of exception values assigned to specific colors
Encourages the user to specify units of data being depicted
Consistency of the color palettes and colored representation of data is assured through the use of the same color mapping functions.
- Parameters:
range_arr (
Optional
[List
[float
]]) –End points of the different color legs.
Must be:
A two element array-like describing the maximum and minimum data values represented by the color palette
eg:
[0.,1]
A n element array-like describing the data values delimiting the bounds of each color leg.
eg:
[0.,1.,10.,100, ...]
In this case, the dimension of range_arr should be the number of legs +1
color_arr (
Optional
[Any
]) –Defines the different colors to be used in a palette.
For categorical palettes, it is used in conjunction with the solid keyword.
It can be:
A list of named colors
eg: [“red”,”green”]
for two semi-continuous color legs, one red and one green
An array-like of rgb colors describing dark and light values of each color leg.
eg:
[[[158, 0, 13],[255,190,187]],[[ 0,134, 0],[134,222,134]]]
for two semi-continuous color legs, one red and one green (same as above) In this context, the number of elements in color_arr must be a multiple of 6 (two rgp value per legs)
For categorical color palettes color_arr must be an array-like of rgb colors describing solid colors for each color leg. This requires that the “solid” keyword be specified.
With solid=”col_dark” or solid=”col_light” color_arr must be a list of strings of named colors
eg:
["red","green"]
The dark or light shade of this color will be used for each leg.
With solid=”supplied” “color_arr” must be an array-like of rgb colors
eg:
[[255,000,000],[000,255,000]]
for two color legs, one solid red, the other solid green.
solid (
Optional
[str
]) – A string set to"supplied"
,"col_dark"
or"col_light"
. See the documentation of the color_arr argument for usage.dark_pos (
Optional
[List
[str
]]) –Defines whether the dark color is to be associated with high or low data value. It is only meaningful when constructing a continuous or semi-continuous palettes.
The default is to assign dark colors to the larger data values
If set to “high” or “low” all legs will be set to the high or low data value
If set to a list of strings,
eg:
["high","low"]
,it will determine the position of the dark color for the individual color legs. In this case, the length of the list should be the same as the number of legs in the palette.
n_col (
Optional
[int
]) –Specifies how many color to display when using the default color sequence.
It must be convertible to an integer number.
It must be <= 8.
over_high (
Optional
[str
]) –Determines what color gets assigned to data values larger than the palette range.
Accepted values are:
"exact"
: no data values expected beyond the range of the color mapping.. At the moment of applying the color mapping, an error will be raised if such data values are found."extend"
: The end-point color will be used for data beyond the range of the color mappingA named color:
eg:
"red"
A rgb color:
eg:
[ 0, 0,255]
under_low (
Optional
[str
]) –Determines what color gets assigned to data values smaller than the palette range.
Accepted values are:
"exact"
: no data values expected beyond the range of the color mapping.. At the moment of applying the color mapping, an error will be raised if such data values are found."extend"
: The end-point color will be used for data beyond the range of the color mappingA named color:
eg:
"red"
A rgb color:
eg:
[ 0, 0,255]
over_under (
Optional
[str
]) – Shortcut to specify both over_high and under_low at the same timeexcep_val (
Optional
[List
[float
]]) – Data values to which special colors will be assigned.excep_tol (
Optional
[List
[float
]]) –Tolerance within which a data value specified in excep_val is considered an exception
exception_range = excep_val +- except_tol inclusively
excep_tol must have the same dimension as “excep_val”
excep_col (
Optional
[Any
]) –Color(s) to be assigned to data value specified in excep_val
Must be
A string describing a named colors
eg:
"dark_red"
This color will be assigned to all exceptions.
A 1D list of named colors
eg:
["dark_red" ,"dark_blue" , ... , "dark_green" ]
A 2D array-like of rgb colors
eg:
[[000,000,255],[000,255,000], ... , [000,000,255]]
For cases 2 and 3, the number of colors represented must be equal to the number of exceptions provided in “excep_val”.
map_f_arr (
Optional
[Callable
]) –Defines the name of the function that performs the mapping between data values and rgb values.
If a string, the function will be used for all color legs of a palette.
If a list of strings, it defines the mapping function for each individual legs. In this case, the dimension of map_f_arr should be equal to the number of color legs.
The default behavior is to use the “linmap” function. For linear interpolation of rgb between two predefiuned colors.
When the solid keyword is set, the “within” function is used instead.
- Callable
alias of
Callable
- np = <module 'numpy' from '/home/docs/checkouts/readthedocs.org/user_builds/domutils/conda/stable/lib/python3.7/site-packages/numpy/__init__.py'>
- plot_data(ax, data, palette=None, zorder=None, aspect='auto', rot90=None, **kwargs)
Applies the mapping from data space to color space and plots the result into an existing axes.
- Parameters:
ax (
Any
) – The matplotlib Axes object where imshow will plot the datadata (
ndarray
) – Data to be plottedpalette (
Optional
[str
]) – Flag to show a palette beside the data axes.aspect (
Optional
[Any
]) – aspect ratio, see documentation for axes.set_aspect()rot90 (
Optional
[int
]) – Number of counter-clockwise rotations to be applied to data before plottingzorder (
Optional
[int
]) – Matplotlib zorder for the imshow call
- plot_palette(data_ax=None, equal_legs=None, pal_pos=None, pal_sp=0.1, pal_w=0.25, pal_units='Undefined Units', pal_linewidth=0.3, pal_format='{:3.3f}')
plot a color palette near an existing axes where data is displayed
- Parameters:
data_ax (
Optional
[Any
]) – The matplotlib axes where the data is plotted. The palette will be plotted in an ax besides this Has no effect if pal_pos is provided.equal_legs (
Optional
[bool
]) –Flag indicating that all color legs should have the same space in the palette.
The default is to set the space proportional to the data interval spanned by individual color legs.
pal_pos (
Optional
[Any
]) – Position [x0,y0,width,height] for plotting palette.pal_sp (
Optional
[float
]) – Space [inches] between figure and palettepal_w (
Optional
[float
]) – Width [inches] of color palettepal_units (
Optional
[str
]) – The units of the palette being shown.pal_linewidth (
Optional
[float
]) – Width of the linespal_format (
Optional
[str
]) – Format string for the data values displayed beside tickmarks
- to_rgb(data_in)
Applies the mapping from data space to color space and returns resulting rgb array
- Parameters:
data – Data to be plotted
- Return type:
ndarray