inertialsim.plot ¶

Plotting and data visualization.

The plot module is optional and requires two additional dependencies:

Classes:

Name	Description
`Scatter`	Plot 2-dimensional data.
`TimeSeries`	Plot time series data.
`MapOverlay`	Plot position data overlaid on Google Maps.

Attributes:

Name	Type	Description
`GOOGLE_MAPS_API_KEY`	`str \| None`	Google Maps API key.

GOOGLE_MAPS_API_KEY `module-attribute` ¶

GOOGLE_MAPS_API_KEY: str | None = get("GOOGLE_MAPS_API_KEY")

Google Maps API key.

The MapOverlay class requires a Google Maps API key. It will attempt to load it from an environment variable of this name. If none is found, it can be set directly.

FIGURE_DPI `module-attribute` ¶

FIGURE_DPI = 100

FIGURE_SIZE `module-attribute` ¶

FIGURE_SIZE = (6.4, 4.8)

Scatter ¶

Scatter(
    *,
    title: str,
    xlabel: str,
    ylabel: str,
    axis_lines: bool = False,
)

Bases: _MatplotlibBase

Plot 2-dimensional data.

Each instance stores a matplotlib axes object. Methods mimic the methods of matplotlib and add plots to the class axes. Formatting and array size and shape conventions are handled automatically.

See matplotlib.pyplot.figure

Parameters:

Name	Type	Description	Default
`title`	`str`	The plot title.	required
`xlabel`	`str`	The x-axis label.	required
`ylabel`	`str`	The y-axis label.	required
`axis_lines`	`bool`	Display the x and y axes as lines.	`False`

Methods:

Name	Description
`scatter`	Add a scatter plot to the class axes.
`legend`	Add a legend to a plot.
`axis_arrows`	Draw axis arrows.
`line`	Add a line graph to the class axes.
`zoom_inset`	Add a zoomed inset plot.

Attributes:

Name	Type	Description
`figure`
`axes`
`handles`	`list`

figure `instance-attribute` ¶

figure = figure(figsize=FIGURE_SIZE, dpi=FIGURE_DPI)

axes `instance-attribute` ¶

axes = gca()

handles `instance-attribute` ¶

handles: list = []

scatter ¶

scatter(
    x: ArrayLike,
    y: ArrayLike,
    *,
    marker: str = "o",
    color: str | None = None,
    xlimits: tuple[float, float] | None = None,
    ylimits: tuple[float, float] | None = None,
    aspect_equal: bool = True,
    **kwargs: Any,
) -> None

Add a scatter plot to the class axes.

Parameters:

Name	Type	Description	Default
`x`	`ArrayLike`	Array of x-axis data with `shape in ((N,), (N,1), (N,1,1))`.	required
`y`	`ArrayLike`	Array of y-axis data with `shape in ((N,), (N,1), (N,1,1))`.	required
`marker`	`str`	Marker symbol for each plot point.	`'o'`
`color`	`str \| None`	Marker color for each plot point.	`None`
`xlimits`	`tuple[float, float] \| None`	Set x-axis limits.	`None`
`ylimits`	`tuple[float, float] \| None`	Set y-axis limits.	`None`
`aspect_equal`	`bool`	Set aspect ratio equal. Use False if axes have different units of measurement.	`True`
`**kwargs`	`Any`	Other arguments passed through to plot.	`{}`

legend ¶

legend(legend: list[str], loc: str = 'best') -> None

Add a legend to a plot.

axis_arrows ¶

axis_arrows(
    x: float = 0.0,
    y: float = 0.0,
    scale: float = 1.5,
    alpha: float = 1.0,
    angle: float = 0.0,
) -> None

Draw axis arrows.

Draw arrows on the x-axis and y-axis. The x-axis will be red, the y-axis will be green (following the convention of using RGB for xyz).

Parameters:

Name	Type	Description	Default
`x`	`float`	x-axis origin of arrow.	`0.0`
`y`	`float`	y-axis origin of arrow.	`0.0`
`scale`	`float`	Length of arrow.	`1.5`
`alpha`	`float`	Arrow alpha (transparency).	`1.0`
`angle`	`float`	Rotation anti-clockwise from x-axis (radians).	`0.0`

line ¶

line(
    x: ArrayLike,
    y: ArrayLike,
    *,
    marker: str = "",
    color: str | None = None,
    xlimits: tuple[float, float] | None = None,
    ylimits: tuple[float, float] | None = None,
    aspect_equal: bool = False,
    **kwargs: Any,
) -> None

Add a line graph to the class axes.

Parameters:

Name	Type	Description	Default
`x`	`ArrayLike`	Array of x-axis data with `shape in ((N,), (N,1), (N,1,1))`.	required
`y`	`ArrayLike`	Array of y-axis data with `shape in ((N,), (N,1), (N,1,1))`.	required
`marker`	`str`	Marker symbol for each plot point.	`''`
`color`	`str \| None`	Marker color for each plot point.	`None`
`xlimits`	`tuple[float, float] \| None`	Set x-axis limits.	`None`
`ylimits`	`tuple[float, float] \| None`	Set y-axis limits.	`None`
`aspect_equal`	`bool`	Set aspect ratio equal. Use False if axes have different units of measurement.	`False`
`**kwargs`	`Any`	Other arguments passed through to plot.	`{}`

zoom_inset ¶

zoom_inset(
    bounds: tuple[float, float, float, float],
    xlimits: tuple[float, float],
    ylimits: tuple[float, float],
    **kwargs: Any,
) -> None

Add a zoomed inset plot.

Adds an inset plot with a zoomed view of any line elements previously added to the plot. Only lines visible inside the x and y limits will be visible.

Parameters:

Name	Type	Description	Default
`bounds`	`tuple[float, float, float, float]`	Lower-left corner of inset axes, and its width and height, both as fractions of the existing axis range.	required
`xlimits`	`tuple[float, float]`	x-axis limits of the zoom area.	required
`ylimits`	`tuple[float, float]`	y-axis limits of the zoom area.	required
`**kwargs`	`Any`	Other arguments passed through to inset_axes.	`{}`

TimeSeries ¶

TimeSeries(
    *,
    title: str,
    xlabel: str = "Time (s)",
    ylabel: str,
    axis_lines: bool = False,
)

Bases: _MatplotlibBase

Plot time series data.

Each instance stores a matplotlib axes object. Methods mimic the methods of matplotlib and add plots to the class axes. Formatting and array size and shape conventions are handled automatically.

Parameters:

Name	Type	Description	Default
`title`	`str`	The plot title.	required
`xlabel`	`str`	The x-axis label.	`'Time (s)'`
`ylabel`	`str`	The y-axis label.	required
`axis_lines`	`bool`	Display the x and y axes as lines.	`False`

Methods:

Name	Description
`semilogx`	Add a line graph to the class axes with x-axis log scale.
`semilogy`	Add a line graph to the class axes with y-axis log scale.
`loglog`	Add a line graph to the class axes with log scale on both axes.
`legend`	Add a legend to a plot.
`axis_arrows`	Draw axis arrows.
`line`	Add a line graph to the class axes.
`zoom_inset`	Add a zoomed inset plot.

Attributes:

Name	Type	Description
`figure`
`axes`
`handles`	`list`

figure `instance-attribute` ¶

figure = figure(figsize=FIGURE_SIZE, dpi=FIGURE_DPI)

axes `instance-attribute` ¶

axes = gca()

handles `instance-attribute` ¶

handles: list = []

semilogx ¶

semilogx(
    time: ArrayLike,
    y: ArrayLike,
    *,
    marker: str = "",
    color: str | None = None,
    xlimits: tuple[float, float] | None = None,
    ylimits: tuple[float, float] | None = None,
    **kwargs: Any,
) -> None

Add a line graph to the class axes with x-axis log scale.

Parameters:

Name	Type	Description	Default
`time`	`ArrayLike`	Array of time data with `shape in ((N,), (N,1), (N,1,1))`.	required
`y`	`ArrayLike`	Array of y-axis data with `shape in ((N,), (N,M), (N,M,1))`.	required
`marker`	`str`	Marker symbol for each plot point.	`''`
`color`	`str \| None`	Marker color for each plot point.	`None`
`xlimits`	`tuple[float, float] \| None`	Set x-axis limits.	`None`
`ylimits`	`tuple[float, float] \| None`	Set y-axis limits.	`None`
`**kwargs`	`Any`	Other arguments passed through to plot.	`{}`

semilogy ¶

semilogy(
    time: ArrayLike,
    y: ArrayLike,
    *,
    marker: str = "",
    color: str | None = None,
    xlimits: tuple[float, float] | None = None,
    ylimits: tuple[float, float] | None = None,
    **kwargs: Any,
) -> None

Add a line graph to the class axes with y-axis log scale.

Parameters:

Name	Type	Description	Default
`time`	`ArrayLike`	Array of time data with `shape in ((N,), (N,1), (N,1,1))`.	required
`y`	`ArrayLike`	Array of y-axis data with `shape in ((N,), (N,M), (N,M,1))`.	required
`marker`	`str`	Marker symbol for each plot point.	`''`
`color`	`str \| None`	Marker color for each plot point.	`None`
`xlimits`	`tuple[float, float] \| None`	Set x-axis limits.	`None`
`ylimits`	`tuple[float, float] \| None`	Set y-axis limits.	`None`
`**kwargs`	`Any`	Other arguments passed through to plot.	`{}`

loglog ¶

loglog(
    time: ArrayLike,
    y: ArrayLike,
    *,
    marker: str = "",
    color: str | None = None,
    xlimits: tuple[float, float] | None = None,
    ylimits: tuple[float, float] | None = None,
    **kwargs: Any,
) -> None

Add a line graph to the class axes with log scale on both axes.

Parameters:

Name	Type	Description	Default
`time`	`ArrayLike`	Array of time data with `shape in ((N,), (N,1), (N,1,1))`.	required
`y`	`ArrayLike`	Array of y-axis data with `shape in ((N,), (N,M), (N,M,1))`.	required
`marker`	`str`	Marker symbol for each plot point.	`''`
`color`	`str \| None`	Marker color for each plot point.	`None`
`xlimits`	`tuple[float, float] \| None`	Set x-axis limits.	`None`
`ylimits`	`tuple[float, float] \| None`	Set y-axis limits.	`None`
`**kwargs`	`Any`	Other arguments passed through to plot.	`{}`

legend ¶

legend(legend: list[str], loc: str = 'best') -> None

Add a legend to a plot.

axis_arrows ¶

axis_arrows(
    x: float = 0.0,
    y: float = 0.0,
    scale: float = 1.5,
    alpha: float = 1.0,
    angle: float = 0.0,
) -> None

Draw axis arrows.

Draw arrows on the x-axis and y-axis. The x-axis will be red, the y-axis will be green (following the convention of using RGB for xyz).

Parameters:

Name	Type	Description	Default
`x`	`float`	x-axis origin of arrow.	`0.0`
`y`	`float`	y-axis origin of arrow.	`0.0`
`scale`	`float`	Length of arrow.	`1.5`
`alpha`	`float`	Arrow alpha (transparency).	`1.0`
`angle`	`float`	Rotation anti-clockwise from x-axis (radians).	`0.0`

line ¶

line(
    x: ArrayLike,
    y: ArrayLike,
    *,
    marker: str = "",
    color: str | None = None,
    xlimits: tuple[float, float] | None = None,
    ylimits: tuple[float, float] | None = None,
    aspect_equal: bool = False,
    **kwargs: Any,
) -> None

Add a line graph to the class axes.

Parameters:

Name	Type	Description	Default
`x`	`ArrayLike`	Array of x-axis data with `shape in ((N,), (N,1), (N,1,1))`.	required
`y`	`ArrayLike`	Array of y-axis data with `shape in ((N,), (N,1), (N,1,1))`.	required
`marker`	`str`	Marker symbol for each plot point.	`''`
`color`	`str \| None`	Marker color for each plot point.	`None`
`xlimits`	`tuple[float, float] \| None`	Set x-axis limits.	`None`
`ylimits`	`tuple[float, float] \| None`	Set y-axis limits.	`None`
`aspect_equal`	`bool`	Set aspect ratio equal. Use False if axes have different units of measurement.	`False`
`**kwargs`	`Any`	Other arguments passed through to plot.	`{}`

zoom_inset ¶

zoom_inset(
    bounds: tuple[float, float, float, float],
    xlimits: tuple[float, float],
    ylimits: tuple[float, float],
    **kwargs: Any,
) -> None

Add a zoomed inset plot.

Adds an inset plot with a zoomed view of any line elements previously added to the plot. Only lines visible inside the x and y limits will be visible.

Parameters:

Name	Type	Description	Default
`bounds`	`tuple[float, float, float, float]`	Lower-left corner of inset axes, and its width and height, both as fractions of the existing axis range.	required
`xlimits`	`tuple[float, float]`	x-axis limits of the zoom area.	required
`ylimits`	`tuple[float, float]`	y-axis limits of the zoom area.	required
`**kwargs`	`Any`	Other arguments passed through to inset_axes.	`{}`

MapOverlay ¶

MapOverlay(
    title: str,
    map_type: Literal[
        "satellite", "roadmap", "terrain", "hybrid"
    ] = "roadmap",
    zoom: int = 17,
)

Plot position data overlaid on Google Maps.

Each instance stores a bokeh gmap object. Methods mimic the methods of bokeh and add plots to the class map. Formatting and array size and shape conventions are handled automatically.

See bokeh.models.GMapOptions for more detail on the map_type and zoom arguments.

Parameters:

Name	Type	Description	Default
`title`	`str`	The plot title.	required
`map_type`	`Literal['satellite', 'roadmap', 'terrain', 'hybrid']`	Google Maps map type. One of "hybrid", "roadmap", "satellite", or "terrain".	`'roadmap'`
`zoom`	`int`	Google Maps zoom level. Defaults to 17 which is approximately city block scale.	`17`

Methods:

Name	Description
`line`	Add continuous line segments to a Google Map plot.
`show`	Render all prior inputs on the map.

Attributes:

Name	Type	Description
`map_options`
`map`

map_options `instance-attribute` ¶

map_options = GMapOptions(
    map_type=map_type, zoom=zoom, scale_control=True
)

map `instance-attribute` ¶

map = gmap(
    GOOGLE_MAPS_API_KEY,
    map_options,
    title=title,
    x_axis_label="Longitude (deg.)",
    y_axis_label="Latitude (deg.)",
    background_fill_alpha=0.4,
)

line ¶

line(
    latitude: ArrayLike,
    longitude: ArrayLike,
    width: int = 5,
    color: str = "blue",
    **kwargs: Any,
) -> None

Add continuous line segments to a Google Map plot.

Because of the way bokeh works, a subsequent call to show() must be made in order to render the input of this function (and all previous calls to it).

Parameters:

Name	Type	Description	Default
`latitude`	`ArrayLike`	Latitude (radians).	required
`longitude`	`ArrayLike`	Longitude (radians).	required
`width`	`int`	Line width.	`5`
`color`	`str`	Line color.	`'blue'`
`**kwargs`	`Any`	Other arguments passed through to line.	`{}`

show ¶

show() -> None

Render all prior inputs on the map.

inertialsim.plot ¶

GOOGLE_MAPS_API_KEY module-attribute ¶

FIGURE_DPI module-attribute ¶

FIGURE_SIZE module-attribute ¶

Scatter ¶

figure instance-attribute ¶

axes instance-attribute ¶

handles instance-attribute ¶

scatter ¶

legend ¶

axis_arrows ¶

line ¶

zoom_inset ¶

TimeSeries ¶

figure instance-attribute ¶

axes instance-attribute ¶

handles instance-attribute ¶

semilogx ¶

semilogy ¶

loglog ¶

legend ¶

axis_arrows ¶

line ¶

zoom_inset ¶

MapOverlay ¶

map_options instance-attribute ¶

map instance-attribute ¶

line ¶

show ¶

GOOGLE_MAPS_API_KEY `module-attribute` ¶

FIGURE_DPI `module-attribute` ¶

FIGURE_SIZE `module-attribute` ¶

figure `instance-attribute` ¶

axes `instance-attribute` ¶

handles `instance-attribute` ¶

figure `instance-attribute` ¶

axes `instance-attribute` ¶

handles `instance-attribute` ¶

map_options `instance-attribute` ¶

map `instance-attribute` ¶