uclchem.plot.panels#

Atomic plot units — each function draws a single panel onto a provided axis.

Module Contents#

Functions#

draw_panel_abundances(→ matplotlib.pyplot.Axes)

Draw species abundances onto ax (Panel A of a deepdive figure).

draw_panel_rate_constants(→ matplotlib.pyplot.Axes)

Draw rate constants onto ax (Panel C of a deepdive figure).

draw_panel_rates(→ matplotlib.pyplot.Axes)

Draw production and destruction rates onto ax (Panel B of a deepdive figure).

plot_species(→ matplotlib.pyplot.Axes)

Plot the abundance of a list of species through time directly onto an axis.
uclchem.plot.panels.draw_panel_abundances(ax: matplotlib.pyplot.Axes, time: pandas.Series, species: str, chem: pandas.DataFrame, companion: list[str] | None = None, *, reactant_species: set[str] | None = None, color_registry: dict[str, str] | None = None) → matplotlib.pyplot.Axes[source]#

Draw species abundances onto ax (Panel A of a deepdive figure).

The target species is drawn in black at full weight. Each entry in companion is drawn in a tab20 color; species that appear in reactant_species get a thicker, more opaque line to signal their direct chemical involvement.

Parameters:

  • ax (plt.Axes) – Axes to draw on.

  • time (pd.Series) – Time series (years) for the x-axis.

  • species (str) – UCLCHEM name of the primary species.

  • chem (pd.DataFrame) – Chemistry (abundance) DataFrame, already filtered to the desired time range.

  • companion (list[str] | None) – Additional species to overlay. Pass None (default) to show only species.

  • reactant_species (set[str] | None) – Species that appear as reactants in the top reactions; these are rendered with higher visual weight. Default: empty set.

  • color_registry (dict[str, str] | None) – Shared color map (species name → hex string). Pass the same dict to multiple panel calls to keep colors consistent. A fresh registry is created when None is passed. Default: None.

Returns:

ax – The modified axes.

Return type:

plt.Axes

uclchem.plot.panels.draw_panel_rate_constants(ax: matplotlib.pyplot.Axes, time: pandas.Series, prod_k: pandas.DataFrame, dest_k: pandas.DataFrame, top_prod: list[str] | None = None, top_dest: list[str] | None = None, *, top_k: int | None = 5, bar: bool = False, color_registry: dict[str, str] | None = None) → matplotlib.pyplot.Axes[source]#

Draw rate constants onto ax (Panel C of a deepdive figure).

By default draws rate constants as time series so trends are visible. Pass bar=True for a mean bar chart; a warning is emitted for any reaction whose rate constant varies significantly over time (CV > 1 %).

Parameters:

  • ax (plt.Axes) – Axes to draw on.

  • time (pd.Series) – Time series (years) for the x-axis.

  • prod_k (pd.DataFrame) – Rate-constant DataFrame for production reactions, already filtered to the desired time range.

  • dest_k (pd.DataFrame) – Rate-constant DataFrame for destruction reactions.

  • top_prod (list[str] | None) – Reaction column names to include for production. When None, the top top_k reactions by mean rate constant are selected. Default: None.

  • top_dest (list[str] | None) – Reaction column names to include for destruction. When None, the top top_k reactions by mean rate constant are selected. Default: None.

  • top_k (int | None) – Number of top reactions to show when top_prod / top_dest are None. Pass None to show all. Default: 5.

  • bar (bool) – If True, draw a mean bar chart instead of time series. Default: False.

  • color_registry (dict[str, str] | None) – Shared color map (reaction string → hex string). A fresh registry is created when None is passed. Default: None.

Returns:

ax – The modified axes.

Return type:

plt.Axes

uclchem.plot.panels.draw_panel_rates(ax: matplotlib.pyplot.Axes, time: pandas.Series, prod_rates: pandas.DataFrame, dest_rates: pandas.DataFrame, top_prod: list[str] | None = None, top_dest: list[str] | None = None, *, top_k: int | None = 5, color_registry: dict[str, str] | None = None) → matplotlib.pyplot.Axes[source]#

Draw production and destruction rates onto ax (Panel B of a deepdive figure).

Total formation and destruction envelopes are always drawn in black. Reactions listed in top_prod / top_dest are drawn individually in tab20 colors; remaining reactions are summed into a gray “Other” line.

Parameters:

  • ax (plt.Axes) – Axes to draw on.

  • time (pd.Series) – Time series (years) for the x-axis.

  • prod_rates (pd.DataFrame) – Per-reaction production rates (abundance wrt H s⁻¹), already filtered to the desired time range.

  • dest_rates (pd.DataFrame) – Per-reaction destruction rates (absolute values), already filtered.

  • top_prod (list[str] | None) – Reaction column names to draw individually for production. When None, the top top_k reactions by mean rate are selected. Default: None.

  • top_dest (list[str] | None) – Reaction column names to draw individually for destruction. When None, the top top_k reactions by mean rate are selected. Default: None.

  • top_k (int | None) – Number of top reactions to show individually when top_prod / top_dest are None. Pass None to show all reactions. Default: 5.

  • color_registry (dict[str, str] | None) – Shared color map (reaction string → hex string). Pass the same dict to multiple panel calls to keep colors consistent. A fresh registry is created when None is passed. Default: None.

Returns:

ax – The modified axes.

Return type:

plt.Axes

uclchem.plot.panels.plot_species(ax: matplotlib.pyplot.Axes, df: pandas.DataFrame, species: list[str], legend: bool = True, plot_kwargs: dict[str, Any] | None = None) → matplotlib.pyplot.Axes[source]#

Plot the abundance of a list of species through time directly onto an axis.

Parameters:

  • ax (plt.Axes) – An axis object to plot on

  • df (pd.DataFrame) – A dataframe created by uclchem.analysis.read_output_file, uclchem.model.load_model or uclchem.model.Model.get_dataframes.

  • species (list[str]) – A list of species names to be plotted. If species name starts with “$” instead of “#” or “@”, plots the sum of surface and bulk abundances

  • legend (bool) – Whether to add a legend to the plot. Default = True.

  • plot_kwargs (dict[str, Any] | None) – keyword arguments passed to ax.plot. Default = None.

Returns:

ax – Modified input axis is returned

Return type:

plt.Axes

Raises:

KeyError – if no "Time" column is present in df.