Skip to content

Commit

Permalink
rewrite docs to cover new functions and kwarg changes
Browse files Browse the repository at this point in the history
  • Loading branch information
cadeduckworth committed Apr 15, 2023
1 parent bf1b05d commit 97267ac
Showing 1 changed file with 92 additions and 52 deletions.
144 changes: 92 additions & 52 deletions mdpow/workflows/dihedrals.py
Original file line number Diff line number Diff line change
Expand Up @@ -483,9 +483,12 @@ def periodic_angle_padding(df, padding=45):
return df_aug

def dihedral_violins(df, width=0.9, solvents=SOLVENTS_DEFAULT, plot_title=None):
'''Plots distributions of dihedral angles for one dihedral atom group
as violin plots, using as input the augmented :class:`pandas.DataFrame`
from :func:`~mdpow.workflows.dihedrals.periodic_angle_padding`.
'''Plots kernel density estimates (KDE) of dihedral angle frequencies for
one dihedral atom group as violin plots, using as input the augmented
:class:`pandas.DataFrame` from :func:`~mdpow.workflows.dihedrals.periodic_angle_padding`.
Output is converted to SVG by :func:`~mdpow.workflows.dihedrals.build_svg`
and final output is saved as PDF by :func:`~mdpow.workflows.dihedrals.plot_dihedral_violins`
:keywords:
Expand All @@ -499,13 +502,20 @@ def dihedral_violins(df, width=0.9, solvents=SOLVENTS_DEFAULT, plot_title=None):
*solvents*
The default solvents are documented under :data:`SOLVENTS_DEFAULT`.
*plot_title*
format: f'{molname}, {name[0]} {a} | ''{col_name}'
determined by,
.. seealso:: :func:`~mdpow.workflows.dihedrals.build_svg`
:returns:
*violin plot*
*g (violin plot)*
returns a :class:`seaborn.FacetGrid` object containing a violin plot of the
kernel density estimations (KDE) of the dihedral angle frequencies for each
relevant dihedral atom group in the molecule from the current MDPOW project
kernel density estimates (KDE) of the dihedral angle frequencies for each
dihedral atom group identified by :data:`SMARTS_DEFAULT`
'''

Expand Down Expand Up @@ -553,12 +563,50 @@ def dihedral_violins(df, width=0.9, solvents=SOLVENTS_DEFAULT, plot_title=None):

return g

def build_svg(mol, molname=None, name=None, ab_pairs=None,
def build_svg(mol, molname, ab_pairs, atom_group_selection,
solvents=SOLVENTS_DEFAULT, width=0.9):
'''Converts and combines figure components into an
SVG object to be converted and saved as a publication
quality PDF.
:keywords:
*mol*
:class:`rdkit.Chem.rdchem.Mol` object converted from `solute`
*molname*
molecule name to be used for labelling
plots, if different from `resname`
(in this case, carried over from an upstream
decision between the two)
*ab_pairs*
dictionary with key-value pair: '*#-*#-*#-*#': (atom_indices[i], bond_indices[i])
.. seealso:: :func:`~mdpow.workflows.dihedrals.get_paired_indices`
*atom_group_selection*
`name` of each section in the `groupby` series of atom group selections
.. seealso:: :func:`~mdpow.workflows.dihedrals.plot_dihedral_violins`
*solvents*
The default solvents are documented under :data:`SOLVENTS_DEFAULT`.
*width*
width of the violin element (>1 overlaps)
default: 0.9
:returns:
*fig*
:mod:`svgutils` SVG figure object
'''
# atoms
a = ab_pairs[name[0]][0]
a = ab_pairs[atom_group_selection[0]][0]
# bonds
b = ab_pairs[name[0]][1]
b = ab_pairs[atom_group_selection[0]][1]

drawer = rdMolDraw2D.MolDraw2DSVG(250, 250)
drawer.DrawMolecule(mol=mol, highlightAtoms=a, highlightBonds=b)
Expand All @@ -569,8 +617,8 @@ def build_svg(mol, molname=None, name=None, ab_pairs=None,
m = mol_svg.getroot()
m.scale(0.0125).moveto(21.8, 0.35)

plot_title = f'{molname}, {name[0]} {a} | ''{col_name}'
plot = dihedral_violins(name[1], width=width, solvents=solvents, plot_title=plot_title)
plot_title = f'{molname}, {atom_group_selection[0]} {a} | ''{col_name}'
plot = dihedral_violins(atom_group_selection[1], width=width, solvents=solvents, plot_title=plot_title)

plot_svg = svgutils.transform.from_mpl(plot)
p = plot_svg.getroot()
Expand All @@ -581,19 +629,19 @@ def build_svg(mol, molname=None, name=None, ab_pairs=None,

return fig

def plot_dihedral_violins(df, resname, mol, ab_pairs, figdir=None, molname=None,
def plot_dihedral_violins(df, resname, mol, ab_pairs, figdir, molname=None,
width=0.9, plot_pdf_width=PLOT_WIDTH_DEFAULT, solvents=SOLVENTS_DEFAULT):
'''Coordinates plotting and optionally saving figures for all dihedral
atom groups.
'''Coordinates plotting and saving figures for all dihedral atom groups.
Makes a subdirectory within the specified
`figdir` using `resname` or `molname` provided and saves violin plot
figur for each dihedral atom group separately.
Makes a subdirectory for the current project within the specified
`figdir` using `resname` or `molname` as title and saves production
quality PDFs for each dihedral atom group separately.
.. seealso::
:func:`~mdpow.workflows.dihedrals.automated_dihedral_analysis`,
:func:`~mdpow.workflows.dihedrals.dihedral_violins`
:func:`~mdpow.workflows.dihedrals.dihedral_violins`,
:func:`~mdpow.workflows.dihedrals.build_svg`
:keywords:
Expand All @@ -605,8 +653,16 @@ def plot_dihedral_violins(df, resname, mol, ab_pairs, figdir=None, molname=None,
`resname` for the molecule as defined in
the topology and trajectory
*mol*
:class:`rdkit.Chem.rdchem.Mol` object converted from `solute`
*ab_pairs*
dictionary with key-value pair: '*#-*#-*#-*#': (atom_indices[i], bond_indices[i])
.. seealso:: :func:`~mdpow.workflows.dihedrals.get_paired_indices`
*figdir*
optional, path to the location to save figures
path to the location to save figures
*molname*
molecule name to be used for labelling
Expand All @@ -618,19 +674,12 @@ def plot_dihedral_violins(df, resname, mol, ab_pairs, figdir=None, molname=None,
.. seealso:: :func:`~mdpow.workflows.dihedrals.dihedral_violins`
*solvents*
The default solvents are documented under :data:`SOLVENTS_DEFAULT`.
*plot_pdf_width*
The default value for width of plot output is described in detail under
:data:`PLOT_WIDTH_DEFAULT`.
:returns:
*violin plot*
returns a :class:`seaborn.FacetGrid` object containing a violin plot of the
kernel density estimations (KDE) of the dihedral angle frequencies for each
relevant dihedral atom group in the molecule from the current MDPOW project
*solvents*
The default solvents are documented under :data:`SOLVENTS_DEFAULT`.
'''

Expand All @@ -648,7 +697,7 @@ def plot_dihedral_violins(df, resname, mol, ab_pairs, figdir=None, molname=None,

for name in section:

fig = build_svg(mol=mol, molname=molname, name=name, ab_pairs=ab_pairs,
fig = build_svg(mol=mol, molname=molname, atom_group_selection=name, ab_pairs=ab_pairs,
solvents=solvents, width=width)

figfile = pathlib.Path(newdir) / f"{molname}_{name[0]}_violins.pdf"
Expand All @@ -661,8 +710,8 @@ def plot_dihedral_violins(df, resname, mol, ab_pairs, figdir=None, molname=None,

return None

def automated_dihedral_analysis(dirname=None, df_save_dir=None, figdir=None,
resname=None, molname=None,
def automated_dihedral_analysis(dirname, figdir, resname,
df_save_dir=None, molname=None,
SMARTS=SMARTS_DEFAULT, plot_pdf_width=PLOT_WIDTH_DEFAULT,
dataframe=None, padding=45, width=0.9,
solvents=SOLVENTS_DEFAULT,
Expand All @@ -674,13 +723,11 @@ def automated_dihedral_analysis(dirname=None, df_save_dir=None, figdir=None,
For one MDPOW project, automatically determines all relevant dihedral atom groups
in the molecule, runs :class:`~mdpow.analysis.dihedral.DihedralAnalysis` for each group,
pads the dihedral angles from analysis results for all groups to maintain periodicity,
creates violin plots of dihedral angle frequencies for each group, separately, from the
padded results.
pads the dihedral angles to maintain periodicity, creates violin plots of dihedral angle
frequencies (KDEs), and saves publication quality PDF figures for each group, separately.
Optionally saves all pre-padded :class:`~mdpow.analysis.dihedral.DihedralAnalysis` results
as a single :class:`pandas.DataFrame`, and separate violin plots for each dihedral atom group
in `df_save_dir`, and `figdir` directories provided, respectively.
as a single :class:`pandas.DataFrame` in `df_save_dir` provided.
:keywords:
Expand All @@ -694,23 +741,27 @@ def automated_dihedral_analysis(dirname=None, df_save_dir=None, figdir=None,
and .xtc files for trajectory. It will default to using the tpr file
available.
*df_save_dir*
optional, path to the location to save results :class:`pandas.DataFrame`
*figdir*
optional, path to the location to save figures
path to the location to save figures
*resname*
`resname` for the molecule as defined in
the topology and trajectory
*df_save_dir*
optional, path to the location to save results :class:`pandas.DataFrame`
*molname*
molecule name to be used for labelling
plots, if different from `resname`
*SMARTS*
The default SMARTS string is described in detail under :data:`SMARTS_DEFAULT`.
*plot_pdf_width*
The default value for width of plot output is described in detail under
:data:`PLOT_WIDTH_DEFAULT`.
*dataframe*
optional, if :class:`~mdpow.analysis.dihedral.DihedralAnalysis`
was done prior, then results :class:`pandas.DataFrame` can be
Expand All @@ -734,23 +785,12 @@ def automated_dihedral_analysis(dirname=None, df_save_dir=None, figdir=None,
*interactions*
The default interactions are documented under :data:`INTERACTIONS_DEFAULT`.
*plot_pdf_width*
The default value for width of plot output is described in detail under
:data:`PLOT_WIDTH_DEFAULT`.
*start, stop, step*
arguments passed to :func:`~mdpow.analysis.ensemble.EnsembleAnalysis.run`,
as parameters for iterating through the trajectories of the current ensemble
.. seealso:: :class:`~mdpow.analysis.ensemble.EnsembleAnalysis`
:returns:
*violin plot*
returns a :class:`seaborn.FacetGrid` object containing a violin plot of the
kernel density estimations (KDE) of the dihedral angle frequencies for each
relevant dihedral atom group in the molecule from the current MDPOW project
.. rubric:: Example
Typical Workflow::
Expand Down

0 comments on commit 97267ac

Please sign in to comment.