Plot_data python API documentation

plot data is a language to draw in a web browser some awesome plots and graphs. Its rendering engine is written in typescript. This doc is for the python package to create the data structure to give to typescript lib for rendering.

For the typescript doc see: https://documentation.dessia.tech/plot_data/typescript

plot_data.delete_none_from_dict(dict1)[source]

Delete input dictionary’s keys where value is None.

class plot_data.PlotDataObject(type_: str, name: str = '', **kwargs)[source]

Abstract interface for DessiaObject implementation in module.

mpl_plot(ax=None, **kwargs)[source]

Overloading of dessia object mpl_plot.

to_dict(**kwargs) → Dict[str, Any][source]

Redefines DessiaObject’s to_dict() in order not to use pointers and remove keys where value is None.

class plot_data.HatchingSet(stroke_width: float = 1, hatch_spacing: float = 10, name: str = '')[source]

A class for setting hatchings on a surface.

Parameters:

  • stroke_width (float) – lines’ width

  • hatch_spacing (float) – the spacing between two hatching in pixels

class plot_data.EdgeStyle(line_width: float | None = None, color_stroke: Color | None = None, dashline: List[int] | None = None, name: str = '')[source]

A class for customizing edges (such as lines) style.

Parameters:

  • line_width (float) – line width in pixels.

  • color_stroke (plot_data.Colors.Color) – the edge’s color (rgb255).

  • dashline (List[float]) – a list of positive floats [a1,…,an] representing a pattern where a_2i is the number of solid pixels and a_2i+1 is the number of empty pixels.

mpl_arguments(surface=False)[source]

Get matplotlib equivalent values of attributes.

class plot_data.PointStyle(color_fill: str | None = None, color_stroke: str | None = None, stroke_width: float | None = None, size: float | None = None, shape: str | None = None, orientation: str | None = None, name: str = '')[source]

A class for customizing Point2D.

Parameters:

  • color_fill (str) – must be in rgb255.

  • color_stroke (str) – must be in rgb255.

  • stroke_width (float) – the point contour’s width.

  • size (float) – must be 1, 2, 3 or 4.

  • shape (str) – ‘circle’, ‘square’ or ‘crux’.

classmethod dict_to_object(dict_, *args, **kwargs)[source]

Overwrite generic dict_to_object.

mpl_arguments()[source]

Get matplotlib equivalent values of attributes.

class plot_data.TextStyle(text_color: Color | None = None, font_size: float | None = None, font_style: str | None = None, text_align_x: str | None = None, text_align_y: str | None = None, bold: bool | None = None, italic: bool | None = None, angle: float | None = None, name: str = '')[source]

A class for customizing Text.

Parameters:

  • text_color (plot_data.colors.Colors) – the text’s color

  • font_size (float) – the font size

  • font_style (str) – ‘Arial’, ‘Verdana’, ‘Times New Roman’, ‘Courier New’, ‘serif’ or ‘sans-serif’

  • text_align_x (str) – “left”, “right”, “center”, “start” or “end”. More info on https://www.w3schools.com/tags/canvas_textalign.asp

  • text_align_y (str) – “top”, “hanging”, “middle”, “alphabetic”, “ideographic” or “bottom”. More info on https://www.w3schools.com/tags/canvas_textbaseline.asp

  • bold (bool) –

  • italic (bool) –

  • angle (float) – Text angle in degrees. The angle is clockwise.

classmethod dict_to_object(dict_, *args, **kwargs)[source]

Overwrite generic dict_to_object.

class plot_data.SurfaceStyle(color_fill: str | None = None, opacity: float = 1.0, hatching: HatchingSet | None = None, name: str = '')[source]

A class for customizing surfaces.

Parameters:

  • color_fill (str) – fill color

  • opacity (float) – from 0 (transparent) to 1 (opaque).

  • hatching (HatchingSet) – for setting hatchings

classmethod dict_to_object(dict_, *args, **kwargs)[source]

Overwrite generic dict_to_object.

mpl_arguments()[source]

Get matplotlib equivalent values of attributes.

class plot_data.Text(comment: str, position_x: float, position_y: float, text_style: TextStyle | None = None, text_scaling: bool | None = None, max_width: float | None = None, height: float | None = None, multi_lines: bool = True, reference_path: str = '#', tooltip: str | None = None, name: str = '')[source]

A class for displaying texts on canvas. Text is a primitive and can be instantiated by PrimitiveGroup.

Parameters:

  • comment (str) – the comment you want to display

  • position_x (float) – the text’s x position

  • position_y (float) – the text’s y position

  • text_style (TextStyle) – for customization (optional)

  • text_scaling (bool) – True if you want the text the be rescaled when zooming and False otherwise.

  • max_width – Set a maximum length for the text. If the text is longer than max_width, it is split into

several lines. :type max_width: float :param multi_lines: This parameter is only useful when max_width parameter is set. In that case, you can choose between squishing the text in one line or writing on multiple lines. :type multi_lines: bool

mpl_plot(ax=None, color='k', alpha=1.0, **kwargs)[source]

Plots using Matplotlib.

class plot_data.Line2D(point1: List[float], point2: List[float], edge_style: EdgeStyle | None = None, reference_path: str = '#', tooltip: str | None = None, name: str = '')[source]

An infinite line. Line2D is a primitive and can be instantiated by PrimitiveGroups.

Parameters:

  • point1 (List[float]) – first endpoint of the line segment [x1, y1].

  • point2 (List[float]) – first endpoint of the line segment [x2, y2].

  • edge_style (EdgeStyle) – for customization

mpl_plot(ax=None, edge_style=None, **kwargs)[source]

Plots using matplotlib.

class plot_data.LineSegment2D(point1: List[float], point2: List[float], edge_style: EdgeStyle | None = None, reference_path: str = '#', tooltip: str | None = None, name: str = '')[source]

A line segment. This is a primitive that can be called by PrimitiveGroup.

Parameters:

  • point1 (List[float]) – first endpoint of the line segment [x1, y1].

  • point2 (List[float]) – first endpoint of the line segment [x2, y2].

  • edge_style (EdgeStyle) – for customization

bounding_box()[source]

Get 2D bounding box of current LineSegment2D.

mpl_plot(ax=None, edge_style=None, **kwargs)[source]

Plots using matplotlib.

polygon_points()[source]

Get lists of points in a merged list.

class plot_data.Circle2D(cx: float, cy: float, r: float, edge_style: EdgeStyle | None = None, surface_style: SurfaceStyle | None = None, tooltip: str | None = None, reference_path: str = '#', name: str = '')[source]

A circle. It is a primitive and can be instantiated by PrimitiveGroup.

Parameters:

  • cx (float) – the center’s x position.

  • cy (float) – the center’s y position

  • r (float) – radius

  • edge_style (EdgeStyle) – customization of the circle’s contour

  • surface_style (SurfaceStyle) – customization of the circle’s interior

  • tooltip (str) – tooltip message

bounding_box()[source]

Get 2D bounding box of current Circle2D.

mpl_plot(ax=None, **kwargs)[source]

Plots using matplotlib.

class plot_data.Point2D(cx: float, cy: float, point_style: PointStyle | None = None, reference_path: str = '#', tooltip: str | None = None, name: str = '')[source]

A class for instantiating a point.

Parameters:

  • cx (float) – the point center’s x position

  • cy (float) – the point center’s y position

  • point_style (PointStyle) – the point’s customization.

bounding_box()[source]

Get 2D bounding box of current Circle2D.

mpl_plot(ax=None, **kwargs)[source]

Plots using matplotlib.

class plot_data.Axis(nb_points_x: int | None = None, nb_points_y: int | None = None, graduation_style: TextStyle | None = None, axis_style: EdgeStyle | None = None, arrow_on: bool = False, grid_on: bool = True, name: str = '')[source]

A class that contains information for drawing axis.

Parameters:

  • nb_points_x (int) – the average number of points displayed on the x-axis.

  • nb_points_y (int) – the average number of points displayed on the y-axis.

  • graduation_style (TextStyle) – for graduation customization

  • axis_style (EdgeStyle) – for customizing the axis itself.

  • arrow_on (bool) – True if you want an arrow to be displayed on axis, False otherwise.

  • grid_on (bool) – True if you want the display a grid, False otherwise

class plot_data.Tooltip(attributes: List[str] | None = None, text: str | None = None, surface_style: SurfaceStyle | None = None, text_style: TextStyle | None = None, tooltip_radius: float | None = None, name: str = '')[source]

A class that contains information for drawing a tooltip when clicking on points.

Parameters:

  • attributes (List[str]) – a list containing the attributes you want to display. Attributes must be taken from Dataset’s or Scatter’s elements.

  • surface_style (SurfaceStyle) – for customizing the tooltip’s interior

  • text_style (TextStyle) – for customizing its text

  • tooltip_radius (float) – a tooltip is rounded-rectangle-shaped. This parameter defines its corners radius.

class plot_data.Dataset(elements: List[Sample] | None = None, edge_style: EdgeStyle | None = None, tooltip: Tooltip | None = None, point_style: PointStyle | None = None, partial_points: bool | None = None, display_step: int = 1, name: str = '')[source]

Numerous points are joined by line segments to display a mathematical curve.

Datasets are instantiated by Graph2D to display multiple datasets on one canvas.

Parameters:

  • elements (List[dict]) – A list of vectors. Vectors must have the same attributes (ie the same keys)

  • edge_style (EdgeStyle) – for customizing line segments.

  • point_style (PointStyle) – for customizing points

  • tooltip (Tooltip) – an object containing all information for drawing tooltips

  • display_step (int) – a value that limits the number of points displayed.

  • attribute_names ([str, str]) – [attribute_x, attribute_y] where attribute_x is the attribute displayed on x-axis and attribute_y is the attribute displayed on y-axis.

class plot_data.Graph2D(graphs: List[Dataset], x_variable: str, y_variable: str, axis: Axis | None = None, log_scale_x: bool | None = None, log_scale_y: bool | None = None, width: int = 750, height: int = 400, axis_on: bool = True, name: str = '')[source]

Takes one or several Datasets as input and displays them all in one canvas.

Parameters:

  • graphs (List[Dataset]) – a list of Datasets

  • x_variable (str) – variable that you want to display on x axis

  • y_variable (str) – variable that you want to display on y axis

  • axis (Axis) – an object containing all information needed for drawing axis

  • log_scale_x (bool) – True or False

  • log_scale_y (bool) – True or False

mpl_plot(ax=None, **kwargs)[source]

Plots using matplotlib.

class plot_data.Scatter(x_variable: str | None = None, y_variable: str | None = None, tooltip: Tooltip | None = None, point_style: PointStyle | None = None, elements: List[Sample] | None = None, points_sets: List[PointFamily] | None = None, axis: Axis | None = None, log_scale_x: bool | None = None, log_scale_y: bool | None = None, heatmap: Heatmap | None = None, heatmap_view: bool | None = None, width: int = 750, height: int = 400, axis_on: bool = True, name: str = '')[source]

A class for drawing scatter plots.

Parameters:

  • elements – A list of vectors. Vectors must have the same attributes (ie the same keys)

  • x_variable – variable that you want to display on x axis

  • y_variable – variable that you want to display on y axis

  • tooltip – an object containing all information needed for drawing tooltips

  • point_style – for points’ customization

  • axis – an object containing all information needed for drawing axis

  • log_scale_x – True or False

  • log_scale_y – True or False

  • heatmap – Heatmap view settings

  • heatmap_view – Heatmap view when loading the object. If set to False, you’d still be able to enable it using the button.

class plot_data.Arc2D(cx: float, cy: float, r: float, start_angle: float, end_angle: float, clockwise: bool | None = None, edge_style: EdgeStyle | None = None, reference_path: str = '#', tooltip: str | None = None, name: str = '')[source]

A class for drawing arcs. Arc2D is a primitive and can be instantiated by PrimitiveGroup. By default, the arc is drawn anticlockwise.

Parameters:

  • cx (float) – the arc center’s x position

  • cy (float) – the arc center’s y position

  • r (float) – radius

  • start_angle (float) – the start angle in radian

  • end_angle (float) – the end angle in radian

  • data (List[dict]) – a list of relevant points for drawing an arc using BSPline method. This argument is useless unless the arc2D is part of a Contour2D. In such case, the arc must be instantiated by volmdlr.

  • clockwise (bool) – True if you want the arc the be drawn clockwise, False otherwise

  • edge_style (EdgeStyle) – for customization

bounding_box()[source]

Get 2D bounding box of current Circle2D.

mpl_plot(ax=None, **kwargs)[source]

Plots using matplotlib.

polygon_points()[source]

Get lists of points in a merged list.

class plot_data.Contour2D(plot_data_primitives: List[Arc2D | LineSegment2D], edge_style: EdgeStyle | None = None, surface_style: SurfaceStyle | None = None, tooltip: str | None = None, reference_path: str = '#', name: str = '')[source]

A Contour2D is a closed polygon that is formed by multiple primitives.

Parameters:

  • plot_data_primitives (List[Union[Arc2D, LineSegment2D]]) – a list of primitives (Arc2D, LineSegment2D)

  • edge_style (EdgeStyle) – for contour’s customization

  • surface_style (SurfaceStyle) – for customizing the interior of the contour

  • tooltip (str) – A message that is displayed in a tooltip

bounding_box()[source]

Get 2D bounding box of current Contour2D.

mpl_plot(ax=None, **kwargs)[source]

Plots using matplotlib.

polygon_points()[source]

Get lists of points in a merged list.

class plot_data.Label(title: str, text_style: TextStyle | None = None, rectangle_surface_style: SurfaceStyle | None = None, rectangle_edge_style: EdgeStyle | None = None, shape: PlotDataObject | None = None, name: str = '')[source]

An object that adds a label to PrimitiveGroups.

Parameters:

  • title (str) – the text displayed in the label

  • text_style (TextStyle) – customizing the text

  • rectangle_surface_style (SurfaceStyle) – the label’s rectangle interior customization

  • rectangle_edge_style (EdgeStyle) – the label’s rectangle edge customization

class plot_data.MultipleLabels(labels: List[Label], name: str = '')[source]

Draws one or several labels. MultipleLabels can be instantiated by PrimitiveGroup.

Parameters:

labels (List[Label]) – a list of Labels

class plot_data.PrimitiveGroup(primitives: List[Contour2D | Arc2D | LineSegment2D | Circle2D | Line2D | MultipleLabels | Wire | Point2D], width: int = 750, height: int = 400, attribute_names: List[str] | None = None, axis_on: bool = False, name: str = '')[source]

A class for drawing multiple primitives and contours inside a canvas.

Parameters:

primitives (List[Union[Contour2D, Arc2D, LineSegment2D, Circle2D, Line2D, MultipleLabels, Wire, Point2D]]) – a list of Contour2D, Arc2D, LineSegment2D, Circle2D, Line2D or MultipleLabels

bounding_box()[source]

Get 2D bounding box of current PrimitiveGroup.

mpl_plot(ax=None, equal_aspect=True, **kwargs)[source]

Plots using matplotlib.

save_to_image(filepath, remove_axis=True)[source]

Save PrimitiveGroup to a picture generated with matplotlib.

class plot_data.PrimitiveGroupsContainer(primitive_groups: List[PrimitiveGroup], sizes: List[Tuple[float, float]] | None = None, coords: List[Tuple[float, float]] | None = None, associated_elements: List[int] | None = None, x_variable: str | None = None, y_variable: str | None = None, width: int = 750, height: int = 400, axis_on: bool = True, name: str = '')[source]

A class for drawing several PrimitiveGroups in one canvas.

Parameters:

  • primitive_groups (List[PrimitiveGroup]) – a list of PrimitiveGroups

  • sizes (List[Tuple[float, float]]) – [size0,…,size_n] where size_i = [width_i, length_i] is the size of primitive_groups[i]

  • coords (List[Tuple[float, float]]) – In the same way as sizes but for coordinates.

  • associated_elements – A list containing the associated elements indices. associated_elements[i] is associated

with primitive_groups[i]. It only works if this object is inside a MultiplePlots. :type associated_elements: List[int] :param x_variable: variable that you want to display on x axis :type x_variable: str :param y_variable: variable that you want to display on y axis :type y_variable: str

class plot_data.ParallelPlot(elements: List[Sample] | None = None, edge_style: EdgeStyle | None = None, disposition: str | None = None, axes: List[str] | None = None, rgbs: List[Tuple[int, int, int]] | None = None, width: int = 750, height: int = 400, axis_on: bool = True, name: str = '')[source]

Draws a parallel coordinates plot.

Parameters:

  • elements – a list of vectors. Vectors must have the same attributes (ie the same keys)

  • edge_style – for customizing lines

  • disposition – either ‘vertical’ or ‘horizontal’ depending on how you want the initial disposition to be.

  • axes – a list on attribute names you want to display as axis on this parallel plot.

  • rgbs – a list of rgb255 colors for color interpolation. Color interpolation is enabled when clicking on an axis.

class plot_data.Attribute(type_: str, name: str)[source]

Represents an attribute.

Parameters:

  • type – The attribute’s type (in that case, values are either ‘float’, ‘color’ or ‘string’)

  • name – The attribute’s name

class plot_data.PointFamily(point_color: str, point_index: List[int], name: str = '')[source]

A class that defines a point family. This class can be used in MultiplePlots to create families of points.

Parameters:

  • point_color – a color that is proper to this family (rgb255)

  • point_index – a list containing the point’s index from MultiplePlots.elements

class plot_data.MultiplePlots(plots: List[PlotDataObject], sizes: List[Window] | None = None, elements: List[Sample] | None = None, coords: List[Tuple[float, float]] | None = None, point_families: List[PointFamily] | None = None, initial_view_on: bool | None = None, width: int = 750, height: int = 400, axis_on: bool = True, name: str = '')[source]

A class for drawing multiple PlotDataObjects (except MultiplePlots) in one canvas.

Parameters:

  • plots – a list of plots (Scatter, ParallelPlot, PrimitiveGroup, PrimitiveGroupContainer, Graph2D)

  • sizes – [size0,…,size_n] where size_i = [width_i, length_i] is the size of plots[i]

  • elements – a list of vectors. All vectors must have the same attributes (ie the same keys)

  • coords – same as sizes but for plots’ coordinates.

  • point_families – a list of point families

  • initial_view_on – True for enabling initial layout, False otherwise

plot_data.plot_canvas(plot_data_object: Figure, filepath: str | None = None, local: bool = False, canvas_id: str = 'canvas', force_version: str | None = None, width: float | None = None, height: float | None = None)[source]

Creates a html file and plots input data in web browser.

Parameters:

  • plot_data_object (PlotDataObject) – a PlotDataObject(ie Scatter, ParallelPlot, MultiplePlots, Graph2D, PrimitiveGroup or PrimitiveGroupContainer)

  • local (bool) – uses local library if True, uses typescript library from cdn if False

  • canvas_id (str) – set canvas’ id, ie name

  • width (str) – set the canvas’ width:

  • height (str) – set the canvas’ height

  • page_name (str) – set the created html file’s name

plot_data.get_csv_vectors(filepath)[source]

Get csv vector of a VectoredObject (does not exist anymore).

plot_data.bounding_box(plot_datas: List[PlotDataObject])[source]

Calls input plot_datas’ bounding_box method, if it has one.

Parameters:

plot_datas (List[PlotDataObject]) – The target object the bounding_box method has to be called from

Returns:

a bounding box

Return type:

float, float, float, float

class plot_data.colors.Color(red: float, green: float, blue: float, name: str = '')[source]

Base class for handling colors as objects.

classmethod dict_to_object(dict_: Dict[str, Any], **_) → SerializableObject[source]

Get color object from dict.

classmethod from_hex(hex_code)[source]

Get REB color from hexadecimal color.

classmethod from_hsv(hue: float, saturation: float, value: float)[source]

Get RGB color from HSV color.

to_dict(**_) → Dict[str, Any][source]

Get dict of color.

Indices and tables