casys.visualization

CasysPlot: main diagnostic visualization class.

Functions

create_image_grid(figure_size, plots[, ...])

Build an image containing all provided plots in as a grid of plots.

Classes

`CasysPlot`(data, data_name[, stat, template, ...])	CasysPlot is a plotting tool, allowing simple predefined actions as well as exposing the matplotlib axis for more advanced customizations.
`AxeType`(value[, names, module, qualname, ...])	Graphical axe type.
`AxisType`(value[, names, module, qualname, ...])	Type representing figure axis.
`ElementType`(value[, names, module, ...])	Type representing plot elements.
`Position`(value[, names, module, qualname, ...])	Position of a graphical element on a figure.
`TargetAxisType`(value[, names, module, ...])	Type representing a plot axis type.

class casys.visualization.AxeType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Graphical axe type.

MAIN = 1

TWIN_X = 2

TWIN_Y = 3

to_axis_type()

Convert this AxeType into a matching AxisType.

Return type:: AxisType
Returns:: Matching AxisType.

class casys.visualization.AxisType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Type representing figure axis.

ALL = 6

X = 1

X_NEW = 4

Y = 2

Y_NEW = 5

Z = 3

matching_axe()

Convert this AxisType into a matching AxeType.

Return type:: AxeType
Returns:: Matching AxeType.

opposite_axe()

Convert this AxisType into an opposite AxeType.

Return type:: AxeType
Returns:: Matching AxeType.

twin_axis()

Convert this AxisType to its twin match.

Return type:: AxisType
Returns:: Matching AxeType.

class casys.visualization.CasysPlot(data, data_name, stat=None, template=None, data_params=None, plot_params=None, text_params=None, **kwargs)

Bases: object

CasysPlot is a plotting tool, allowing simple predefined actions as well as exposing the matplotlib axis for more advanced customizations.

Parameters:

data (CommonData | PlotContainer) – Data container object from which to extract plot data or PlotContainer object.
data_name (str | None) – Name of the data in the data container object.
stat (StatType | str | None) – Name of the statistic to extract.
template (str | PlotTemplate | None) – Parameters template to use. This template will be overloaded with provided plot, text and data parameters.
plot_params (PlotParams | None) – Plot parameters.
text_params (TextParams | None) – Text parameters.
data_params (DataParams | None) – Data parameters.
kwargs –
Additional parameters used to generate the plot.

When used to create a plot from a computed diagnostic, these additional parameters are passed to the container.get_data method. The description of these parameters can be found in each add_diagnostic method’s documentation.

When used to create a direct plot from non-computed data, these parameters might contain the following elements:

field
Field for which to create a raw_data diagnostic.

x
Field to use as x-axis (raw comparison diagnostic).

y
Field to use as y-axis (raw comparison diagnostic).

start
Starting time.

end
Ending time.

add_color_bar(position=None, params=None)

Add a color bar.

Parameters:

position (Position | str | None) –
Position of the colorbar (top, bottom, left, right)
- Default to bottom for maps
- Default to right for graphics
params (str | AxeParams | None) – Bar’s parameters.

add_event(event)

Add an event to the plot.

Parameters:: event (CasysEvent) – the event to add

add_hist_bar(position=BOTTOM, for_axis=None, y_limits=None, params=None)

Add a histogram graphic for the axis data.

This kind of graphic might be added to:

Raw plots
Time plots
Scatter plots
Geographical box plots
2D binned statistics plots

Parameters:

position (Position | str) – Position of the histogram graph (top, bottom, left, right) (default to bottom).
for_axis (TargetAxisType | str) – Name of the axis for which to compute and display this graphic (X, Y or Z). Default value is the z-axis (Z).
y_limits (tuple[float | int, float | int]) – Limits for the “y-axis” of the histogram graphic to add.
params (AxeParams) – Bar’s parameters.

add_plot(cplot, shared_ax='all')

Add a plot to the current one.

The provided plot is copied with its current parameters. Modifying it afterward won’t affect the added plot, you have to set it before.

Parameters:

cplot (CasysPlot) – CasysPlot to add.
shared_ax (AxisType | str) – Axis to share with the current plot (x, y or all).

add_stat_bar(position=None, stats=None, nb_digits=None, params=None)

Add a bar containing number, minimum, mean, median, maximum and standard deviation information.

Parameters:

position (Position | str | None) – position of the stat bar (top, bottom, left, right) (default to top)
stats (list[str | StatType] | None) – List of the statistics to display in the stat bar.
nb_digits (int | None) – Number of significant digits for statistics values.
params (AxeParams) – Bar’s parameters.

add_stat_graph(for_axis=None, position=None, y_limits=None, params=None)

Add a graphic containing mean/std for each X or Y box.

This kind of graphic might be added to:

Geographical box plots
Scatter plots
2D binned statistics plots

Parameters:

for_axis (TargetAxisType | str) – Name of the axis for which to compute and display this graphic (X or Y). Default value is the x-axis (X).
position (Position | str) – Position of the stat graph (top, bottom, left, right) (default to top).
y_limits (tuple[float | int, float | int]) – Limits for the “y-axis” of the stat graphic to add.
params (AxeParams) – Bar’s parameters.

add_ticks_space(*, space, position)

Add space for ticks at the given position.

Parameters:

space (float) – Space to add.
position (Position | str) – Position where to add space.

add_watermark(image, image_size=None, xo=None, yo=None, alpha=None, **kwargs)

Add a watermark.

Parameters:

image (str | ndarray) – file path or numpy array.
image_size (tuple[int | None, int | None] | int | None) – Tuple (width, height) in pixels (width or height can be None), or an integer representing a percentage of the plot’s width used to resize the image. If the image is a numpy array, it cannot be resized.
xo (int) – the x image offset in pixels.
yo (int) – the y image offset in pixels.
alpha (float) – the alpha blending value.
kwargs – other parameters to pass to underlying matplotlib function : https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.figimage.html

adjust_coordinates(longitude=0, latitude=0)

Adjust plots longitudes and latitudes coordinates.

Parameters:

longitude (float) – Value to add.
latitude (float) – Value to add.

center_data(center)

Center the plot data.

Parameters:: center (str | int | float | None) – Value, clip like str or function to use on the plot data.

concatenate_data(cplots)

Concatenate data from provided plots into the current one.

Parameters:: cplots (CasysPlot | list[CasysPlot]) – List of plots to concatenate.

property container: PlotContainer

Plot’s container.

Returns:: PlotContainer.

property data: Dataset

Plot’s input data.

Returns:: Data.

property data_used: Dataset

Plot’s displayed data (constrained by DataParams).

Returns:: Data.

property figure: Figure

Matplotlib figure object of the plot. Axes can be access through the axes’ property:

The main graphic is the first axes of the figure.
Following axes are the additional bars in their addition order.

Returns:: Matplotlib figure

classmethod from_array(name, data, dtype, x, y, z=None, time=None, index=None, stat=None, template=None, data_params=None, plot_params=None, text_params=None, params_level=PropertiesLevel.DEFAULT, **kwargs)

Create a CasysPlot object from a xarray Dataset or DataArray.

Parameters:

name (str) – Name of the plot.
data (DataArray | Dataset) – Plot data.
dtype (str | DataType) –
Type of plot:
- STAT_TIME: Along time data.
- STAT_BINNED: Binned data.
- STAT_BINNED_2D: 2D binned data.
- STAT_BINNED_2D_CURVE: 2D binned data, set of curves.
- STAT_BINNED_2D_SURFACE: 2D binned data in 3d, surface.
- STAT_BINNED_2D_BOX3D: 2D binned data in 3d, surface by boxes.
- STAT_HISTO: Histogram data.
- RAW_DATA: Raw data
- RAW_DATA_3D_SCATTER: Raw data in 3d, surface.
- RAW_DATA_3D_SURFACE: Raw data in 3d, scatter.
- RAW_COMPARISON: Raw data
- RAW_COMPARISON_3D_SCATTER: Raw data in 3d, surface.
- RAW_COMPARISON_3D_SURFACE: Raw data in 3d, scatter.
- STAT_GEOBOX: Geographically binned data.
- STAT_SCATTER: Scatter data.
x (str | Field) – x-axis field.
y (str | Field) – y-axis field.
z (str | Field | None) – z-axis field.
time (str | None) – Time axis field’s name (only required for raw data’s map plots).
index (str | None) – Data’s index name (only required for raw data’s map plots).
stat (StatType | str | None) – Statistic type.
template (str | PlotTemplate | None) – Parameters template to use. This template will be overloaded with provided plot, text and data parameters.
data_params (DataParams | None) – Plot’s data parameters.
plot_params (PlotParams | None) – Plot’s visualization parameters.
text_params (TextParams | None) – Text parameters.
params_level (PropertiesLevel) – Properties level at which provided parameters has to be normalized.
kwargs – Additional specific parameters for the PlotContainer.

Return type:

CasysPlot

Returns:

A CasysPlot object.

classmethod load(name)

Load a previously stored CasysPlot object.

Parameters:: name (str) – Name and path of the file.
Return type:: CasysPlot
Returns:: The loaded object.

remove_events(): Remove all events from this plot.

reset(): Reinitialize this plot by removing anything previously added to it.

save_figure(path, **kwargs)

Save this CasysPlot figure at the provided path. Generate a default one if not already generated.

Parameters:

path (str | BytesIO) – Path to the file where to save the figure.
kwargs – Additional parameters passed to the underlying matplotlib save_fig method.

set_data_params(params)

Change the plot’s data parameters and refresh it.

Parameters:: params (DataParams) – Plot’s data parameters.

set_element_params(element, params)

Set the parameters of the provided element.

Parameters:

element (ElementType | str) –
Element to set. Available elements are:
- title
- legend
- x1
- y1
- x2
- y2
- stat_bar
- color_bar
- hist_bar_x
- hist_bar_y
- hist_bar_z
- stat_graph_x
- stat_graph_y
params (AxeParams) – Element parameters.

set_legend(legend)

Set the figure legend.

Parameters:: legend (str) – legend of the figure

set_plot_params(params)

Change the plot’s visualization parameters and refresh it.

Parameters:: params (PlotParams) – Plot’s visualization parameters.

set_size(width, height)

Set the figure size.

Parameters:

width (float) – Width of the figure.
height (float) – Height of the figure.

set_text_params(params)

Change the text parameters and refresh it.

Parameters:: params (TextParams) – Text parameters.

set_text_size(size, elements=TITLE)

Resize all text elements of the figure. (except for events labels)

Parameters:

size (str | int) – the new size.
elements (TextElementType | str | list[TextElementType | str] | set[TextElementType]) –
As a single element or a list of elements. Possibilities are:
- ”all”
- ”title” (only title),
- ”legend” (legend),
- ”axes_labels” (labels of axes),
- ”bars_labels” (labels of stat and color bar),
- ”axes_ticks” (ticks of axes),
- ”bars_ticks” (ticks of color bar)

set_ticks(position=None, fmt=None, params=None, **kwargs)

Change ticks parameters on specified axis.

Parameters:

position (str | Position | None) – Position of the axis on which to change the ticks (default to bottom axis).
fmt (str | CyclePassFmt | None) – Cycle / pass format to display (‘C’, ‘P’ or ‘CP’).
params (AxeParams) – Additional text formatting options.

set_title(title)

Set the figure title.

Parameters:: title (str) – title of the figure.

set_xlabel(xlabel)

Set the text of the x-axis label.

Parameters:: xlabel (str) – xlabel of the figure

set_ylabel(ylabel)

Set the text of the y-axis label.

Parameters:: ylabel (str) – ylabel of the figure

show(**kwargs)

Displays the plot.

kwargs Additional parameters passed to the underlying matplotlib save_fig method.

showi(**kwargs): Interactive display of the plot.

Warning

this method is experimental for now

showv(merge=True, columns=2)

Vador display of the plot.

Parameters:

merge (bool) – Whether to merge added plots (True) or display them as a grid (False).
columns (int) – If displayed as a grid, number of columns of this grid.

store(name, overwrite=False)

Store this CasysPlot object into a pickle format.

Parameters:

name (str) – Name and path of the file.
overwrite (bool) – Whether to overwrite any existing file or not.

property template: PlotTemplate

Plot’s template.

Templates contain all the plot’s elements properties.

Returns:: Plot’s template.

transform_data(transform)

Transform the plot data.

Parameters:: transform (Union[str, Callable, None]) – Clip like str or function to use on the plot data.

class casys.visualization.ElementType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Type representing plot elements.

COASTLINES = 10

COLOR_BAR = 13

DATA = 11

GRID = 9

HIST_BAR_X = 14

HIST_BAR_Y = 15

HIST_BAR_Z = 16

LEGEND = 7

PLOT = 8

STAT_BAR = 12

STAT_GRAPH_X = 17

STAT_GRAPH_Y = 18

TITLE = 6

X1 = 1

X2 = 4

Y1 = 2

Y2 = 5

Z = 3

static normalize(axt)

Normalize the provided AxisType into a matching ElementType.

Parameters:: axt (ElementType | AxisType) – Type to normalize.
Return type:: ElementType
Returns:: Normalized ElementType.

class casys.visualization.Position(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Position of a graphical element on a figure.

BOTTOM = 2

LEFT = 3

RIGHT = 4

TOP = 1

ticks_space(ticks_position, geo_axe=False)

Parameters:

ticks_position (Position)
geo_axe (bool)

Return type:

float

static ticks_space_values(geo_axe)

Parameters:: geo_axe (bool)
Return type:: dict[Position, dict[Position, float]]

to_axis_type()

Convert this Position into a matching AxisType.

Return type:: AxisType
Returns:: Matching AxisType.

class casys.visualization.TargetAxisType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Type representing a plot axis type.

GLOBAL = 3

LATITUDE = 2

LONGITUDE = 1

X = 1

Y = 2

Z = 3

casys.visualization.create_image_grid(figure_size, plots, rows_nb=None, columns_nb=None, save_path=None, dpi=100, **kwargs)

Build an image containing all provided plots in as a grid of plots.

Parameters:

figure_size (tuple[int, int]) – Figure size (width, height).
plots (list[CasysPlot | str]) – List of CasysPlots or/and images path.
rows_nb (int) – Number of rows in the grid.
columns_nb (int) – Number of columns in the grid.
save_path (str | list[str]) – Save individual plot in the specified directory.
dpi – Resulting image dpi.
kwargs – Additional parameters passed to the pyplot’s figure method.

Return type:

Figure

Returns:

Matplotlib figure containing everything.