ampycloud.plots package

Distributed under the terms of the 3-Clause BSD License.

SPDX-License-Identifier: BSD-3-Clause

Submodules

ampycloud.plots.core module

Distributed under the terms of the 3-Clause BSD License.

SPDX-License-Identifier: BSD-3-Clause

Module contains: core plotting routines

ampycloud.plots.core.diagnostic(chunk: CeiloChunk, upto: str = 'layers', show_ceilos: bool = False, ref_metar: str | None = None, ref_metar_origin: str | None = None, show: bool = True, save_stem: str | None = None, save_fmts: list | str | None = None) → None

A function to create the ampycloud diagnostic plot all the way to the layering step (included). This is the ultimate ampycloud plot that shows it all (or not - you choose !).

Parameters:

chunk (CeiloChunk) – the CeiloChunk to look at.
upto (str, optional) – up to which algorithm steps to plot. Can be one of [‘raw_data’, ‘slices’, ‘groups’, ‘layers’]. Defaults to ‘layers’.
show_ceilos (bool, optional) – if True, hits will be colored as a function of the responsible ceilometer. Defaults to False. No effects unless upto='raw data'.
ref_metar (str, optional) – reference METAR message. Defaults to None.
ref_metar_origin (str, optional) – name of the source of the reference METAR set with ref_metar. Defaults to None.
show (bool, optional) – will show the plot on the screen if True. Defaults to False.
save_stem (str, optional) – if set, will save the plot with this stem (which can include a path as well). Deafults to None.
save_fmts (list|str, optional) – a list of file formats to export the plot to. Defaults to None = [‘pdf’].

Example:

from datetime import datetime
import ampycloud
from ampycloud.utils import mocker
from ampycloud.plots import diagnostic

# First create some mock data for the example
mock_data = mocker.canonical_demo_data()

# Then run the ampycloud algorithm on it
chunk = ampycloud.run(mock_data, geoloc='Mock data', ref_dt=datetime.now())

# Create the full ampycloud diagnostic plot
diagnostic(chunk, upto='layers', show=True)

ampycloud.plots.diagnostics module

Distributed under the terms of the 3-Clause BSD License.

SPDX-License-Identifier: BSD-3-Clause

Module contains: class for the diagnostic plots

class ampycloud.plots.diagnostics.DiagnosticPlot(chunk: CeiloChunk)

Bases: object

Class used to create diagnostic plots.

__init__(chunk: CeiloChunk) → None

The init function.

Parameters:: :py:class:`ampycloud.data.CeiloChunk` – a ceilometer Data Chunk.

static setup_fig() → tuple

Setups a diagnsotic plot figure.

Returns:: fig, axs – the matplotlib figure, and the axes stored in a list.

new_fig() → None: Assign the fig attribute.

show_hits_only(show_ceilos: bool = False) → None

Shows the ceilometer hits alone.

Parameters:: show_ceilos (bool, optional) – whether to distinguish between the different ceilos, or not.

Important

This will clear the plot first !

show_slices() → None: Show the slice data.

show_groups(show_points: bool = False) → None

Show the group data.

Parameters:: show_points (bool, optional) – whether to actually draw the groups, or simply add the info about them. Defaults to False.

show_layers() → None: Show the layer data.

add_vv_legend() → None: Adds a legend about the VV hits.

add_ceilo_count() → None: Adds the number of ceilometer present in the data.

add_max_hits() → None: Adds the max_hit_per_layer info.

add_geoloc_and_ref_dt() → None: Adds info about the chunk geoloc and reference date & time.

add_ref_metar(name: str | None, metar: str | None) → None

Display a reference METAR, for example from human observers, different code, etc …

Parameters:

name (str) – the name of the reference, e.g. ‘Human Observers’.
metar (str) – the METAR code.

add_metar() → None: Display the ampycloud METAR message.

format_primary_axes() → None: Deals with the main plot axes

format_slice_axes() → None: Format the duplicate axes related to the slicing part.

format_group_axes() → None

Format the duplicate axes related to the grouping part.

TODO: add secondary axis for the height rescaling as well. See #91.

save(fn_out: str, fmts: list | None = None) → None

Saves the plot to file.

Parameters:

fn_out (str) – file name out.
fmts (list or str, optional) – list of formats to export the plot to. Defaults to None == ‘pdf’.

show() → None: Shows the plot

close_fig() → None

Close the figure to free the memory.

If you need to re-create them, start by generating the figure with the .new_fig() method.

ampycloud.plots.hardcoded module

Distributed under the terms of the 3-Clause BSD License.

SPDX-License-Identifier: BSD-3-Clause

Module contains: hardcoded plotting parameters

ampycloud.plots.hardcoded.WIDTH_ONECOL: float = 6.92

Width of a 1-column plot [inches], to fit in scientific articles when scaled by 50%

Type:: float

ampycloud.plots.hardcoded.WIDTH_TWOCOL: float = 14.16

Width of a 2-column plot [inches], to fit in scientific articles when scaled by 50%

Type:: float

ampycloud.plots.hardcoded.MRKS = ['s', '^', 'o', 'v', 'D', '>', 'h', '<']

list of markers, for the different cloud layers

Type:: list

ampycloud.plots.secondary module

Distributed under the terms of the 3-Clause BSD License.

SPDX-License-Identifier: BSD-3-Clause

Module contains: secondary plotting functions

ampycloud.plots.secondary.scaling_fcts(show: bool = True, save_stem: str | None = None, save_fmts: list | str | None = None) → None

Plots the different scaling functions.

Parameters:

show (bool, optional) – show the plot, or not. Defaults to True.
save_stem (str, optional) – if set, will save the plot with this stem (which can include a path as well). Defaults to None.
save_fmts (list|str, optional) – a list of file formats to export the plot to. Defaults to None = [‘png’].

This is a small utility routine to rapidly see the different height scaling options used by ampycloud.

For the “step” scaling plot, the parameters are taken straight from dynamic.GROUPING_PRMS.

Example:

from ampycloud.plots.secondary import scaling_fcts

scaling_fcts(show=True, save_stem='ampycloud_scaling_fcts', save_fmts=['pdf'])

ampycloud.plots.tools module

Distributed under the terms of the 3-Clause BSD License.

SPDX-License-Identifier: BSD-3-Clause

Module contains: tools for plots

ampycloud.plots.tools.style_pth() → Path: Returns the Path to the ampycloud plotting styles.

ampycloud.plots.tools.valid_styles() → list: Returns the list of valid plotting styles.

ampycloud.plots.tools.set_mplstyle(func: Callable) → Callable

Intended to be used as a decorator around plotting functions, to set the plotting style.

Returns:: Callable – the decorator.

By defaults, the base ampycloud style will be enabled. Motivated users can tweak it further by setting the MPL_STYLE entry of ampycloud.dynamic.AMPYCLOUD_PRMS to:

latex: to enable the use of a system-wide LaTeX engine, and the Computer Modern font.

metsymb: to enable the use of a system-wide LaTeX engine, the Computer Modern font, and the metsymb LaTeX package to display proper okta symbols.

Important

The metsymb LaTeX package is NOT included with ampycloud, and must be installed separately. It is available at: https://github.com/MeteoSwiss/metsymb

Caution

Specifying the latex or metsymb style requires a working system-wide LaTeX installation. In particular, the following LaTeX packages must be installed:

cmbright

amsmath

amssymb

relsize

metsymb (only if the MPL_STYLE entry of ampycloud.dynamic.AMPYCLOUD_PRMS was set to 'metsymb')

Todo

See https://github.com/MeteoSwiss/ampycloud/issues/18

ampycloud.plots.tools.texify(msg: str) → str

Small utility function that TeX-ifies a string to make it LaTeX robust if warranted by the current rcParams settings.

Parameters:: msg (str) – message to clean-up
Returns:: str – the robust string.

ampycloud.plots.tools.get_scaling_kwargs(data: ndarray, mode: str, kwargs: dict) → tuple

Utility function to extract the actual, deterministic parameters required to scale the data, given a set of user-defined parameters.

Parameters:

data (pd.Series) – the data that was originally scaled by the user.
mode (str) – the name of the scaling used by the user. Must be any mode supported by ampycloud.scaler.convert_kwargs() (e.g. shift-and-scale, minmax-scale, step-scale).
kwargs (dict) – the scaling parameter set by the user.

Returns:

tuple – (scale_kwargs, descale_kwargs), the two dict with parameters for the forward/backward scaling.

This is a utility function to aid in the drawing of secondary axis that require to derive the “reverse scaling function”.