uclchem.plot.compositions ========================= .. py:module:: uclchem.plot.compositions .. autoapi-nested-parse:: Composition functions — each creates a complete figure by assembling panels. Module Contents --------------- Functions ~~~~~~~~~ .. autoapisummary:: uclchem.plot.compositions.create_abundance_plot uclchem.plot.compositions.plot_rate_summary uclchem.plot.compositions.plot_rates_deepdive .. py:function:: 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] Create a plot of the abundance of a list of species through time. :param df: Pandas dataframe containing the UCLCHEM output, see ``uclchem.analysis.read_output_file``, ``uclchem.model.load_model`` or ``uclchem.model.Model.get_dataframes``. :type df: pd.DataFrame :param species: list of strings containing species names. Using a $ instead of # or @ will plot the sum of surface and bulk abundances. :type species: list[str] :param figsize: Size of figure, width by height in inches. Defaults to (16, 9). :type figsize: tuple[float, float] :param plot_file: Path to file where figure will be saved. If None, figure is not saved. Defaults to None. :type plot_file: str | Path | None :param plot_kwargs: keyword arguments passed to ``ax.plot``. Default = None. :type plot_kwargs: dict[str, Any] | None :returns: * **fig** (*plt.Figure*) -- created Figure object * **ax** (*plt.Axes*) -- created axis object .. py:function:: 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] Create a summary of the top k production and destruction reactions. :param production_df: dataframe with reaction rates of formation reactions of species of interest :type production_df: pd.DataFrame :param destruction_df: dataframe with reaction rates of destruction reactions of species of interest :type destruction_df: pd.DataFrame :param step: time index of dataframes to plot. :type step: int :param xlabel: xlabel. Default: "Reaction rate (abundance wrt H / s)" :type xlabel: str :param top_k_rates: Plot top k formation and destruction reactions. Default: 5 :type top_k_rates: int :returns: **axs** -- axes of the plot :rtype: list[plt.Axes] .. py:function:: 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] 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. :param species: UCLCHEM species name to analyze, e.g. ``"HCO+"``. :type species: str :param physics_df: Physics DataFrame from :meth:`~uclchem.model.AbstractModel.get_dataframes`. :type physics_df: pd.DataFrame :param chemistry_df: Chemistry (abundance) DataFrame. :type chemistry_df: pd.DataFrame :param rate_constants_df: Rate-constants DataFrame (``with_rate_constants=True``). :type rate_constants_df: pd.DataFrame :param network: Pre-loaded :class:`~uclchem.makerates.network.Network`. If ``None`` the default network is loaded via :meth:`~uclchem.makerates.network.Network.from_csv`. :type network: Network | None :param filter_threshold: Reactions whose rate never exceeds this fraction of the per-step maximum within *filter_window* are excluded. Default: ``0.01``. :type filter_threshold: float :param filter_window: ``(t_min, t_max)`` in years used for reaction filtering and ranking. Default: ``(1e4, 1e6)``. :type filter_window: tuple[float, float] :param filter_freeze: If ``True`` (default), exclude freeze-out reactions. :type filter_freeze: bool :param max_species_show: Maximum number of companion species to draw in Panel A. Default: ``12``. :type max_species_show: int :param figsize: Figure width × height in inches. Ignored when *fig* is provided. Default: ``(8, 12)``. :type figsize: tuple[float, float] :param output_path: If provided, save the figure as both ``.pdf`` and ``.png``. Only meaningful when *fig* is a top-level :class:`~matplotlib.figure.Figure`. Default: ``None``. :type output_path: Path | str | None :param fig: Existing figure or sub-figure to draw into. Pass a :class:`~matplotlib.figure.SubFigure` obtained from ``parent.subfigures()`` to embed this plot inside a larger layout. If ``None`` (default) a new figure is created. :type fig: matplotlib.figure.FigureBase | None :param color_registry: 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. :type color_registry: dict[str, str] | None :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. .. rubric:: Notes .. todo:: Return a ``pd.DataFrame`` of per-reaction rates at the final timestep so callers can export to CSV / Excel.