uclchem.plot.compositions#

Composition functions — each creates a complete figure by assembling panels.

Module Contents#

Functions#

create_abundance_plot(, plot_file, plot_kwargs, ...)

Create a plot of the abundance of a list of species through time.

plot_rate_summary(→ list[matplotlib.pyplot.Axes])

Create a summary of the top k production and destruction reactions.

plot_rates_deepdive(, filter_freeze, max_species_show, ...)

Create a three-panel chemical deep-dive figure for species.
uclchem.plot.compositions.create_abundance_plot(df: pandas.DataFrame, species: list[str], figsize: tuple[float, float] = (16, 9), plot_file: str | pathlib.Path | None = None, plot_kwargs: dict[str, Any] | None = None) → tuple[matplotlib.pyplot.Figure, matplotlib.pyplot.Axes][source]#

Create a plot of the abundance of a list of species through time.

Parameters:

  • df (pd.DataFrame) – Pandas dataframe containing the UCLCHEM output, see uclchem.analysis.read_output_file, uclchem.model.load_model or uclchem.model.Model.get_dataframes.

  • species (list[str]) – list of strings containing species names. Using a $ instead of # or @ will plot the sum of surface and bulk abundances.

  • figsize (tuple[float, float]) – Size of figure, width by height in inches. Defaults to (16, 9).

  • plot_file (str | Path | None) – Path to file where figure will be saved. If None, figure is not saved. Defaults to None.

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

Returns:

  • fig (plt.Figure) – created Figure object

  • ax (plt.Axes) – created axis object

uclchem.plot.compositions.plot_rate_summary(production_df: pandas.DataFrame, destruction_df: pandas.DataFrame, step: int, xlabel: str = 'Reaction rate (abundance wrt H / s)', top_k_rates: int = 5) → list[matplotlib.pyplot.Axes][source]#

Create a summary of the top k production and destruction reactions.

Parameters:

  • production_df (pd.DataFrame) – dataframe with reaction rates of formation reactions of species of interest

  • destruction_df (pd.DataFrame) – dataframe with reaction rates of destruction reactions of species of interest

  • step (int) – time index of dataframes to plot.

  • xlabel (str) – xlabel. Default: “Reaction rate (abundance wrt H / s)”

  • top_k_rates (int) – Plot top k formation and destruction reactions. Default: 5

Returns:

axs – axes of the plot

Return type:

list[plt.Axes]

uclchem.plot.compositions.plot_rates_deepdive(species: str, physics_df: pandas.DataFrame, chemistry_df: pandas.DataFrame, rate_constants_df: pandas.DataFrame, network: uclchem.makerates.network.Network | None = None, *, filter_threshold: float = 0.01, filter_window: tuple[float, float] = (10000.0, 1000000.0), filter_freeze: bool = True, max_species_show: int = 12, figsize: tuple[float, float] = (8, 12), output_path: pathlib.Path | str | None = None, fig: matplotlib.figure.FigureBase | None = None, color_registry: dict[str, str] | None = None) → tuple[matplotlib.figure.FigureBase, matplotlib.pyplot.Axes, matplotlib.pyplot.Axes, matplotlib.pyplot.Axes][source]#

Create a three-panel chemical deep-dive figure for species.

Panel A (top): Abundances of species and the reactant species involved in its top production and destruction reactions.

Panel B (bottom): Individual production (solid) and destruction (dashed) reaction rates, plus totals.

Panel C (middle): Bar chart of mean rate constants for the top reactions, colored to match Panel B.

Parameters:

  • species (str) – UCLCHEM species name to analyze, e.g. "HCO+".

  • physics_df (pd.DataFrame) – Physics DataFrame from get_dataframes().

  • chemistry_df (pd.DataFrame) – Chemistry (abundance) DataFrame.

  • rate_constants_df (pd.DataFrame) – Rate-constants DataFrame (with_rate_constants=True).

  • network (Network | None) – Pre-loaded Network. If None the default network is loaded via from_csv().

  • filter_threshold (float) – Reactions whose rate never exceeds this fraction of the per-step maximum within filter_window are excluded. Default: 0.01.

  • filter_window (tuple[float, float]) – (t_min, t_max) in years used for reaction filtering and ranking. Default: (1e4, 1e6).

  • filter_freeze (bool) – If True (default), exclude freeze-out reactions.

  • max_species_show (int) – Maximum number of companion species to draw in Panel A. Default: 12.

  • figsize (tuple[float, float]) – Figure width × height in inches. Ignored when fig is provided. Default: (8, 12).

  • output_path (Path | str | None) – If provided, save the figure as both <output_path>.pdf and <output_path>.png. Only meaningful when fig is a top-level Figure. Default: None.

  • fig (matplotlib.figure.FigureBase | None) – Existing figure or sub-figure to draw into. Pass a SubFigure obtained from parent.subfigures() to embed this plot inside a larger layout. If None (default) a new figure is created.

  • color_registry (dict[str, str] | None) – Mutable mapping from species / reaction name to hex color string. Pass the same dict to multiple calls to keep colors consistent across subfigures. If None (default) a fresh registry is created internally.

Returns:

  • fig (matplotlib.figure.FigureBase) – The figure (or sub-figure) containing all three panels.

  • ax_abundances (plt.Axes) – Panel A — species abundances.

  • ax_rates (plt.Axes) – Panel B — production / destruction rates.

  • ax_rate_constants (plt.Axes) – Panel C — mean rate-constant bar chart.

Notes