shnitsel.vis.plot#

Submodules#

Functions#

biplot_kde(frames, *ids[, pca_data, state_selection, ...])

Generates a biplot that visualizes PCA projections and kernel density estimates (KDE)

plot_cdf_for_kde(z, contour_level[, ax])

Plot the cumulative density for a KDE, to show what

ski_plots(spectra[, threshold])

Plot spectra for different times on top of each other,

pcm_plots(spectra)

Represent fosc as colour in a plot of fosc against time and energy.

timeplot(data[, ax, trajs, sep, time_coord])

Plot some property of one or many trajectories over time,

Package Contents#

biplot_kde(frames, *ids, pca_data=None, state_selection=None, structure_selection=None, mol=None, geo_kde_ranges=None, scatter_color_property='time', geo_feature=None, geo_cmap='PRGn', time_cmap='cividis', contour_levels=None, contour_colors=None, contour_fill=True, num_bins=4, fig=None, center_mean=False)#

Generates a biplot that visualizes PCA projections and kernel density estimates (KDE) of a property (distance, angle, dihedral angle) describing the geometry of specified atoms. The property is chosen based on the number of atoms specified:

  • 2 atoms => distance

  • 3 atoms => angle

  • 4 atoms => dihedral angle

Parameters:

  • frames (xarray.Dataset | shnitsel.data.dataset_containers.shared.ShnitselDataset | shnitsel.data.tree.node.TreeNode[Any, shnitsel.data.dataset_containers.shared.ShnitselDataset | xarray.Dataset]) – A dataset containing trajectory frames with atomic coordinates. This needs to correspond to the data that was the input to pca_data if that parameter is provided.

  • *ids (int) – Indices for atoms to be used in geo_feature if geo_feature is not set. Note that pyramidalization angles cannot reliably be provided in this format.

  • pca_data (PCAResult, optional) – A PCA result to use for the analysis. If not provided, will perform PCA analysis based on structure_selection or a generic pairwise distance PCA on frames. Accordingly, if provided, the parameter frames needs to correspond to the input provided to obtain the value in `

  • structure_selection (StructureSelection | StructureSelectionDescriptor, optional) – An optional selection of features/structure to use for the PCA analysis.

  • geo_kde_ranges (Sequence[tuple[float, float]], optional) – A Sequence of tuples representing ranges. A KDE is plotted for each range, indicating the distribution of points for which the value of the geometry feature falls in that range. Default values are chosen depending on the type of feature that should be analyzed.

  • contour_levels (int | list[float], optional) – Contour levels for the KDE plot. Either the number of contour levels as an int or the list of floating point values at which the contour lines should be drawn. Defaults to [0.08, 1]. This parameter is passed to matplotlib.axes.Axes.contour.

  • scatter_color_property ({'time', 'geo'}, default='time') – Must be one of ‘time’ or ‘geo’. If ‘time’, the scatter-points will be colored based on the time coordinate; if ‘geo’, the scatter-points will be colored based on the relevant geometry feature (see above).

  • geo_cmap (str, default = 'PRGn') – The Colormap to use for the noodleplot, if scatter_color='geo'; this also determines contour colors unless contour_colors is set.

  • time_cmap (str, default = 'cividis') – The Colormap to use for the noodleplot, if scatter_color='time'.

  • contour_fill (bool, default = True) – Whether to plot filled contours (contour_fill=True, uses ax.contourf) or just contour lines (contour_fill=False, uses ax.contour).

  • contour_colors (list[str], optional) – An iterable (not a Colormap) of colours (in a format matplotlib will accept) to use for the contours. By default, the geo_cmap will be used; this defaults to ‘PRGn’.

  • num_bins ({1, 2, 3, 4}, default = 4) – number of bins to be visualized, must be an integer between 1 and 4

  • fig (mpl.figure.Figure, optional) – matplotlib.figure.Figure object into which the plot will be drawn; if not provided, one will be created using plt.figure(layout='constrained')

  • center_mean (bool, default = False) – Flag whether PCA data should be mean-centered before analysis. Defaults to False.

  • state_selection (shnitsel.filtering.state_selection.StateSelection | shnitsel.filtering.state_selection.StateSelectionDescriptor | None)

  • mol (rdkit.Chem.Mol | None)

  • geo_feature (shnitsel.filtering.structure_selection.BondDescriptor | shnitsel.filtering.structure_selection.AngleDescriptor | shnitsel.filtering.structure_selection.DihedralDescriptor | shnitsel.filtering.structure_selection.PyramidsDescriptor | None)

Returns:

  • Figure – The single figure of the PCA result, if the PCA result was not provided as a tree or on-the go PCA did not yield a tree result.

  • Sequence[Figure] – The sequence of all figures, one for each individual PCA result if the provided or obtained PCA result was a tree structure.

Return type:

matplotlib.figure.Figure | Sequence[matplotlib.figure.Figure]

Notes

  • Computes a geometric property of the specified atoms across all frames.

  • Uses kernel density estimation (KDE) to analyze the distance distributions.

  • Performs PCA on trajectory pairwise distances and visualizes clustering of structural changes.

  • Produces a figure with PCA projection, cluster analysis, and KDE plots.

plot_cdf_for_kde(z, contour_level, ax=None)#

Plot the cumulative density for a KDE, to show what proportion of points are contained by contours at a given density level

Parameters:

  • z (np.ndarray) – The values from the kernel evaluated over the input space

  • contour_level (float) – The cumulative density corresponding to this level will be marked on the graph

  • ax (Axes, optional) – A matplotlib.axes.Axes object into which to plot. (If not provided, one will be created.)

Returns:

The proportion of points contained by contours placed at density level

Return type:

y

ski_plots(spectra, threshold=np.inf)#

Plot spectra for different times on top of each other, along with a dashed “ski”-line that tracks the maximum. One plot per statecomb; plots stacked vertically. Expected to be used on data produced by spectra.spectra_all_times.

Parameters:

  • spectra (xarray.DataArray) – DataArray containing fosc values organized along ‘energy’, ‘time’ and ‘statecomb’ dimensions.

  • threshold (float) – The “ski” line will not be drawn between successive points for which the change in energy-coordinate is greater than this.

Return type:

Figure object corresponding to plot.

pcm_plots(spectra)#

Represent fosc as colour in a plot of fosc against time and energy. The colour scale is logarithmic. One plot per statecomb; plots stacked horizontally. Expected to be used on data produced by spectra.spectra_all_times.

Parameters:

spectra (xarray.DataArray) – DataArray containing fosc values organized along ‘energy’, ‘time’ and ‘statecomb’ dimensions.

Return type:

Figure object corresponding to plot.

Examples

>>> import shnitsel as st
>>> from shnitsel.core.plot import spectra3d
>>> spectra_data = (
        st.io.read(path)
        .st.get_inter_state()
        .st.assign_fosc()
        .st.spectra_all_times())
>>> spectra3d.pcm_plots(spectra_data)
timeplot(data, ax=None, trajs=None, sep=False, time_coord='time')#

Plot some property of one or many trajectories over time, possibly aggregating over trajectories, and distinguishing different states/statecombs if applicable.

Parameters:

  • data (xarray.DataArray) – Data to plot

  • ax (matplotlib.pyplot.Axes | None) – A matplotlib Axes onto which to plot; if not provided, one will be created.

  • trajs (Literal['ci', 'shade', 'conv', None]) –

    How to aggregate trajectories, if at all:

    • None (default): do not aggregate

    • ’ci’: aggregate by confidence interval

    • ’shade’: use colour to represent overlap

      density using the datashader library (to produce what is sometimes called a hairplot)

  • sep (bool) – Whether to plot different states/statecombs separately; this will be done regardless when using trajs='shade'.

Return type:

The Axes object used

Raises:

  • ValueError –

    • If data has both ‘state’ and ‘statecomb’ dimensions.

    • If ax is passed when multiple Axes will be required

      as states/statecombs are to be plotted separately.

    • If trajs is set to a value other than None, ‘ci’ or ‘shade’

  • NotImplementedError – If trajs='conv' is used