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:

    1. A two element array-like describing the maximum and minimum data values represented by the color palette

      eg: [0.,1]

    2. 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:

    1. A list of named colors

      eg: [“red”,”green”]

      for two semi-continuous color legs, one red and one green

    2. 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)

    3. 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.

      1. 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.

      2. 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:

    1. "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.

    2. "extend": The end-point color will be used for data beyond the range of the color mapping

    3. A named color:

      eg: "red"

    4. 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:

    1. "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.

    2. "extend": The end-point color will be used for data beyond the range of the color mapping

    3. A named color:

      eg: "red"

    4. A rgb color:

      eg: [  0,  0,255]

  • over_under (Optional[str]) – Shortcut to specify both over_high and under_low at the same time

  • excep_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

    1. A string describing a named colors

      eg: "dark_red"

      This color will be assigned to all exceptions.

    2. A 1D list of named colors

      eg: ["dark_red"   ,"dark_blue"  , ... , "dark_green" ]

    3. 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.

    1. If a string, the function will be used for all color legs of a palette.

    2. 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/latest/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 data

  • data (ndarray) – Data to be plotted

  • palette (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 plotting

  • zorder (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 palette

  • pal_w (Optional[float]) – Width [inches] of color palette

  • pal_units (Optional[str]) – The units of the palette being shown.

  • pal_linewidth (Optional[float]) – Width of the lines

  • pal_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