Visuals

Submodules

Plotting module

In: scintillometry.visuals.plotting.py

Automates data plotting.

class scintillometry.visuals.plotting.FigureFormat

Bases: object

Regulates plot annotations and formatting.

get_date_and_timezone(data)

Return first time index and timezone.

Parameters:

data (pd.DataFrame or pd.Series) – TZ-aware dataframe with DatetimeIndex.

Returns:

Date formatted as “DD Month YYYY”, and timezone object.

Return type:

dict[str, datetime.tzinfo]

get_site_name(site_name, dataframe=None)

Gets name of site from user string or dataframe metadata.

Parameters:

• site_name (str) – Location of data collection.

• dataframe (pd.DataFrame or pd.Series) – Any collected dataset. Default None.

Returns:

Location of data collection. Returns empty string if no user argument or metadata was found.

Return type:

str

initialise_formatting(small=14, medium=16, large=18, extra=20)

Initialises font sizes for matplotlib figures.

Called separately from other plotting functions in this module to avoid overwriting on-the-fly formatting changes.

Parameters:

• small (int) – Size of text, ticks, legend. Default 14.

• medium (int) – Size of axis labels. Default 16.

• large (int) – Size of axis title. Default 18.

• extra (int) – Size of figure title (suptitle). Default 20.

label_selector(dependent)

Constructs label parameters from dependent variable name.

If the variable name is not implemented, the unconverted variable is passed directly, with the symbol duplicated from its name and with no unit provided.

Parameters:

dependent (str) – Name of dependent variable.

Returns:

Name of dependent variable, symbol in LaTeX format, unit in LaTeX format -> (name, symbol, unit).

Return type:

tuple[str, str, str]

merge_label_with_unit(label)

Merges variable name with its unit if applicable.

Parameters:

label (tuple[str, str, str]) –

Contains the name, symbol, and unit of a variable. Supports both TeX and empty strings. Strings containing TeX must be passed as raw strings:

label = ("Name", "Symbol", r"$Unit_{TeX}$")
label = ("Name", r"$Symbol_{TeX}$", "")

Returns:

Formatted string with the name and unit of a variable.

Return type:

str

merge_multiple_labels(labels)

Merges multiple labels into a single formatted string.

Parameters:

labels (list[str]) – Labels, which may contain duplicates.

Returns:

A formatted, punctuated string with no duplicates.

Return type:

str

parse_formatting_kwargs(axis, **kwargs)

Parses kwargs for generic formatting.

Applies horizontal or vertical lines, updates axis title and labels.

Parameters:

axis (plt.Axes) – Target axes.

Keyword Arguments:

• hlines (dict) – Name and y-axis value for which to plot a horizontal line.

• title (str) – Axis title.

• vlines (dict) – Name and x-axis value for which to plot a vertical line.

• x_label (str) – X-axis label.

• y_label (str) – Y-axis label.

plot_constant_lines(axis, hlines=None, vlines=None)

Plots horizontal or vertical lines onto axis.

Parameters:

• axis (plt.Axes) – Target axes.

• hlines (dict[str, float]) – Name and x-axis value for which to plot a horizontal line. Default None.

• vlines (dict[str, float]) – Name and x-axis value for which to plot a vertical line. Default None.

set_xy_labels(ax, timezone, name)

Sets labels for X (time), Y (variable) axis.

Parameters:

• ax (plt.Axes) – Plot’s axes.

• timezone (datetime.tzinfo) – Local timezone of data.

• name (str) – Name or abbreviation of dependent variable.

Returns:

Plot axes with labels for local time on the x-axis and for the dependent variable with units on the y-axis. Ticks on the x-axis are formatted at hourly intervals.

Return type:

plt.Axes

title_plot(title, timestamp, location='')

Constructs title and legend.

Parameters:

• title (str) – Prefix to include in title.

• timestamp (Union[str, pd.Timestamp]) – Date or time of data collection.

• location (str) – Location of data collection. Default empty string.

Returns:

Title of plot with location and time.

Return type:

str

class scintillometry.visuals.plotting.FigurePlotter

Bases: FigureFormat

Handles drawing and saving figures from various data.

plot_comparison(df_01, df_02, keys, labels, site='')

Plots two dataframes with identical indices.

Parameters:

• df_01 (pd.DataFrame) – First dataframe.

• df_02 (pd.DataFrame) – Second dataframe.

• keys (list) – Key names formatted as: [<df_01_key>, <df_series_key>].

• labels (list) – Labels for legend formatted as: [<df_01_label>, <df_02_label>].

• site (str) – Location of data collection. Default empty string.

Returns:

Figure and axes of time series plot.

Return type:

tuple[plt.Figure, plt.Axes]

plot_convection(dataframe, stability=None, site='')

Plots scintillometer convection and free convection.

Parameters:

• dataframe (pd.DataFrame) – Contains sensible heat fluxes from on-board software and for free convection \(H_{free}\).

• stability (str) – Stability conditions. Default None.

• site (str) – Location of data collection. Default empty string.

Returns:

Figure, axes comparing the sensible heat flux from on-board software to free convection.

Return type:

tuple[plt.Figure, plt.Axes]

plot_generic(dataframe, name, site='')

Plots time series of variable with hourly mean.

Parameters:

• dataframe (pd.DataFrame) – Contains data for times series.

• name (str) – Name of dependent variable, must be key in dataframe.

• site (str) – Location of data collection. Default empty string.

Returns:

Figure and axes of time series plot.

Return type:

tuple[plt.Figure, plt.Axes]

plot_innflux(iter_data, innflux_data, name='obukhov', site='')

Plots comparison between scintillometer and InnFLUX data.

Parameters:

• iter_data (pd.DataFrame) – Iterated data from scintillometer.

• innflux_data (pd.DataFrame) – InnFLUX data.

• name (str) – Name of dependent variable, must be key in dataframe.

• site (str) – Location of data collection. Default empty string.

Returns:

Figure and axes of time series plot.

Return type:

tuple[plt.Figure, plt.Axes]

plot_iterated_fluxes(iteration_data, time_id, location='')

Plots and saves iterated SHF, comparison to free convection.

Note

Pending deprecation in a future patch release. Use MetricsFlux.plot_iterated_metrics() instead.

Parameters:

• iteration_data (pd.DataFrame) – TZ-aware with sensible heat fluxes calculated for free convection \(H_{free}\), and MOST \(H\).

• time_id (pd.Timestamp) – Local time of data collection.

• location (str) – Location of data collection. Default empty string.

Returns:

Time series and comparison.

Return type:

list[tuple[plt.Figure, plt.Axes]]

plot_merged_profiles(dataset, time_index, site='', y_lim=None, **kwargs)

Plots vertical profiles on the same axis.

Parameters:

• dataset (dict) – Dataframes of vertical profiles.

• time_index (str or pd.Timestamp) – The time for which to plot a vertical profile.

• site (str) – Location of data collection. Default empty string.

• y_lim (float) – Y-axis limit. Default None.

Keyword Arguments:

• hlines (dict) – Names and y-axis values for which to plot horizontal lines.

• title (str) – Figure title.

• vlines (dict) – Names and x-axis values for which to plot vertical lines.

• x_label (str) – X-axis label. Default None.

Returns:

Figure and axis of vertical profiles.

Return type:

tuple[plt.Figure, plt.Axes]

plot_scatter(x_data, y_data, name, sources, score=None, regression_line=None, site='')

Plots scatter between two datasets with a regression line.

Parameters:

• x_data (pd.Series) – Labelled explanatory data.

• y_data (pd.Series) – Labelled response data.

• name (str) – Name of variable.

• sources (list[str, str]) – Names of data sources formatted as: [<Explanatory Source>, <Response Source>].

• score (float) – Coefficient of determination math:R^{2}. Default None.

• regression_line (np.ndarray) – Values for regression line. Default None.

• site (str) – Location of data collection. Default empty string.

Returns:

Regression plot of explanatory and response data, with fitted regression line and regression score.

Return type:

tuple[plt.Figure, plt.Axes]

plot_time_series(series_data, series_mean=None, name='Time Series', line_colour='black', grey=False)

Plots time series and mean.

Parameters:

• series_data (pd.Series) – Series with data to plot.

• series_mean (pd.Series) – Series with mean data to plot. Default None.

• name (str) – Time series label. Default “Time Series”.

• line_colour (str) – Line colour. Default “black”.

• grey (bool) – If True, plotted line is greyed out. Default False.

plot_vertical_comparison(dataset, time_index, keys, site='', **kwargs)

Plots comparison of two vertical profiles with the same indices.

Parameters:

• dataset (dict) – Dataframes of vertical profiles.

• time_index (str or pd.Timestamp) – The time for which to plot a vertical profile.

• keys (list) – Dependent variable keys.

• site (str) – Location of data collection. Default empty string.

Keyword Arguments:

• hlines (dict) – Name and y-axis value for which to plot horizontal lines.

• vlines (dict) – Name and x-axis value for which to plot vertical lines.

Returns:

Figure and axis of vertical profiles.

Return type:

tuple[plt.Figure, plt.Axes]

plot_vertical_profile(vertical_data, time_idx, name, site='', y_lim=None, **kwargs)

Plots vertical profile of variable.

Parameters:

• vertical_data (dict[str, pd.DataFrame]) – Contains time series of vertical measurements.

• time_idx (pd.Timestamp) – The local time for which to plot a vertical profile.

• name (str) – Name of dependent variable, must be key in <vertical_data>.

• site (str) – Location of data collection. Default empty string.

• y_lim (float) – Y-axis limit. Default None.

Keyword Arguments:

• hlines (dict) – Name and y-axis value for which to plot a horizontal line.

• vlines (dict) – Name and x-axis value for which to plot a vertical line.

Returns:

Figure and axis of vertical profiles.

Return type:

tuple[plt.Figure, plt.Axes]

save_figure(figure, timestamp, suffix='', img_format='svg', output_dir='./reports/figures/')

Saves figure to disk.

Parameters:

• figure (plt.Figure) – Matplotlib figure object.

• timestamp (pd.Timestamp) – Date or time of data collection.

• suffix (str) – Additional string to add to file name.

• img_format (str) – Image file format. Default SVG.

• output_dir (str) – Location to save images. Default “./reports/figures/”.

setup_plot_data(data, names=None)

Sets up data for plotting.

The original data is deep copied as slicing in the outer scope can overwrite data before it is plotted.

Parameters:

• data (pd.DataFrame) – Labelled data.

• names (list) – Names of dependent variables. Default None.

Returns:

Deep copy of original data, hourly mean of data, and dictionary with date and timestamp metadata.

Return type:

tuple[pd.DataFrame, pd.DataFrame, dict]

Module contents