Plotting Reference

Plotting functions (bokeh)

Plotting functions for the underwater acoustic propagation modeling toolbox.

class bellhop.plot.Any(*args, **kwargs)[source]

Special type indicating an unconstrained type.

  • Any is compatible with every type.

  • Any assumed to have all methods.

  • All values assumed to be instances of Any.

Note that all the above statements are true from the point of view of static type checkers. At runtime, Any should not be used with instance checks.

class bellhop.plot.Environment(name: str = 'bellhop/python default', type: str = '2D', frequency: float = 25000.0, _num_media: int = 1, soundspeed: float | Any = 1500.0, soundspeed_interp: str = _Strings.linear, depth: float | Any = 25.0, depth_interp: str = _Strings.linear, _mesh_npts: int = 0, _depth_sigma: float = 0.0, depth_max: float | None = None, _bathymetry: str = _Strings.flat, _altimetry: str = _Strings.flat, _sbp_file: str = _Strings.default, bottom_interp: str | None = None, bottom_soundspeed: float = 1600.0, _bottom_soundspeed_shear: float = 0.0, bottom_density: float = 1600, bottom_attenuation: float | None = None, _bottom_attenuation_shear: float | None = None, bottom_roughness: float = 0.0, bottom_beta: float | None = None, bottom_transition_freq: float | None = None, bottom_boundary_condition: str = _Strings.acousto_elastic, bottom_reflection_coefficient: Any | None = None, surface: Any | None = None, surface_interp: str = _Strings.linear, surface_boundary_condition: str = _Strings.vacuum, surface_reflection_coefficient: Any | None = None, surface_depth: float = 0.0, surface_soundspeed: float = 1600.0, _surface_soundspeed_shear: float = 0.0, surface_density: float = 1000.0, surface_attenuation: float | None = None, _surface_attenuation_shear: float | None = None, source_type: str = 'default', source_depth: float | Any = 5.0, source_ndepth: int | None = None, source_directionality: Any | None = None, receiver_depth: float | Any = 10.0, receiver_range: float | Any = 1000.0, receiver_ndepth: int | None = None, receiver_nrange: int | None = None, beam_type: str = _Strings.default, beam_angle_min: float | None = None, beam_angle_max: float | None = None, beam_num: int = 0, single_beam_index: int | None = None, _single_beam: str = _Strings.default, step_size: float | None = 0.0, box_depth: float | None = None, box_range: float | None = None, grid_type: str = 'default', task: str | None = None, interference_mode: str | None = None, volume_attenuation: str = 'none', attenuation_units: str = 'frequency dependent', fg_salinity: float | None = None, fg_temperature: float | None = None, fg_pH: float | None = None, fg_depth: float | None = None)[source]

Dataclass for underwater acoustic environment configuration.

This class provides automatic validation of environment parameters, eliminating the need for manual checking of option validity.

These entries are either intended to be set or edited by the user, or with _ prefix are internal state read from a .env file or inferred by other data. Some others are ignored.

attenuation_units: str = 'frequency dependent'
beam_angle_max: float | None = None
beam_angle_min: float | None = None
beam_num: int = 0
beam_type: str = 'default'
bottom_attenuation: float | None = None
bottom_beta: float | None = None
bottom_boundary_condition: str = 'acousto-elastic'
bottom_density: float = 1600
bottom_interp: str | None = None
bottom_reflection_coefficient: Any | None = None
bottom_roughness: float = 0.0
bottom_soundspeed: float = 1600.0
bottom_transition_freq: float | None = None
box_depth: float | None = None
box_range: float | None = None
check() → Environment[source]
copy() → Environment[source]

Return a shallow copy of the environment.

depth: float | Any = 25.0
depth_interp: str = 'linear'
depth_max: float | None = None
fg_depth: float | None = None
fg_pH: float | None = None
fg_salinity: float | None = None
fg_temperature: float | None = None
frequency: float = 25000.0
grid_type: str = 'default'
interference_mode: str | None = None
name: str = 'bellhop/python default'
receiver_depth: float | Any = 10.0
receiver_ndepth: int | None = None
receiver_nrange: int | None = None
receiver_range: float | Any = 1000.0
single_beam_index: int | None = None
soundspeed: float | Any = 1500.0
soundspeed_interp: str = 'linear'
source_depth: float | Any = 5.0
source_directionality: Any | None = None
source_ndepth: int | None = None
source_type: str = 'default'
step_size: float | None = 0.0
surface: Any | None = None
surface_attenuation: float | None = None
surface_boundary_condition: str = 'vacuum'
surface_density: float = 1000.0
surface_depth: float = 0.0
surface_interp: str = 'linear'
surface_reflection_coefficient: Any | None = None
surface_soundspeed: float = 1600.0
task: str | None = None
to_dict() → Dict[str, Any][source]

Return a dictionary representation of the environment.

type: str = '2D'
volume_attenuation: str = 'none'
class bellhop.plot.figure(title=None, xlabel=None, ylabel=None, xlim=None, ylim=None, xtype='auto', ytype='auto', width=None, height=None, interactive=None)[source]

Create a new figure, and optionally automatically display it.

Parameters:

  • title (str, optional) – Figure title

  • xlabel (str, optional) – X-axis label

  • ylabel (str, optional) – Y-axis label

  • xlim (tuple of float, optional) – X-axis limits (min, max)

  • ylim (tuple of float, optional) – Y-axis limits (min, max)

  • xtype (str, default='auto') – X-axis type (‘auto’, ‘linear’, ‘log’, etc)

  • ytype (str, default='auto') – Y-axis type (‘auto’, ‘linear’, ‘log’, etc)

  • width (int, optional) – Figure width in pixels

  • height (int, optional) – Figure height in pixels

  • interactive (bool, optional) – Enable interactive tools (pan, zoom, etc) for plot

Notes

This function can be used in standalone mode to create a figure:

>>> import arlpy.plot
>>> arlpy.plot.figure(title='Demo 1', width=500)
>>> arlpy.plot.plot([0,10], [0,10])

Or it can be used as a context manager to create, hold and display a figure:

>>> import arlpy.plot
>>> with arlpy.plot.figure(title='Demo 2', width=500):
>>>     arlpy.plot.plot([0,10], [0,10], color='blue', legend='A')
>>>     arlpy.plot.plot([10,0], [0,10], marker='o', color='green', legend='B')

It can even be used as a context manager to work with Bokeh functions directly:

>>> import arlpy.plot
>>> with arlpy.plot.figure(title='Demo 3', width=500) as f:
>>>     f.line([0,10], [0,10], line_color='blue')
>>>     f.square([3,7], [4,5], line_color='green', fill_color='yellow', size=10)
bellhop.plot.plot_env(env: Environment, surface_color: str = 'dodgerblue', bottom_color: str = 'peru', source_color: str = 'orangered', receiver_color: str = 'midnightblue', receiver_plot: bool | None = None, **kwargs: Any) → None[source]

Plots a visual representation of the environment.

Parameters:

  • env (dict) – Environment description

  • surface_color (str, default='dodgerblue') – Color of the surface (see Bokeh colors)

  • bottom_color (str, default='peru') –

    Color of the bottom (see Bokeh colors)

  • source_color (str, default='orangered') –

    Color of transmitters (see Bokeh colors)

  • receiver_color (str, default='midnightblue') –

    Color of receivers (see Bokeh colors)

  • receiver_plot (bool, optional) – True to plot all receivers, False to not plot any receivers, None to automatically decide

  • **kwargs – Other keyword arguments applicable for bellhop.plot.plot() are also supported

Notes

The surface, bottom, transmitters (marker: ‘*’) and receivers (marker: ‘o’) are plotted in the environment. If receiver_plot is set to None and there are more than 2000 receivers, they are not plotted.

Examples

>>> import bellhop as bh
>>> env = bh.create_env(depth=[[0, 40], [100, 30], [500, 35], [700, 20], [1000,45]])
>>> bh.plot_env(env)
bellhop.plot.plot_ssp(env: Environment, **kwargs: Any) → None[source]

Plots the sound speed profile.

Parameters:

  • env (dict) – Environment description

  • **kwargs – Other keyword arguments applicable for bellhop.plot.plot() are also supported

Notes

If the sound speed profile is range-dependent, this function only plots the first profile.

Examples

>>> import bellhop as bh
>>> env = bh.create_env(soundspeed=[[ 0, 1540], [10, 1530], [20, 1532], [25, 1533], [30, 1535]])
>>> bh.plot_ssp(env)
bellhop.plot.plot_arrivals(arrivals: Any, dB: bool = False, color: str = 'blue', **kwargs: Any) → None[source]

Plots the arrival times and amplitudes.

Parameters:

  • arrivals (pandas.DataFrame) – Arrivals times (s) and coefficients

  • dB (bool, default=False) – True to plot in dB, False for linear scale

  • color (str, default='blue') –

    Line color (see Bokeh colors)

  • **kwargs – Other keyword arguments applicable for bellhop.plot.plot() are also supported

Examples

>>> import bellhop as bh
>>> env = bh.create_env()
>>> arrivals = bh.compute_arrivals(env)
>>> bh.plot_arrivals(arrivals)
bellhop.plot.plot_rays(rays: Any, env: Environment | None = None, invert_colors: bool = False, **kwargs: Any) → None[source]

Plots ray paths.

Parameters:

  • rays (pandas.DataFrame) – Ray paths

  • env (dict, optional) – Environment definition

  • invert_colors (bool, default=False) – False to use black for high intensity rays, True to use white

  • **kwargs – Other keyword arguments applicable for bellhop.plot.plot() are also supported

Notes

If environment definition is provided, it is overlayed over this plot using default parameters for bellhop.plot_env().

Examples

>>> import bellhop as bh
>>> env = bh.create_env()
>>> rays = bh.compute_eigenrays(env)
>>> bh.plot_rays(rays, width=1000)
bellhop.plot.plot_transmission_loss(tloss: Any, env: Environment | None = None, **kwargs: Any) → None[source]

Plots transmission loss.

Parameters:

  • tloss (pandas.DataFrame) – Complex transmission loss

  • env (dict, optional) – Environment definition

  • **kwargs – Other keyword arguments applicable for bellhop.plot.image() are also supported

Notes

If environment definition is provided, it is overlayed over this plot using default parameters for bellhop.plot_env().

Examples

>>> import bellhop as bh
>>> import numpy as np
>>> env = bh.create_env(
        receiver_depth=np.arange(0, 25),
        receiver_range=np.arange(0, 1000),
        beam_angle_min=-45,
        beam_angle_max=45
    )
>>> tloss = bh.compute_transmission_loss(env)
>>> bh.plot_transmission_loss(tloss, width=1000)

Plotting utilities (bokeh)

Easy-to-use plotting utilities based on Bokeh.

bellhop.plotutils.theme(name: str) → None[source]

Set color theme.

Parameters:

name (str) – Name of theme

Examples

>>> import arlpy.plot
>>> arlpy.plot.theme('dark')
bellhop.plotutils.figsize(x: int, y: int) → None[source]

Set the default figure size in pixels.

Parameters:

  • x (int) – Figure width

  • y (int) – Figure height

bellhop.plotutils.interactive(b: bool) → None[source]

Set default interactivity for plots.

Parameters:

b (bool) – True to enable interactivity, False to disable it

bellhop.plotutils.enable_javascript(b: bool) → None[source]

Enable/disable Javascript.

Parameters:

b (bool) – True to use Javascript, False to avoid use of Javascript

Notes

Jupyterlab does not support Javascript output. To avoid error messages, Javascript can be disabled using this call. This removes an optimization to replace non-interactive plots with static images, but other than that does not affect functionality.

bellhop.plotutils.use_static_images(b: bool = True) → None[source]

Use static images instead of dynamic HTML/Javascript in Jupyter notebook.

Parameters:

b (bool, default=True) – True to use static images, False to use HTML/Javascript

Notes

Static images are useful when the notebook is to be exported as a markdown, LaTeX or PDF document, since dynamic HTML/Javascript is not rendered in these formats. When static images are used, all interactive functionality is disabled.

To use static images, you must have the following packages installed: selenium, pillow, phantomjs.

bellhop.plotutils.hold(enable: bool = True) → bool | None[source]

Combine multiple plots into one.

Parameters:

enable (bool, default=True) – True to hold plot, False to release hold

Returns:

Old state of hold if enable is True

Return type:

bool or None

Examples

>>> import arlpy.plot
>>> oh = arlpy.plot.hold()
>>> arlpy.plot.plot([0,10], [0,10], color='blue', legend='A')
>>> arlpy.plot.plot([10,0], [0,10], marker='o', color='green', legend='B')
>>> arlpy.plot.hold(oh)
class bellhop.plotutils.figure(title=None, xlabel=None, ylabel=None, xlim=None, ylim=None, xtype='auto', ytype='auto', width=None, height=None, interactive=None)[source]

Create a new figure, and optionally automatically display it.

Parameters:

  • title (str, optional) – Figure title

  • xlabel (str, optional) – X-axis label

  • ylabel (str, optional) – Y-axis label

  • xlim (tuple of float, optional) – X-axis limits (min, max)

  • ylim (tuple of float, optional) – Y-axis limits (min, max)

  • xtype (str, default='auto') – X-axis type (‘auto’, ‘linear’, ‘log’, etc)

  • ytype (str, default='auto') – Y-axis type (‘auto’, ‘linear’, ‘log’, etc)

  • width (int, optional) – Figure width in pixels

  • height (int, optional) – Figure height in pixels

  • interactive (bool, optional) – Enable interactive tools (pan, zoom, etc) for plot

Notes

This function can be used in standalone mode to create a figure:

>>> import arlpy.plot
>>> arlpy.plot.figure(title='Demo 1', width=500)
>>> arlpy.plot.plot([0,10], [0,10])

Or it can be used as a context manager to create, hold and display a figure:

>>> import arlpy.plot
>>> with arlpy.plot.figure(title='Demo 2', width=500):
>>>     arlpy.plot.plot([0,10], [0,10], color='blue', legend='A')
>>>     arlpy.plot.plot([10,0], [0,10], marker='o', color='green', legend='B')

It can even be used as a context manager to work with Bokeh functions directly:

>>> import arlpy.plot
>>> with arlpy.plot.figure(title='Demo 3', width=500) as f:
>>>     f.line([0,10], [0,10], line_color='blue')
>>>     f.square([3,7], [4,5], line_color='green', fill_color='yellow', size=10)
class bellhop.plotutils.many_figures(figsize: Tuple[int, int] | None = None)[source]

Create a grid of many figures.

Parameters:

figsize (tuple of int, optional) – Default size of figure in grid as (width, height)

Examples

>>> import arlpy.plot
>>> with arlpy.plot.many_figures(figsize=(300,200)):
>>>     arlpy.plot.plot([0,10], [0,10])
>>>     arlpy.plot.plot([0,10], [0,10])
>>>     arlpy.plot.next_row()
>>>     arlpy.plot.next_column()
>>>     arlpy.plot.plot([0,10], [0,10])
bellhop.plotutils.next_row() → None[source]

Move to the next row in a grid of many figures.

bellhop.plotutils.next_column() → None[source]

Move to the next column in a grid of many figures.

bellhop.plotutils.gcf() → Any[source]

Get the current figure.

Returns:

handle to the current figure

bellhop.plotutils.plot(x: Any, y: Any = None, fs: float | None = None, maxpts: int = 10000, pooling: str | None = None, color: str | None = None, style: str = 'solid', thickness: int = 1, marker: str | None = None, filled: bool = False, size: int = 6, mskip: int = 0, title: str | None = None, xlabel: str | None = None, ylabel: str | None = None, xlim: Tuple[float, float] | None = None, ylim: Tuple[float, float] | None = None, xtype: str = 'auto', ytype: str = 'auto', width: int | None = None, height: int | None = None, legend: str | None = None, interactive: bool | None = None, hold: bool = False) → None[source]

Plot a line graph or time series.

Parameters:

  • x – x data or time series data (if y is None)

  • y – y data or None (if time series)

  • fs – sampling rate for time series data

  • maxpts – maximum number of points to plot (downsampled if more points provided)

  • pooling – pooling for downsampling (None, ‘max’, ‘min’, ‘mean’, ‘median’)

  • color –

    line color (see Bokeh colors)

  • style – line style (‘solid’, ‘dashed’, ‘dotted’, ‘dotdash’, ‘dashdot’, None)

  • thickness – line width in pixels

  • marker – point markers (‘.’, ‘o’, ‘s’, ‘*’, ‘x’, ‘+’, ‘d’, ‘^’)

  • filled – filled markers or outlined ones

  • size – marker size

  • mskip – number of points to skip marking (to avoid too many markers)

  • title – figure title

  • xlabel – x-axis label

  • ylabel – y-axis label

  • xlim – x-axis limits (min, max)

  • ylim – y-axis limits (min, max)

  • xtype – x-axis type (‘auto’, ‘linear’, ‘log’, etc)

  • ytype – y-axis type (‘auto’, ‘linear’, ‘log’, etc)

  • width – figure width in pixels

  • height – figure height in pixels

  • legend – legend text

  • interactive – enable interactive tools (pan, zoom, etc) for plot

  • hold – if set to True, output is not plotted immediately, but combined with the next plot

>>> import arlpy.plot
>>> import numpy as np
>>> arlpy.plot.plot([0,10], [1,-1], color='blue', marker='o', filled=True, legend='A', hold=True)
>>> arlpy.plot.plot(np.random.normal(size=1000), fs=100, color='green', legend='B')
bellhop.plotutils.scatter(x: Any, y: Any, marker: str = '.', filled: bool = False, size: int = 6, color: str | None = None, title: str | None = None, xlabel: str | None = None, ylabel: str | None = None, xlim: Tuple[float, float] | None = None, ylim: Tuple[float, float] | None = None, xtype: str = 'auto', ytype: str = 'auto', width: int | None = None, height: int | None = None, legend: str | None = None, hold: bool = False, interactive: bool | None = None) → None[source]

Plot a scatter plot.

Parameters:

  • x – x data

  • y – y data

  • color – marker color (see Bokeh colors)

  • marker – point markers (‘.’, ‘o’, ‘s’, ‘*’, ‘x’, ‘+’, ‘d’, ‘^’)

  • filled – filled markers or outlined ones

  • size – marker size

  • title – figure title

  • xlabel – x-axis label

  • ylabel – y-axis label

  • xlim – x-axis limits (min, max)

  • ylim – y-axis limits (min, max)

  • xtype – x-axis type (‘auto’, ‘linear’, ‘log’, etc)

  • ytype – y-axis type (‘auto’, ‘linear’, ‘log’, etc)

  • width – figure width in pixels

  • height – figure height in pixels

  • legend – legend text

  • interactive – enable interactive tools (pan, zoom, etc) for plot

  • hold – if set to True, output is not plotted immediately, but combined with the next plot

>>> import arlpy.plot
>>> import numpy as np
>>> arlpy.plot.scatter(np.random.normal(size=100), np.random.normal(size=100), color='blue', marker='o')
bellhop.plotutils.image(img: Any, x: Any | None = None, y: Any | None = None, colormap: str = 'Plasma256', clim: Tuple[float, float] | None = None, clabel: str | None = None, title: str | None = None, xlabel: str | None = None, ylabel: str | None = None, xlim: Tuple[float, float] | None = None, ylim: Tuple[float, float] | None = None, xtype: str = 'auto', ytype: str = 'auto', width: int | None = None, height: int | None = None, hold: bool = False, interactive: bool | None = None) → None[source]

Plot a heatmap of 2D scalar data.

Parameters:

  • img – 2D image data

  • x – x-axis range for image data (min, max)

  • y – y-axis range for image data (min, max)

  • colormap – named color palette or Bokeh ColorMapper (see Bokeh palettes)

  • clim – color axis limits (min, max)

  • clabel – color axis label

  • title – figure title

  • xlabel – x-axis label

  • ylabel – y-axis label

  • xlim – x-axis limits (min, max)

  • ylim – y-axis limits (min, max)

  • xtype – x-axis type (‘auto’, ‘linear’, ‘log’, etc)

  • ytype – y-axis type (‘auto’, ‘linear’, ‘log’, etc)

  • width – figure width in pixels

  • height – figure height in pixels

  • interactive – enable interactive tools (pan, zoom, etc) for plot

  • hold – if set to True, output is not plotted immediately, but combined with the next plot

>>> import arlpy.plot
>>> import numpy as np
>>> arlpy.plot.image(np.random.normal(size=(100,100)), colormap='Inferno256')
bellhop.plotutils.vlines(x: Any, color: str = 'gray', style: str = 'dashed', thickness: int = 1, hold: bool = False) → None[source]

Draw vertical lines on a plot.

Parameters:

  • x – x location of lines

  • color – line color (see Bokeh colors)

  • style – line style (‘solid’, ‘dashed’, ‘dotted’, ‘dotdash’, ‘dashdot’)

  • thickness – line width in pixels

  • hold – if set to True, output is not plotted immediately, but combined with the next plot

>>> import arlpy.plot
>>> arlpy.plot.plot([0, 20], [0, 10], hold=True)
>>> arlpy.plot.vlines([7, 12])
bellhop.plotutils.hlines(y: Any, color: str = 'gray', style: str = 'dashed', thickness: int = 1, hold: bool = False) → None[source]

Draw horizontal lines on a plot.

Parameters:

  • y – y location of lines

  • color – line color (see Bokeh colors)

  • style – line style (‘solid’, ‘dashed’, ‘dotted’, ‘dotdash’, ‘dashdot’)

  • thickness – line width in pixels

  • hold – if set to True, output is not plotted immediately, but combined with the next plot

>>> import arlpy.plot
>>> arlpy.plot.plot([0, 20], [0, 10], hold=True)
>>> arlpy.plot.hlines(3, color='red', style='dotted')
bellhop.plotutils.text(x: float, y: float, s: str, color: str = 'gray', size: str = '8pt', hold: bool = False) → None[source]

Add text annotation to a plot.

Parameters:

  • x – x location of left of text

  • y – y location of bottom of text

  • s – text to add

  • color – text color (see Bokeh colors)

  • size – text size (e.g. ‘12pt’, ‘3em’)

  • hold – if set to True, output is not plotted immediately, but combined with the next plot

>>> import arlpy.plot
>>> arlpy.plot.plot([0, 20], [0, 10], hold=True)
>>> arlpy.plot.text(7, 3, 'demo', color='orange')
bellhop.plotutils.box(left: float | None = None, right: float | None = None, top: float | None = None, bottom: float | None = None, color: str = 'yellow', alpha: float = 0.1, hold: bool = False) → None[source]

Add a highlight box to a plot.

Parameters:

  • left – x location of left of box

  • right – x location of right of box

  • top – y location of top of box

  • bottom – y location of bottom of box

  • color – text color (see Bokeh colors)

  • alpha – transparency (0-1)

  • hold – if set to True, output is not plotted immediately, but combined with the next plot

>>> import arlpy.plot
>>> arlpy.plot.plot([0, 20], [0, 10], hold=True)
>>> arlpy.plot.box(left=5, right=10, top=8)
bellhop.plotutils.color(n: int) → str[source]

Get a numbered color to cycle over a set of colors.

>>> import arlpy.plot
>>> arlpy.plot.color(0)
'blue'
>>> arlpy.plot.color(1)
'red'
>>> arlpy.plot.plot([0, 20], [0, 10], color=arlpy.plot.color(3))
bellhop.plotutils.set_colors(c: List[str]) → None[source]

Provide a list of named colors to cycle over.

>>> import arlpy.plot
>>> arlpy.plot.set_colors(['red', 'blue', 'green', 'black'])
>>> arlpy.plot.color(2)
'green'
bellhop.plotutils.specgram(x: Any, fs: float = 2, nfft: int | None = None, noverlap: int | None = None, colormap: str = 'Plasma256', clim: Tuple[float, float] | None = None, clabel: str = 'dB', title: str | None = None, xlabel: str = 'Time (s)', ylabel: str = 'Frequency (Hz)', xlim: Tuple[float, float] | None = None, ylim: Tuple[float, float] | None = None, width: int | None = None, height: int | None = None, hold: bool = False, interactive: bool | None = None) → None[source]

Plot spectrogram of a given time series signal.

Parameters:

  • x – time series signal

  • fs – sampling rate

  • nfft – FFT size (see scipy.signal.spectrogram)

  • noverlap – overlap size (see scipy.signal.spectrogram)

  • colormap – named color palette or Bokeh ColorMapper (see Bokeh palettes)

  • clim – color axis limits (min, max), or dynamic range with respect to maximum

  • clabel – color axis label

  • title – figure title

  • xlabel – x-axis label

  • ylabel – y-axis label

  • xlim – x-axis limits (min, max)

  • ylim – y-axis limits (min, max)

  • width – figure width in pixels

  • height – figure height in pixels

  • interactive – enable interactive tools (pan, zoom, etc) for plot

  • hold – if set to True, output is not plotted immediately, but combined with the next plot

>>> import arlpy.plot
>>> import numpy as np
>>> arlpy.plot.specgram(np.random.normal(size=(10000)), fs=10000, clim=30)
bellhop.plotutils.psd(x: Any, fs: float = 2, nfft: int = 512, noverlap: int | None = None, window: str = 'hann', color: str | None = None, style: str = 'solid', thickness: int = 1, marker: str | None = None, filled: bool = False, size: int = 6, title: str | None = None, xlabel: str = 'Frequency (Hz)', ylabel: str = 'Power spectral density (dB/Hz)', xlim: Tuple[float, float] | None = None, ylim: Tuple[float, float] | None = None, width: int | None = None, height: int | None = None, legend: str | None = None, hold: bool = False, interactive: bool | None = None) → None[source]

Plot power spectral density of a given time series signal.

Parameters:

  • x – time series signal

  • fs – sampling rate

  • nfft – segment size (see scipy.signal.welch)

  • noverlap – overlap size (see scipy.signal.welch)

  • window – window to use (see scipy.signal.welch)

  • color – line color (see Bokeh colors)

  • style – line style (‘solid’, ‘dashed’, ‘dotted’, ‘dotdash’, ‘dashdot’)

  • thickness – line width in pixels

  • marker – point markers (‘.’, ‘o’, ‘s’, ‘*’, ‘x’, ‘+’, ‘d’, ‘^’)

  • filled – filled markers or outlined ones

  • size – marker size

  • title – figure title

  • xlabel – x-axis label

  • ylabel – y-axis label

  • xlim – x-axis limits (min, max)

  • ylim – y-axis limits (min, max)

  • width – figure width in pixels

  • height – figure height in pixels

  • legend – legend text

  • interactive – enable interactive tools (pan, zoom, etc) for plot

  • hold – if set to True, output is not plotted immediately, but combined with the next plot

>>> import arlpy.plot
>>> import numpy as np
>>> arlpy.plot.psd(np.random.normal(size=(10000)), fs=10000)
bellhop.plotutils.iqplot(data: Any, marker: str = '.', color: str | None = None, labels: Any | None = None, filled: bool = False, size: int | None = None, title: str | None = None, xlabel: str | None = None, ylabel: str | None = None, xlim: List[float] = [-2, 2], ylim: List[float] = [-2, 2], width: int | None = None, height: int | None = None, hold: bool = False, interactive: bool | None = None) → None[source]

Plot signal points.

Parameters:

  • data – complex baseband signal points

  • marker – point markers (‘.’, ‘o’, ‘s’, ‘*’, ‘x’, ‘+’, ‘d’, ‘^’)

  • color – marker/text color (see Bokeh colors)

  • labels – label for each signal point, or True to auto-generate labels

  • filled – filled markers or outlined ones

  • size – marker/text size (e.g. 5, ‘8pt’)

  • title – figure title

  • xlabel – x-axis label

  • ylabel – y-axis label

  • xlim – x-axis limits (min, max)

  • ylim – y-axis limits (min, max)

  • width – figure width in pixels

  • height – figure height in pixels

  • interactive – enable interactive tools (pan, zoom, etc) for plot

  • hold – if set to True, output is not plotted immediately, but combined with the next plot

>>> import arlpy
>>> import arlpy.plot
>>> arlpy.plot.iqplot(arlpy.comms.psk(8))
>>> arlpy.plot.iqplot(arlpy.comms.qam(16), color='red', marker='x')
>>> arlpy.plot.iqplot(arlpy.comms.psk(4), labels=['00', '01', '11', '10'])
bellhop.plotutils.freqz(b: Any, a: Any = 1, fs: float = 2.0, worN: int | None = None, whole: bool = False, degrees: bool = True, style: str = 'solid', thickness: int = 1, title: str | None = None, xlabel: str = 'Frequency (Hz)', xlim: Tuple[float, float] | None = None, ylim: Tuple[float, float] | None = None, width: int | None = None, height: int | None = None, hold: bool = False, interactive: bool | None = None) → None[source]

Plot frequency response of a filter.

This is a convenience function to plot frequency response, and internally uses scipy.signal.freqz() to estimate the response. For further details, see the documentation for scipy.signal.freqz().

Parameters:

  • b – numerator of a linear filter

  • a – denominator of a linear filter

  • fs – sampling rate in Hz (optional, normalized frequency if not specified)

  • worN – see scipy.signal.freqz()

  • whole – see scipy.signal.freqz()

  • degrees – True to display phase in degrees, False for radians

  • style – line style (‘solid’, ‘dashed’, ‘dotted’, ‘dotdash’, ‘dashdot’)

  • thickness – line width in pixels

  • title – figure title

  • xlabel – x-axis label

  • ylabel1 – y-axis label for magnitude

  • ylabel2 – y-axis label for phase

  • xlim – x-axis limits (min, max)

  • ylim – y-axis limits (min, max)

  • width – figure width in pixels

  • height – figure height in pixels

  • interactive – enable interactive tools (pan, zoom, etc) for plot

  • hold – if set to True, output is not plotted immediately, but combined with the next plot

>>> import arlpy
>>> arlpy.plot.freqz([1,1,1,1,1], fs=120000);

Plotting functions (matplotlib)

Plotting functions for the underwater acoustic propagation modeling toolbox.

class bellhop.pyplot.Any(*args, **kwargs)[source]

Special type indicating an unconstrained type.

  • Any is compatible with every type.

  • Any assumed to have all methods.

  • All values assumed to be instances of Any.

Note that all the above statements are true from the point of view of static type checkers. At runtime, Any should not be used with instance checks.

bellhop.pyplot.pyplot_env(env: Dict[str, Any], surface_color: str = 'dodgerblue', bottom_color: str = 'peru', source_color: str = 'orangered', receiver_color: str = 'midnightblue', receiver_plot: bool | None = None, **kwargs: Any) → None[source]

Plots a visual representation of the environment with matplotlib.

Parameters:

  • env (dict) – Environment description

  • surface_color (str, default='dodgerblue') –

    Color of the surface (see Bokeh colors)

  • bottom_color (str, default='peru') –

    Color of the bottom (see Bokeh colors)

  • source_color (str, default='orangered') –

    Color of transmitters (see Bokeh colors)

  • receiver_color (str, default='midnightblue') –

    Color of receivers (see Bokeh colors)

  • receiver_plot (bool, optional) – True to plot all receivers, False to not plot any receivers, None to automatically decide

  • **kwargs – Other keyword arguments applicable for bellhop.plot.plot() are also supported

Notes

The surface, bottom, transmitters (marker: ‘*’) and receivers (marker: ‘o’) are plotted in the environment. If receiver_plot is set to None and there are more than 2000 receivers, they are not plotted.

Examples

>>> import bellhop as bh
>>> env = bh.create_env(depth=[[0, 40], [100, 30], [500, 35], [700, 20], [1000,45]])
>>> bh.plot_env(env)
bellhop.pyplot.pyplot_ssp(env: Dict[str, Any], **kwargs: Any) → None[source]

Plots the sound speed profile with matplotlib.

Parameters:

  • env (dict) – Environment description

  • **kwargs – Other keyword arguments applicable for bellhop.plot.plot() are also supported

Notes

If the sound speed profile is range-dependent, this function only plots the first profile.

Examples

>>> import bellhop as bh
>>> env = bh.create_env(soundspeed=[[ 0, 1540], [10, 1530], [20, 1532], [25, 1533], [30, 1535]])
>>> bh.plot_ssp(env)
bellhop.pyplot.pyplot_arrivals(arrivals: Any, dB: bool = False, color: str = 'blue', **kwargs: Any) → None[source]

Plots the arrival times and amplitudes with matplotlib.

Parameters:

  • arrivals (pandas.DataFrame) – Arrivals times (s) and coefficients

  • dB (bool, default=False) – True to plot in dB, False for linear scale

  • color (str, default='blue') –

    Line color (see Bokeh colors)

  • **kwargs – Other keyword arguments applicable for bellhop.plot.plot() are also supported

Examples

>>> import bellhop as bh
>>> env = bh.create_env()
>>> arrivals = bh.compute_arrivals(env)
>>> bh.plot_arrivals(arrivals)
bellhop.pyplot.pyplot_rays(rays: Any, env: Dict[str, Any] | None = None, invert_colors: bool = False, **kwargs: Any) → None[source]

Plots ray paths with matplotlib

Parameters:

  • rays (pandas.DataFrame) – Ray paths

  • env (dict, optional) – Environment definition

  • invert_colors (bool, default=False) – False to use black for high intensity rays, True to use white

  • **kwargs – Other keyword arguments applicable for bellhop.plot.plot() are also supported

Notes

If environment definition is provided, it is overlayed over this plot using default parameters for bellhop.plot_env().

Examples

>>> import bellhop as bh
>>> env = bh.create_env()
>>> rays = bh.compute_eigenrays(env)
>>> bh.plot_rays(rays, width=1000)
bellhop.pyplot.pyplot_transmission_loss(tloss: Any, env: Dict[str, Any] | None = None, **kwargs: Any) → None[source]

Plots transmission loss with matplotlib.

Parameters:

  • tloss (pandas.DataFrame) – Complex transmission loss

  • env (dict, optional) – Environment definition

  • **kwargs – Other keyword arguments applicable for bellhop.plot.image() are also supported

Notes

If environment definition is provided, it is overlayed over this plot using default parameters for bellhop.plot_env().

Examples

>>> import bellhop as bh
>>> import numpy as np
>>> env = bh.create_env(
        receiver_depth=np.arange(0, 25),
        receiver_range=np.arange(0, 1000),
        beam_angle_min=-45,
        beam_angle_max=45
    )
>>> tloss = bh.compute_transmission_loss(env)
>>> bh.plot_transmission_loss(tloss, width=1000)