uclchem.analysis ================ .. py:module:: uclchem.analysis Module Contents --------------- Functions ~~~~~~~~~ .. autoapisummary:: uclchem.analysis.analysis uclchem.analysis.analyze_element_per_phase uclchem.analysis.check_element_conservation uclchem.analysis.construct_incidence uclchem.analysis.create_abundance_plot uclchem.analysis.derive_phase_from_name uclchem.analysis.get_change_df uclchem.analysis.get_production_and_destruction uclchem.analysis.get_total_swap uclchem.analysis.plot_species uclchem.analysis.rates_to_dy_and_flux uclchem.analysis.read_analysis uclchem.analysis.read_output_file uclchem.analysis.read_rate_file uclchem.analysis.total_element_abundance Attributes ~~~~~~~~~~ .. autoapisummary:: uclchem.analysis.elementList .. py:function:: analysis(species_name, rates, output_file, rate_threshold=0.99) A function which loops over every time step in an output file and finds the rate of change of a species at that time due to each of the reactions it is involved in. From this, the most important reactions are identified and printed to file. This can be used to understand the chemical reason behind a species' behaviour. :param species_name: Name of species to be analysed :type species_name: str :param result_file: The path to the file containing the UCLCHEM output :type result_file: str :param output_file: The path to the file where the analysis output will be written :type output_file: str :param rate_threshold: Analysis output will contain the only the most efficient reactions that are responsible for rate_threshold of the total production and destruction rate. Defaults to 0.99. :type rate_threshold: float,optional .. py:function:: analyze_element_per_phase(element, df) Calculates that the total elemental abundance of a species as a function of time. Allows you to check conservation. :param element: Name of element :type element: str :param df: DataFrame from `read_output_file()` :type df: pandas.DataFrame :returns: Total abundance of element for all time steps in df. :rtype: pandas.Series .. py:function:: check_element_conservation(df, element_list=['H', 'N', 'C', 'O'], percent=True) Check the conservation of major element by comparing total abundance at start and end of model :param df: UCLCHEM output in format from `read_output_file` :type df: pandas.DataFrame :param element_list: List of elements to check. Defaults to ["H", "N", "C", "O"]. :type element_list: list, optional :returns: Dictionary containing the change in the total abundance of each element as a fraction of initial value :rtype: dict .. py:function:: construct_incidence(species: List[uclchem.makerates.species.Species], reactions: List[uclchem.makerates.Reaction]) -> numpy.ndarray Construct the incidence matrix, a matrix that describes the in and out degree for each of the reactions; useful to matrix multiply by the indvidual fluxes per reaction to obtain a flux (dy) per species. :param species: A list of species S :type species: List[Species] :param reactions: The list of reactions S :type reactions: List[Reaction] :returns: A RxS incidence matrix :rtype: np.ndarray .. py:function:: create_abundance_plot(df, species, figsize=(16, 9), plot_file=None) Create a plot of the abundance of a list of species through time. :param df: Pandas dataframe containing the UCLCHEM output, see `read_output_file` :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 :param figsize: Size of figure, width by height in inches. Defaults to (16, 9). :type figsize: tuple, optional :param plot_file: Path to file where figure will be saved. If None, figure is not saved. Defaults to None. :type plot_file: str, optional :returns: matplotlib figure and axis objects :rtype: fig,ax .. py:function:: derive_phase_from_name(name) -> str .. py:function:: get_change_df(rate_df: pandas.DataFrame, species: str, on_grain: bool = False) -> pandas.DataFrame From a dataframe containing all the reaction rates, get the change of a species over time, due to each reaction. :param rate_df: dataframe containing physical parameters and reaction rates over time :type rate_df: pd.DataFrame :param species: species to get the change over time :type species: str :param on_grain: whether to analyse the ice phase of this species :type on_grain: bool :returns: change of species over time due to each reaction the species is involved in :rtype: change_df (pd.DataFrame) .. py:function:: get_production_and_destruction(species: str, rates_or_flux: pandas.DataFrame) .. py:function:: get_total_swap(rates: pandas.DataFrame, abundances: pandas.DataFrame, reactions: List[uclchem.makerates.Reaction]) -> numpy.ndarray Obtain the amount of 'random' swapping per timestep :param rates: The rates obtained from running an UCLCHEM model :type rates: pd.DataFrame :param abundances: The abundances obtained from running an UCLCHEM model :type abundances: pd.DataFrame :param reactions: The reactions used in UCLCHEM :type reactions: List[Reaction] :returns: The total swap per timestep :rtype: np.ndarray .. py:function:: plot_species(ax, df, species, legend=True, **plot_kwargs) Plot the abundance of a list of species through time directly onto an axis. :param ax: An axis object to plot on :type ax: pyplot.axis :param df: A dataframe created by `read_output_file` :type df: pd.DataFrame :param species: A list of species names to be plotted. If species name starts with "$" instead of # or @, plots the sum of surface and bulk abundances :type species: str :returns: Modified input axis is returned :rtype: pyplot.axis .. py:function:: rates_to_dy_and_flux(physics: pandas.DataFrame, abundances: pandas.DataFrame, rates: pandas.DataFrame, network: uclchem.makerates.network.Network = None, species: list[uclchem.makerates.species.Species] = None, reactions: list[uclchem.makerates.Reaction] = None) -> tuple[pandas.DataFrame, pandas.DataFrame] Apply postprocessing to obtain the equivalent of GETYDOT from the fortran side; It returns two dataframes: - ydot: the RHS that is solved in UCLCHEM at every output timestep - flux_by_reaction: the individual terms that result in ydot when multiplied by the incidence matrix :param physics: The physics output from running a model :type physics: pd.DataFrame :param abundances: The abundances output from running a model :type abundances: pd.DataFrame :param rates: The rates output from running a model :type rates: pd.DataFrame :param network: The reaction network used to postprocess the rates. Defaults to None. :type network: Network, optional :param species: The species used to postprocess the rates . Defaults to None. :type species: list[Species], optional :param reactions: The reactions used to postprocess the rates. Defaults to None. :type reactions: list[Reaction], optional :returns: dy, flux_by_reaction. :rtype: tuple[pd.DataFrame, pd.DataFrame] .. py:function:: read_analysis(filepath, species) .. py:function:: read_output_file(output_file) Read the output of a UCLCHEM run created with the outputFile parameter into a pandas DataFrame :param output_file: path to file containing a full UCLCHEM output :type output_file: str :returns: A dataframe containing the abundances and physical parameters of the model at every time step. :rtype: pandas.DataFrame .. py:function:: read_rate_file(rate_file) Read the output of a UCLCHEM run created with the rateFile parameter into a pandas DataFrame :param rate_file: path to file containing the UCLCHEM reaction rates. :type rate_file: str :returns: A dataframe containing the physical parameters, and reaction rates (s-1) at each timestep. :rtype: pandas.DataFrame .. py:function:: total_element_abundance(element, df) Calculates that the total elemental abundance of a species as a function of time. Allows you to check conservation. :param element: Name of element :type element: str :param df: DataFrame from `read_output_file()` :type df: pandas.DataFrame :returns: Total abundance of element for all time steps in df. :rtype: pandas.Series .. py:data:: elementList :value: ['H', 'D', 'HE', 'C', 'N', 'O', 'F', 'P', 'S', 'CL', 'LI', 'NA', 'MG', 'SI', 'PAH', '15N',...