Plotter

class modusa.tools.plotter.Fig(arrangement='asm', xlim=None, width=16, dark_mode=True)[source]

Bases: object

A utility class that provides easy-to-use API for plotting 1D/2D signals along with clean representations of annotations, events.

Parameters:

  • arrangement (str) –

    • Arrangement of the subplots you want in the figure.

    • ”a” for aux plot which is good for adding annotations and events onto.

    • ”s” for signal plot which is good for 1D array.

    • ”m” for matrix plot which is good for 2D array.

    • E.g., “asm” or “aasm” or “saams”, …

    • Default: “asm”

  • xlim (tuple[number, number] | None) –

    • Since all the subplots share x-axis, we set the x limit while creating the figure.

    • Default: None

  • width (number) –

    • Width of the figure

    • Default: 16

  • dark_mode (bool) –

    • Do you want dark mode?

    • Default: True

add_signal(y, x=None, c=None, ls=None, lw=None, m=None, ms=3, label=None, ylabel=None, ylim=None, yticks=None, yticklabels=None, xticks=None, xticklabels=None, grid=True, ax=None)[source]

Add signal to the figure.

Parameters:

  • y (np.ndarray) –

    • Signal y values.

  • x (np.ndarray | None) –

    • Signal x values.

    • Default: None (indices will be used)

  • c (str) –

    • Color of the line.

    • Default: None

  • ls (str) –

    • Linestyle

    • Default: None

  • lw (Number) –

    • Linewidth

    • Default: None

  • m (str) –

    • Marker

    • Default: None

  • ms (number) –

    • Markersize

    • Default: 3

  • label (str) –

    • Label for the plot.

    • Legend will use this.

    • Default: None

  • ylabel (str) –

    • y-label for the plot.

    • Default: None

  • ylim (tuple) –

    • y-lim for the plot.

    • Default: None

  • yticks (Arraylike) –

    • Positions at which to place y-axis ticks.

  • yticklabels (list of str, optional) –

    • Labels corresponding to yticks. Must be the same length as yticks.

  • xticks (Arraylike) –

    • Positions at which to place x-axis ticks.

  • xticklabels (list of str, optional) –

    • Labels corresponding to xticks. Must be the same length as xticks.

  • grid (bool) –

    • Do you want the grid?

    • Default: True

  • ax (int) –

    • Which specific axis to plot (1, 2, 3, …)

    • None

Return type:

None

add_matrix(M, y=None, x=None, c='viridis', o='upper', label=None, ylabel=None, ylim=None, yticks=None, yticklabels=None, xticks=None, xticklabels=None, cbar=True, grid=True, ax=None)[source]

Add matrix to the figure.

Parameters:

  • M (np.ndarray) –

    • Matrix (2D) array

  • y (np.ndarray | None) –

    • y axis values.

  • x (np.ndarray | None (indices will be used)) –

    • x axis values.

    • Default: None (indices will be used)

  • c (str) –

    • cmap for the matrix.

    • Default: None

  • o (str) –

    • origin

    • Default: “lower”

  • label (str) –

    • Label for the plot.

    • Legend will use this.

    • Default: None

  • ylabel (str) –

    • y-label for the plot.

    • Default: None

  • ylim (tuple) –

    • y-lim for the plot.

    • Default: None

  • yticks (Arraylike) –

    • Positions at which to place y-axis ticks.

  • yticklabels (list of str, optional) –

    • Labels corresponding to yticks. Must be the same length as yticks.

  • xticks (Arraylike) –

    • Positions at which to place x-axis ticks.

  • xticklabels (list of str, optional) –

    • Labels corresponding to xticks. Must be the same length as xticks.

  • cbar (bool) –

    • Show colorbar

    • Default: True

  • grid (bool) –

    • Do you want the grid?

    • Default: True

  • ax (int) –

    • Which specific axis to plot (1, 2, 3, …)

    • None

Return type:

None

add_events(events, c=None, ls=None, lw=None, label=None, grid=True, ax=None)[source]

Add events to the figure.

Parameters:

  • events (np.ndarray) –

    • All the event marker values.

  • c (str) –

    • Color of the event marker.

    • Default: “k”

  • ls (str) –

    • Line style.

    • Default: “-”

  • lw (float) –

    • Linewidth.

    • Default: 1.5

  • label (str) –

    • Label for the event type.

    • This will appear in the legend.

    • Default: None

  • grid (bool) –

    • Do you want the grid?

    • Default: True

  • ax (int) –

    • Which specific axis to plot (1, 2, 3, …)

    • None

Return type:

None

add_annotation(ann, label=None, patterns=None, ylim=(0, 1), text_loc='m', grid=True, ax=None)[source]

Add annotation to the figure.

Parameters:

  • ann (list[tuple[Number, Number, str]] | None) –

    • A list of annotation spans. Each tuple should be (start, end, label).

    • Default: None (no annotations).

  • label (str) –

    • Label for the annotation type.

    • This will appear to the right of the aux plot.

    • Default: None

  • patterns (list[str]) –

    • Patterns to group annotations

    • E.g., “R” or “<tag>” or [“A*”, “*B”]

    • All elements in a group will have same color.

  • ylim (tuple[number, number]) –

    • Y-limit for the annotation.

    • Default: (0, 1)

  • text_loc (str) –

    • Location of text relative to the box. (b for bottom, m for middle, t for top)

    • Default: “m”

  • grid (bool) –

    • Do you want the grid?

    • Default: True

  • ax (int) –

    • Which specific axis to plot (1, 2, 3, …)

    • None

Return type:

None

class Rectangle(xy, width, height, *, angle=0.0, rotation_point='xy', **kwargs)

Bases: Patch

A rectangle defined via an anchor point xy and its width and height.

The rectangle extends from xy[0] to xy[0] + width in x-direction and from xy[1] to xy[1] + height in y-direction.

:                +------------------+
:                |                  |
:              height               |
:                |                  |
:               (xy)---- width -----+

One may picture xy as the bottom left corner, but which corner xy is actually depends on the direction of the axis and the sign of width and height; e.g. xy would be the bottom right corner if the x-axis was inverted or if width was negative.

get_angle()

Get the rotation angle in degrees.

get_bbox()

Return the .Bbox.

get_center()

Return the centre of the rectangle.

get_corners()

Return the corners of the rectangle, moving anti-clockwise from (x0, y0).

get_height()

Return the height of the rectangle.

get_patch_transform()

Return the ~.transforms.Transform instance mapping patch coordinates to data coordinates.

For example, one may define a patch of a circle which represents a radius of 5 by providing coordinates for a unit circle, and a transform which scales the coordinates (the patch coordinate) by 5.

get_path()

Return the vertices of the rectangle.

get_width()

Return the width of the rectangle.

get_x()

Return the left coordinate of the rectangle.

get_xy()

Return the left and bottom coords of the rectangle as a tuple.

get_y()

Return the bottom coordinate of the rectangle.

property rotation_point

The rotation point of the patch.

set(*, agg_filter=<UNSET>, alpha=<UNSET>, angle=<UNSET>, animated=<UNSET>, antialiased=<UNSET>, bounds=<UNSET>, capstyle=<UNSET>, clip_box=<UNSET>, clip_on=<UNSET>, clip_path=<UNSET>, color=<UNSET>, edgecolor=<UNSET>, facecolor=<UNSET>, fill=<UNSET>, gid=<UNSET>, hatch=<UNSET>, hatch_linewidth=<UNSET>, height=<UNSET>, in_layout=<UNSET>, joinstyle=<UNSET>, label=<UNSET>, linestyle=<UNSET>, linewidth=<UNSET>, mouseover=<UNSET>, path_effects=<UNSET>, picker=<UNSET>, rasterized=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, transform=<UNSET>, url=<UNSET>, visible=<UNSET>, width=<UNSET>, x=<UNSET>, xy=<UNSET>, y=<UNSET>, zorder=<UNSET>)

Set multiple properties at once.

Supported properties are

Properties:

agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image alpha: float or None angle: unknown animated: bool antialiased or aa: bool or None bounds: (left, bottom, width, height) capstyle: .CapStyle or {‘butt’, ‘projecting’, ‘round’} clip_box: ~matplotlib.transforms.BboxBase or None clip_on: bool clip_path: Patch or (Path, Transform) or None color: :mpltype:`color` edgecolor or ec: :mpltype:`color` or None facecolor or fc: :mpltype:`color` or None figure: ~matplotlib.figure.Figure or ~matplotlib.figure.SubFigure fill: bool gid: str hatch: {‘/’, ‘\’, ‘|’, ‘-’, ‘+’, ‘x’, ‘o’, ‘O’, ‘.’, ‘*’} hatch_linewidth: unknown height: unknown in_layout: bool joinstyle: .JoinStyle or {‘miter’, ‘round’, ‘bevel’} label: object linestyle or ls: {‘-’, ‘–’, ‘-.’, ‘:’, ‘’, (offset, on-off-seq), …} linewidth or lw: float or None mouseover: bool path_effects: list of .AbstractPathEffect picker: None or bool or float or callable rasterized: bool sketch_params: (scale: float, length: float, randomness: float) snap: bool or None transform: ~matplotlib.transforms.Transform url: str visible: bool width: unknown x: unknown xy: (float, float) y: unknown zorder: float

set_angle(angle)

Set the rotation angle in degrees.

The rotation is performed anti-clockwise around xy.

set_bounds(*args)

Set the bounds of the rectangle as left, bottom, width, height.

The values may be passed as separate parameters or as a tuple:

set_bounds(left, bottom, width, height)
set_bounds((left, bottom, width, height))
set_height(h)

Set the height of the rectangle.

set_width(w)

Set the width of the rectangle.

set_x(x)

Set the left coordinate of the rectangle.

set_xy(xy)

Set the left and bottom coordinates of the rectangle.

Parameters:

xy ((float, float))

set_y(y)

Set the bottom coordinate of the rectangle.

property xy

Return the left and bottom coords of the rectangle as a tuple.

plt = <module 'matplotlib.pyplot' from '/Users/ankit/Documents/meluron-toolbox/modusa/.venv/lib/python3.10/site-packages/matplotlib/pyplot.py'>
add_arrows(xys, labels, text_offset=(0, 0), c='r', fontsize=12, ax=None)[source]

Add multiple arrows pointing to specific points with boxed labels at the tails.

Parameters:

  • xys (list[tuple[float, float]] | tuple[float, float]) –

    • List of target points (x, y) for the arrow heads.

  • labels (list[str] | str) –

    • List of text labels at the arrow tails.

    • If str, the same label is used for all points.

  • text_offset (tuple[float, float] | list[tuple[float, float]]) –

    • Offset(s) (dx, dy) for label positions from arrow tails.

    • If single tuple, same offset is applied to all.

  • c (str | list[str]) –

    • Color(s) for arrow and text.

    • If str, same color is applied to all.

  • fontsize (int | list[int]) –

    • Font size(s) of the label text.

    • If int, same size is applied to all.

  • ax (int | None) –

    • Which specific axis to plot (1, 2, 3, …).

    • If None, uses the current row.

Return type:

None

add_legend(ypos=1.0)[source]

Add legend to the figure.

Parameters:

ypos (float) –

  • y position from the top.

  • > 1 to push it higher, < 1 to push it lower

  • Default: 1.3

Return type:

None

add_title(title=None, s=13)[source]

Add title to the figure.

Parameters:

  • title (str | None) –

    • Title of the figure.

    • Default: None

  • s (Number) –

    • Font size.

    • Default: None

add_xlabel(xlabel=None, s=None)[source]

Add shared x-label to the figure.

Parameters:

  • xlabel (str | None) –

    • xlabel for the figure.

    • Default: None

  • s (Number) –

    • Font size.

    • Default: None

add_xticks(xticks=None)[source]

Not implemented yet

save(path='./figure.png')[source]

Save the figure.

Parameters:

path (str) –

  • Path to the output file.

Return type:

None

modusa.plot_dist(*args, ann=None, xlim=None, ylim=None, ylabel=None, xlabel=None, title=None, legend=None, show_hist=True, npoints=200, bins=30)[source]

Plot distribution.

import modusa as ms
import numpy as np
np.random.seed(42)
data = np.random.normal(loc=1, scale=1, size=1000)
ms.plot_dist(data, data+5, data-10, ann=[(0, 1, "A")], legend=("D1", "D2", "D3"), ylim=(0, 1), xlabel="X", ylabel="Counts", title="Distribution")
Parameters:

  • *args (ndarray) –

    • Data arrays for which distribution needs to be plotted.

    • Arrays will be flattened.

  • ann (list[tuple[Number, Number, str] | None) –

    • A list of annotations to mark specific points. Each tuple should be of the form (start, end, label).

    • Default: None => No annotation.

  • events (list[Number] | None) –

    • A list of x-values where vertical lines (event markers) will be drawn.

    • Default: None

  • xlim (tuple[Number, Number] | None) –

    • Limits for the x-axis as (xmin, xmax).

    • Default: None

  • ylim (tuple[Number, Number] | None) –

    • Limits for the y-axis as (ymin, ymax).

    • Default: None

  • xlabel (str | None) –

    • Label for the x-axis.

      • Default: None

  • ylabel (str | None) –

    • Label for the y-axis.

    • Default: None

  • title (str | None) –

    • Title of the plot.

    • Default: None

  • legend (list[str] | None) –

    • List of legend labels corresponding to each signal if plotting multiple distributions.

    • Default: None

  • show_hist (bool) –

    • Want to show histogram as well.

  • npoints (int) –

    • Number of points for which gaussian needs to be computed between min and max.

    • Higher value means more points are evaluated with the fitted gaussian, thereby higher resolution.

  • bins (int) –

    • The number of bins for histogram.

    • This is used only to plot the histogram.

Returns:

  • Matplotlib figure.

Return type:

plt.Figure