diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index 3ab28c1e..ab9b1284 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.11.1","generation_timestamp":"2024-10-18T20:04:53","documenter_version":"1.7.0"}} \ No newline at end of file +{"documenter":{"julia_version":"1.11.1","generation_timestamp":"2024-10-18T20:10:42","documenter_version":"1.7.0"}} \ No newline at end of file diff --git a/dev/contributions/index.html b/dev/contributions/index.html index ef7baaa1..2ad2101c 100644 --- a/dev/contributions/index.html +++ b/dev/contributions/index.html @@ -44,4 +44,4 @@ julia> ca_cb = contributions(results, SoluteGroup(["CA", "CB"])); # contribution of CA and CB atoms to the MDDF -julia> ca_cb = contributions(results, SoluteGroup(["CA", "CB"]); type=:coordination_number); # contribution of CA and CB atoms to the coordination numbersource +julia> ca_cb = contributions(results, SoluteGroup(["CA", "CB"]); type=:coordination_number); # contribution of CA and CB atoms to the coordination numbersource diff --git a/dev/example1/index.html b/dev/example1/index.html index 4e836fe8..04cbb53d 100644 --- a/dev/example1/index.html +++ b/dev/example1/index.html @@ -153,4 +153,4 @@

In the figure on the left, the points in space around the protein are selected with the following properties: distance from the protein smaller than 2.0Å and relative contribution to the MDDF at the corresponding distance of at least 10% of the maximum contribution. Thus, we are selecting the regions of the protein corresponding to the most stable hydrogen-bonding interactions. The color of the points is the contribution to the MDDF, from blue to red. Thus, the most reddish-points corresponds to the regions where the most stable hydrogen bonds were formed. We have marked two regions here, on opposite sides of the protein, with arrows.

Clicking on those points we obtain which are the atoms of the protein contributing to the MDDF at that region. In particular, the arrow on the right points to the strongest red region, which corresponds to an Aspartic acid. These residues are shown explicitly under the density (represented as a transparent surface) on the figure in the center.

The figure on the right displays, overlapped with the hydrogen-bonding residues, the most important contributions to the second peak of the distribution, corresponding to distances from the protein between 2.0 and 3.5Å. Notably, the regions involved are different from the ones forming hydrogen bonds, indicating that non-specific interactions with the protein (and not a second solvation shell) are responsible for the second peak.

How to run this example:

Assuming that the input files are available in the script directory, just run the script with:

julia density3D.jl

Alternatively, open Julia and copy/paste or the commands in density3D.jl or use include("./density3D.jl"). These options will allow you to remain on the Julia section with access to the grid data structure that was generated and corresponds to the output grid.pdb file.

This will create the grid.pdb file. Here we provide a previously setup VMD session that contains the data with the visualization choices used to generate the figure above. Load it with:

vmd -e grid.vmd

A short tutorial video showing how to open the input and output PDB files in VMD and produce images of the density is available here:

-
+ diff --git a/dev/example2/index.html b/dev/example2/index.html index f309c11b..daebaead 100644 --- a/dev/example2/index.html +++ b/dev/example2/index.html @@ -250,4 +250,4 @@ savefig("./map2D_acr.png") println("Plot saved to map2D_acr.png")

Output

The terminal methyl groups interact strongly with DMF, and strong local density augmentations are visible in particular on the amine groups. These occur at less than 2.0Angs and are characteristic of hydrogen-bond interactions. Interestingly, the DMF molecules are excluded from the aliphatic and carbonyl groups of the polymer, relative to the other groups.

Finally, it is noticeable that the central mer is more weakly solvated by DMF than the mers approaching the extremes of the polymer chain. This is likely a result of the partial folding of the polymer, that protects that central mers from the solvent in a fraction of the polymer configurations.

-

References

Molecules built with JSME: B. Bienfait and P. Ertl, JSME: a free molecule editor in JavaScript, Journal of Cheminformatics 5:24 (2013) http://biomodel.uah.es/en/DIY/JSME/draw.en.htm

The system was built with Packmol.

The simulations were perfomed with NAMD, with CHARMM36 parameters.

+

References

Molecules built with JSME: B. Bienfait and P. Ertl, JSME: a free molecule editor in JavaScript, Journal of Cheminformatics 5:24 (2013) http://biomodel.uah.es/en/DIY/JSME/draw.en.htm

The system was built with Packmol.

The simulations were perfomed with NAMD, with CHARMM36 parameters.

diff --git a/dev/example3/index.html b/dev/example3/index.html index 74cf795c..40b92409 100644 --- a/dev/example3/index.html +++ b/dev/example3/index.html @@ -512,4 +512,4 @@ annotate!(12, 2.7, text("Palmitoyl", :left, 12, plot_font), subplot=2) savefig("POPC_water_chains.png") -println("The plot was saved as POPC_water_chains.png")

Ethanol displays an important density augmentation at the vicinity of the carbonyl that follows the glycerol group, and accumulates on the proximity of the aliphatic chain. The density of ethanol decreases as one advances into the aliphatic chain, displaying a minimum around the insaturation in the Oleoyl chain. The terminal methyl group of both chains display a greater solvation by ethanol, suggesting the twisting of the aliphatic chain expose these terminal groups to membrane depth where ethanol is already abundant.

The equivalent maps for water are strikingly different, and show that water is excluded from the interior of the membrane:

References

Membrane built with the VMD membrane plugin.

Water and ethanol layers added with Packmol.

The simulations were performed with NAMD, with CHARMM36 parameters.

Density of the ethanol-water mixture from: https://wissen.science-and-fun.de/chemistry/chemistry/density-tables/ethanol-water-mixtures/

+println("The plot was saved as POPC_water_chains.png")

Ethanol displays an important density augmentation at the vicinity of the carbonyl that follows the glycerol group, and accumulates on the proximity of the aliphatic chain. The density of ethanol decreases as one advances into the aliphatic chain, displaying a minimum around the insaturation in the Oleoyl chain. The terminal methyl group of both chains display a greater solvation by ethanol, suggesting the twisting of the aliphatic chain expose these terminal groups to membrane depth where ethanol is already abundant.

The equivalent maps for water are strikingly different, and show that water is excluded from the interior of the membrane:

References

Membrane built with the VMD membrane plugin.

Water and ethanol layers added with Packmol.

The simulations were performed with NAMD, with CHARMM36 parameters.

Density of the ethanol-water mixture from: https://wissen.science-and-fun.de/chemistry/chemistry/density-tables/ethanol-water-mixtures/

diff --git a/dev/example4/index.html b/dev/example4/index.html index 3ebcbbc8..93784fd1 100644 --- a/dev/example4/index.html +++ b/dev/example4/index.html @@ -279,4 +279,4 @@ ) savefig("./GlycerolWater_map.png") -println("Plot saved to GlycerolWater_map.png")

The interesting result here is that the $\mathrm{CH}$ group of glycerol is protected from both solvents. There is a strong density augmentation at the vicinity of hydroxyl groups, and the second peak of the MDDFs is clearly associated to interactions with the $\mathrm{CH_2}$ groups.

+println("Plot saved to GlycerolWater_map.png")

The interesting result here is that the $\mathrm{CH}$ group of glycerol is protected from both solvents. There is a strong density augmentation at the vicinity of hydroxyl groups, and the second peak of the MDDFs is clearly associated to interactions with the $\mathrm{CH_2}$ groups.

diff --git a/dev/examples/index.html b/dev/examples/index.html index 34cfa81a..deed0807 100644 --- a/dev/examples/index.html +++ b/dev/examples/index.html @@ -2,4 +2,4 @@ Examples: · ComplexMixtures.jl
GitHub

Examples

List of examples

How to run these examples

1 Download and install Julia

To run the scripts, we suggest the following procedure:

  1. Create a directory, for example example1.
  2. Copy the required data files, indicated in each example.
  3. Launch julia in that directory, activate the directory environment, and install the required packages. This is done by launching Julia and executing:
    import Pkg 
 Pkg.activate(".")
 Pkg.add(["ComplexMixtures", "PDBTools", "Plots", "LaTeXStrings", "EasyFit"])
-exit()
  4. Copy the code of each script in to a file, and execute with:
    julia -t auto script.jl
    Alternativelly (and perhaps preferrably), copy line by line the content of the script into the Julia REPL, to follow each step of the calculation. For a more advanced Julia usage, we suggest the VSCode IDE with the Julia Language Support extension.
+exit()
  • Copy the code of each script in to a file, and execute with:
    julia -t auto script.jl
    Alternativelly (and perhaps preferrably), copy line by line the content of the script into the Julia REPL, to follow each step of the calculation. For a more advanced Julia usage, we suggest the VSCode IDE with the Julia Language Support extension.
    • diff --git a/dev/index.html b/dev/index.html index 4986bdfa..2c9a6521 100644 --- a/dev/index.html +++ b/dev/index.html @@ -16,4 +16,4 @@
    Preferential interaction parameters obtained for the solvation of a protein by ionic liquids.

    -

    In particular, the plot shows that besides being preferentially excluded from the protein surface at high concentrations in the native state, suggesting protein folding stabilization, the interactions with the protein in the denatured states are stronger, leading to denaturation at all concentrations.

    References

    Please cite the following articles if the package was useful to you:

    See also

    Seminar

    Applications

    +

    In particular, the plot shows that besides being preferentially excluded from the protein surface at high concentrations in the native state, suggesting protein folding stabilization, the interactions with the protein in the denatured states are stronger, leading to denaturation at all concentrations.

    References

    Please cite the following articles if the package was useful to you:

    See also

    Seminar

    Applications

    diff --git a/dev/installation/index.html b/dev/installation/index.html index 1fff6db2..3b11fadd 100644 --- a/dev/installation/index.html +++ b/dev/installation/index.html @@ -11,4 +11,4 @@ using LaTeXStrings # etc ...

    And the script can be run with julia -t auto script.jl (where -t auto allows for multi-threading), or included in julia with julia> include("./scritp.jl"), as described in the next section.

    Tip

    By loading the package with 

    using ComplexMixtures

    the most common functions of the package become readily available by their direct name, for example mddf(...).

    If you don't want to bring the functions into the scope of your script, use

    import ComplexMixtures

    Then, the functions of the package are called, for example, using ComplexMixtures.mddf(...). To avoid having to write ComplexMixtures all the time, define an acronym. For example:

    import ComplexMixtures as CM
-CM.mddf(...)
    +CM.mddf(...) diff --git a/dev/mddf/index.html b/dev/mddf/index.html index 29c7e9b1..2aac4881 100644 --- a/dev/mddf/index.html +++ b/dev/mddf/index.html @@ -21,8 +21,8 @@ julia> options = Options(lastframe=10, bulk_range=(10.0, 15.0)); -julia> results = mddf(trajectory, options)source

    The mddf functions is run with, for example:

    results = mddf(trajectory, Options(bulk_range=(10.0, 15.0)))

    The MDDF along with other results, like the corresponding KB integrals, are returned in the results data structure, which is described in the next section.

    It is possible to tune several options of the calculation, by setting the Options data structure with user-defined values in advance. The most common parameters to be set by the user are bulk_range and stride.

    stride defines if some frames will be skip during the calculation (for speedup). For example, if stride=5, only one in five frames will be considered. Adjust stride with: 

    options = Options(stride=5, bulk_range=(10.0, 15.0))
+julia> results = mddf(trajectory, options)
    source

    The mddf functions is run with, for example:

    results = mddf(trajectory, Options(bulk_range=(10.0, 15.0)))

    The MDDF along with other results, like the corresponding KB integrals, are returned in the results data structure, which is described in the next section.

    It is possible to tune several options of the calculation, by setting the Options data structure with user-defined values in advance. The most common parameters to be set by the user are bulk_range and stride.

    stride defines if some frames will be skip during the calculation (for speedup). For example, if stride=5, only one in five frames will be considered. Adjust stride with: 

    options = Options(stride=5, bulk_range=(10.0, 15.0))
 results = mddf(trajectory, options)
    Note

    bulk_range defines the subset of the system, as defined according to a range of distances from the solute, that are to be considered as the bulk solution. Within this range of distances, the user believes that the reference solute molecule does not significantly affect anymore the structure of the solvent.

    By default, all molecules above 10 Angstroms from the solute are considered bulk molecules (corresponding to Options(dbulk=10.0)), but it is highly recommended to use a manual definition of bulk_range.

    The definition of a range of distances within the system to compute the bulk density is adequate because this system subset is then an open system with a solvent molecule reservoir. The adequate choice of bulk_range can be inspected by the proper convergence of the distribution functions (which must converge to 1.0) and a proper convergence of the KB integrals.

    The bulk_range option was introduced in version 2.1.0.

    See the Options section for further details and other options to set.

    Coordination numbers only

    The coordination_number function, called with the same arguments as the mddf function, can be used to compute coordination numbers without the normalization required for the MDDF:

    ComplexMixtures.coordination_number — Method
    coordination_number(
     trajectory::Trajectory, options::Options;
     kargs...
-)

    Computes the coordination numbers for each solute molecule in the trajectory, given the Trajectory. This is an auxiliary function of the ComplexMixtures package, which is used to compute coordination numbers when the normalization of the distribution is not possible or needed.

    The output is a Result structure, which contains the data as the result of a call to mddf, except that all counters which require normalization of the distribution will be zero. In summary, this result data structure can be used to compute the coordination numbers, but not the MDDF, RDF, or KB integrals.

    The keyword arguments are the same as for the mddf function, and are passed to it. This function is a wrapper around mddf with the coordination_number_only keyword set to true.

    source

    This function can be useful if the normalization is not possible or meaningful. The computation is much faster if the normalization is not necessary.

    Note

    The mddf, kb, and random count parameters will be empty when using this options, and are meaningless.

    +)

    Computes the coordination numbers for each solute molecule in the trajectory, given the Trajectory. This is an auxiliary function of the ComplexMixtures package, which is used to compute coordination numbers when the normalization of the distribution is not possible or needed.

    The output is a Result structure, which contains the data as the result of a call to mddf, except that all counters which require normalization of the distribution will be zero. In summary, this result data structure can be used to compute the coordination numbers, but not the MDDF, RDF, or KB integrals.

    The keyword arguments are the same as for the mddf function, and are passed to it. This function is a wrapper around mddf with the coordination_number_only keyword set to true.

    source

    This function can be useful if the normalization is not possible or meaningful. The computation is much faster if the normalization is not necessary.

    Note

    The mddf, kb, and random count parameters will be empty when using this options, and are meaningless.

    diff --git a/dev/multiple/index.html b/dev/multiple/index.html index 251661eb..b6761d11 100644 --- a/dev/multiple/index.html +++ b/dev/multiple/index.html @@ -18,4 +18,4 @@ 0.5 0.25 0.25 -

    It is not a bad idea to check if that is what you were expecting.

    +

    It is not a bad idea to check if that is what you were expecting.

    diff --git a/dev/options/index.html b/dev/options/index.html index f7902a73..f4b13840 100644 --- a/dev/options/index.html +++ b/dev/options/index.html @@ -18,4 +18,4 @@ StableRNG::Bool = false, nthreads::Int = 0, silent::Bool = false -)

    Create an Options object with the specified options.

    source +)

    Create an Options object with the specified options.

    source diff --git a/dev/parallel/index.html b/dev/parallel/index.html index f5b9a647..1c1d4550 100644 --- a/dev/parallel/index.html +++ b/dev/parallel/index.html @@ -1,3 +1,3 @@ Parallel execution · ComplexMixtures.jl
    GitHub

    Parallel execution

    It is highly recommended to run MDDF calculations in parallel, using multiple processors of a single computer. To run the computation in parallel, initialize julia with the -t N option, where N is the number of processes to be used. For example, to use 8 parallel processes, use:

    julia -t 8 example.jl

    The computation will use a number of parallel processes equal to N. Use -t auto to automatically pick the number of threads available in your computer.

    Optimal number of threads

    The number of threads used for computation of the MDDF is the number of threads available to Julia. Many computers allow hyperthreading, and not necessarily this this beneficial for the execution of this package. The optimal number of threads may vary. Some newer CPUs have "energy saving" cores, which are also relatively slow.

    Independently of the number of threads initialized with the -t command-line parameter, the number of processes launched by ComplexMixtures in any given computation can be adjusted by the Options(nthreads=N) option. This won't provide any speedup if the optional number of threads is greater than the number of threads available to Julia at runtime.

    Memory issues

    If the calculations get Killed by no apparent reason, that is probably because you are running out of memory because of the many parallel computations running.

    The main reason for memory exhaustion is the annotation of the contributions of each atom of the solute molecules to the total counts. By default, in a parallel run, one copy of such data structures is saved for each thread. This might be an issue if the solute is molecular structure with many hundreds of thousand atoms, and if the number of CPUs available is very high, but memory is not as abundant.

    There are different ways to deal with this issue:

    1. Use predefined groups, to reduce the size of the group array contributions.
    2. Use the low_memory=true option the call to mddf (for example with mddf(traj, options; low_memory=true).
    3. Reduce the number of threads used (with Options(nthreads=N)).
    4. Increase the frequency of garbage collection calls:
      options = Options(GC=true, GC_threshold=0.5)
-R = mddf(trajectory, options)
      The GC_threshold=0.5 indicates that if the free memory is smaller than 50% of the total memory of the machine, a garbage-collection run will occur. The default parameters are GC=true and GC_threshold=0.3.
    +R = mddf(trajectory, options)The GC_threshold=0.5 indicates that if the free memory is smaller than 50% of the total memory of the machine, a garbage-collection run will occur. The default parameters are GC=true and GC_threshold=0.3. diff --git a/dev/python/index.html b/dev/python/index.html index 91c9fff6..f174dba0 100644 --- a/dev/python/index.html +++ b/dev/python/index.html @@ -83,4 +83,4 @@ plt.legend() plt.xlabel("distance / Angs") plt.ylabel("MDDF") -plt.savefig("group_contributions.png")

    Despite the low sampling, it is clear that hydroxyl groups contribute to the greter peak of the distribution, at hydrogen-bonding distances, as expected. The contributions of the aliphatic groups to the MDDF occurs at longer distances, associated to non-specific interactions.

    Note

    The syntax here diverges from the Julia-only examples by requiring the lists of names to be converted to Julia arrays, which happens by using the cm.list(python_list) function calls.

    +plt.savefig("group_contributions.png")

    Despite the low sampling, it is clear that hydroxyl groups contribute to the greter peak of the distribution, at hydrogen-bonding distances, as expected. The contributions of the aliphatic groups to the MDDF occurs at longer distances, associated to non-specific interactions.

    Note

    The syntax here diverges from the Julia-only examples by requiring the lists of names to be converted to Julia arrays, which happens by using the cm.list(python_list) function calls.

    diff --git a/dev/quickguide/index.html b/dev/quickguide/index.html index 542c9e35..cb15e5e7 100644 --- a/dev/quickguide/index.html +++ b/dev/quickguide/index.html @@ -51,4 +51,4 @@

    The Kirkwood-Buff integral corresponding to that distribution is provided in the results.kb vector, and can be also directly plotted with 

    plot(results.d, results.kb, xlabel="d / Å", ylabel="KB(d) / L / mol")

    to obtain:

    -

    See the Atomic and group contributions section for a detailed account on how to obtain a molecular picture of the solvation by splitting the MDDF in the contributions of each type of atom of the solvent, each type of residue of the protein, etc.

    Save the results

    The results can be saved into a file (with JSON format) with:

    save("./results.json", results)

    And these results can be loaded afterwards with:

    load("./results.json")

    Alternatively, a human-readable set of output files can be obtained to be analyzed in other software (or plotted with alternative tools), with

    write("./results.dat", results)
    +

    See the Atomic and group contributions section for a detailed account on how to obtain a molecular picture of the solvation by splitting the MDDF in the contributions of each type of atom of the solvent, each type of residue of the protein, etc.

    Save the results

    The results can be saved into a file (with JSON format) with:

    save("./results.json", results)

    And these results can be loaded afterwards with:

    load("./results.json")

    Alternatively, a human-readable set of output files can be obtained to be analyzed in other software (or plotted with alternative tools), with

    write("./results.dat", results)
    diff --git a/dev/references/index.html b/dev/references/index.html index b997d7a2..95122498 100644 --- a/dev/references/index.html +++ b/dev/references/index.html @@ -1,2 +1,2 @@ -References · ComplexMixtures.jl
    GitHub

    References

    Primary citations

    If this package was useful to you, please cite the following papers:

    • L. Martínez, ComplexMixtures.jl: Investigating the structure of solutions of complex-shaped molecules from a solvent-shell perspective. J. Mol. Liq. 347, 117945, 2022. [Full Text]

    • L. Martínez, S. Shimizu, Molecular interpretation of preferential interactions in protein solvation: a solvent-shell perspective by means of minimum-distance distribution functions. J. Chem. Theor. Comp. 13, 6358–6372, 2017. [Full Text]

    Applications and examples

    • V. Piccoli, L. Martínez, Competitive Effects of Anions on Protein Solvation by Aqueous Ionic Liquids. J. Phys. Chem. B 2024. [Full Text]

    • A. F. Pereira, L. Martínez, Helical Content Correlations and Hydration Structures of the Folding Ensemble of the B Domain of Protein A. J. Chem. Inf. Model. 64, 3350-3359, 2024. [Full Text]

    • A. F. Pereira, V. Piccoli, L. Martínez, Trifluoroethanol direct interactions with protein backbones destabilize alpha-helices. J. Mol. Liq. 365, 120209, 2022. [Full Text]

    • V. Piccoli, L. Martínez, Ionic liquid solvation of proteins in native and denatured states. J. Mol. Liq. 363, 119953, 2022. [Full Text]

    • V. Piccoli, L. Martínez, Correlated counterion effects in the solvation of proteins by ionic-liquids. J. Mol. Liq. 320, 114347, 2020. [Full Text]

    • I. P. de Oliveira, L. Martínez, The shift in urea orientation at protein surfaces at low pH is compatible with a direct mechanism of protein denaturation. Phys. Chem. Chem. Phys. 22, 354-367, 2020. [Full Text]

    • I. P. de Oliveira, L. Martínez, Molecular basis for competitive solvation of the Burkholderia cepacia lipase by sorbitol and urea. Phys. Chem. Chem. Phys. 18, 21797-21808, 2016. [Full Text]

    See also

    • Packmol: A package for building initial configurations for molecular dynamics simulations.

    • CellListMap.jl: Efficient and customizable implementation of cell lists, which allows the computation of general properties dependent on distances of particles within a cutoff, for example short-range potentials, forces, neighbor lists, etc.

    • MDLovoFit: Automatic identification of mobile and rigid substructures in molecular dynamics simulations and fractional structural fluctuation analysis.

    +References · ComplexMixtures.jl
    GitHub

    References

    Primary citations

    If this package was useful to you, please cite the following papers:

    • L. Martínez, ComplexMixtures.jl: Investigating the structure of solutions of complex-shaped molecules from a solvent-shell perspective. J. Mol. Liq. 347, 117945, 2022. [Full Text]

    • L. Martínez, S. Shimizu, Molecular interpretation of preferential interactions in protein solvation: a solvent-shell perspective by means of minimum-distance distribution functions. J. Chem. Theor. Comp. 13, 6358–6372, 2017. [Full Text]

    Applications and examples

    • V. Piccoli, L. Martínez, Competitive Effects of Anions on Protein Solvation by Aqueous Ionic Liquids. J. Phys. Chem. B 2024. [Full Text]

    • A. F. Pereira, L. Martínez, Helical Content Correlations and Hydration Structures of the Folding Ensemble of the B Domain of Protein A. J. Chem. Inf. Model. 64, 3350-3359, 2024. [Full Text]

    • A. F. Pereira, V. Piccoli, L. Martínez, Trifluoroethanol direct interactions with protein backbones destabilize alpha-helices. J. Mol. Liq. 365, 120209, 2022. [Full Text]

    • V. Piccoli, L. Martínez, Ionic liquid solvation of proteins in native and denatured states. J. Mol. Liq. 363, 119953, 2022. [Full Text]

    • V. Piccoli, L. Martínez, Correlated counterion effects in the solvation of proteins by ionic-liquids. J. Mol. Liq. 320, 114347, 2020. [Full Text]

    • I. P. de Oliveira, L. Martínez, The shift in urea orientation at protein surfaces at low pH is compatible with a direct mechanism of protein denaturation. Phys. Chem. Chem. Phys. 22, 354-367, 2020. [Full Text]

    • I. P. de Oliveira, L. Martínez, Molecular basis for competitive solvation of the Burkholderia cepacia lipase by sorbitol and urea. Phys. Chem. Chem. Phys. 18, 21797-21808, 2016. [Full Text]

    See also

    • Packmol: A package for building initial configurations for molecular dynamics simulations.

    • CellListMap.jl: Efficient and customizable implementation of cell lists, which allows the computation of general properties dependent on distances of particles within a cutoff, for example short-range potentials, forces, neighbor lists, etc.

    • MDLovoFit: Automatic identification of mobile and rigid substructures in molecular dynamics simulations and fractional structural fluctuation analysis.

    diff --git a/dev/results/index.html b/dev/results/index.html index 6beef2aa..ebfdca7e 100644 --- a/dev/results/index.html +++ b/dev/results/index.html @@ -26,7 +26,7 @@ results.kb / 1000, # convert to L / mol xlabel="d/A", ylabel="mddf(d) / L/mol" -)

    Units

    Warning

    If the coordinates are not in Å, the calculation will proceed normally, but the units of the KB integrals, which has units of volume per mol, should be converted to conform the length unit provided. Note that all coordinates that are supported by default (and are thus read by the Chemfiles library) will be in Å, independently on the software used to generate the trajectories, as described here.

    Coordination number and other data

    Obtaining the MDDF involves the computation of some intermediate properties that are frequently useful for additional solution structure analysis. In particular, the coordination numbers are computed. For example, the coordination number as a function from the distance to the solute can be retrieved from a Results data structure with:

    coordination_number = results.coordination_number

    and this data can be plotted against the distances by:

    plot(result.d,results.coordination_number)

    The coordination number of subgroups can also be obtained, as explained in the Coordination number section.

    The complete data available is:

    ParameterMeaningType of valueComment
    dVector of distances of the histograms.Vector{Float64}To be used as the x coordinate on plotting any of the data.
    md_countNon-normalized count of minimum distances at each d.Vector{Float64}This is the number of minimum distances found at each histogram bin, without normalization. Usually this is not interesting to analyze, because it is dependent on the bin size.
    md_count_randomNumber of minimum distances found at each histogram bin for the random distribution.Vector{Float64}This is the normalization required to convert the md_count array into the minimum-distance distribution.
    coordination_numberCumulative number of sites found for each histogram distance.Vector{Float64}This is the coordination number, that is, the number of sites found cumulative up to each distance, without any normalization.
    coordination_number_randomCumulative site count for the random distribution.Vector{Float64}Usually not interesting for analysis.
    mddfThe final distribution function.Vector{Float64}This is the MDDF computed (md_count normalized by md_count_random). It is the main result of the calculation.
    kbThe final Kirkwood-Buff integral.Vector{Float64}This is the final KB integral, as a function of the integration distance from the solute. Computed as coordination_number - coordination_number_random
    solute_atomAtomic contributions of the solute.Matrix{Float64}This is a matrix with nbins lines and solute.natomspermol columns, containing the atomic contributions of each solute atom to the complete MDDF.
    solvent_atomAtomic contributions of the solvent.Matrix{Float64}This is a matrix with nbins lines and solvent.natomspermol columns, containing the atomic contributions of each solvent atom to the complete MDDF.
    density.soluteDensity (concentration) of the solute in the complete simulation box.Float64In units of molecules/$\textrm{\AA}^3$
    density.solventDensity (concentration) of the solvent in the complete simulation box.Float64In units of molecules/$\textrm{\AA}^3$
    density.solvent_bulkDensity (concentration) of the solute in the bulk region.Float64In units of molecules/$\textrm{\AA}^3$
    volumeVolume measures.VolumeContains the total volume of the simulation, the bulk volume, the volume of the solute domain and the shell volume of each bin of the histogram. These are computed by numerical integration from the random distributions.
    filesList of files read.Vector{String}
    weightsWeights of each file in the final counts.Vector{Float64}If the trajectories have different lengths or number of frames, the weights are adapted accordingly.

    Other Result parameters available which are set at Options:

    ParameterMeaningType of valueComment
    nbinsNumber of bins of the histograms.Int
    dbulkDistance from solute of bulk solution.Float64
    cutoffMaximum distance to be considered for histograms.Float64
    autocorrelationThe solute is the same as the solvent?BoolAutomatically set if solute == solvent.
    soluteProperties of the soluteAtomSelectionContains the number of atoms, number of atoms per molecule and number of molecules of the solute.
    solventProperties of the solvent.AtomSelectionContains the number of atoms, number of atoms per molecule and number of molecules of the solvent.
    irefatomThis is a reference atom that is used to generate random rotations and translations internally.IntCounts of the distributions for this atom are performed automatically to obtain radial (or proximal) distribution functions. Can be used for testing purposes.
    rdf_countThis is the md_count minimum distance count of irefatom.Vector{Float64}This corresponds to the conventional radial distribution function if the solute contains only one atom.
    rdf_count_randomMinimum distance of irefatom count for the random distribution.Vector{Float64}
    rdfDistribution function computed from the irefatom distribution. It is a conventional rdf if the solvent has only one atom.Vector{Float64}
    kb_rdfKirkwood-Buff integral computed from the irefatom distribution.Vector{Float64}This must converge, at long distances, to the same value as kb, and can be used for testing.
    optionsCalculation options.OptionsCarries (some redundant) options set by the user.
    lastframe_readLast frame read from the trajectory.Int
    n_frames_readNumber of frames read from the trajectory.IntCan differ from lastframe_read if stride != 1

    Reference functions

    ComplexMixtures.Result — Type
    mutable struct Result

    Structure to contain the results of the MDDF calculation.

    • Version::VersionNumber

    • nbins::Int64

    • dbulk::Float64

    • cutoff::Float64

    • d::Vector{Float64}

    • md_count::Vector{Float64}

    • md_count_random::Vector{Float64}

    • coordination_number::Vector{Float64}

    • coordination_number_random::Vector{Float64}

    • mddf::Vector{Float64}

    • kb::Vector{Float64}

    • autocorrelation::Bool

    • solute::AtomSelection

    • solvent::AtomSelection

    • solute_group_count::Vector{Vector{Float64}}

    • solvent_group_count::Vector{Vector{Float64}}

    • rdf_count::Vector{Float64}

    • rdf_count_random::Vector{Float64}

    • sum_rdf_count::Vector{Float64}

    • sum_rdf_count_random::Vector{Float64}

    • rdf::Vector{Float64}

    • kb_rdf::Vector{Float64}

    • density::ComplexMixtures.Density

    • volume::ComplexMixtures.Volume

    • files::Vector{ComplexMixtures.TrajectoryFileOptions}

    • weights::Vector{Float64}

    The Result{Vector{Float64}} parametric type is necessary only for reading the JSON3 saved file.

    source
    ComplexMixtures.load — Method
    load(filename::String, [::Type{Result}=Result])

    Function to load the json saved results file into, by default, the Result data structure. The second parameter is optional for loading Result objects.

    Example

    using ComplexMixtures: load
+)

    Units

    • The distance is assumed to be in Å, as this is the most common distance units in molecular simulations. The coordinates of the atoms are assumed be provided in Å.

    • The minimum-distance distribution function is unit-less, since it is the ratio of the density at each distance divided by an ideal-gas density.

    • The Kirkwood-Buff integrals are returned in cm³ mol⁻¹, if the coordinates were provided in Å.

    Warning

    If the coordinates are not in Å, the calculation will proceed normally, but the units of the KB integrals, which has units of volume per mol, should be converted to conform the length unit provided. Note that all coordinates that are supported by default (and are thus read by the Chemfiles library) will be in Å, independently on the software used to generate the trajectories, as described here.

    Coordination number and other data

    Obtaining the MDDF involves the computation of some intermediate properties that are frequently useful for additional solution structure analysis. In particular, the coordination numbers are computed. For example, the coordination number as a function from the distance to the solute can be retrieved from a Results data structure with:

    coordination_number = results.coordination_number

    and this data can be plotted against the distances by:

    plot(result.d,results.coordination_number)

    The coordination number of subgroups can also be obtained, as explained in the Coordination number section.

    The complete data available is:

    ParameterMeaningType of valueComment
    dVector of distances of the histograms.Vector{Float64}To be used as the x coordinate on plotting any of the data.
    md_countNon-normalized count of minimum distances at each d.Vector{Float64}This is the number of minimum distances found at each histogram bin, without normalization. Usually this is not interesting to analyze, because it is dependent on the bin size.
    md_count_randomNumber of minimum distances found at each histogram bin for the random distribution.Vector{Float64}This is the normalization required to convert the md_count array into the minimum-distance distribution.
    coordination_numberCumulative number of sites found for each histogram distance.Vector{Float64}This is the coordination number, that is, the number of sites found cumulative up to each distance, without any normalization.
    coordination_number_randomCumulative site count for the random distribution.Vector{Float64}Usually not interesting for analysis.
    mddfThe final distribution function.Vector{Float64}This is the MDDF computed (md_count normalized by md_count_random). It is the main result of the calculation.
    kbThe final Kirkwood-Buff integral.Vector{Float64}This is the final KB integral, as a function of the integration distance from the solute. Computed as coordination_number - coordination_number_random
    solute_atomAtomic contributions of the solute.Matrix{Float64}This is a matrix with nbins lines and solute.natomspermol columns, containing the atomic contributions of each solute atom to the complete MDDF.
    solvent_atomAtomic contributions of the solvent.Matrix{Float64}This is a matrix with nbins lines and solvent.natomspermol columns, containing the atomic contributions of each solvent atom to the complete MDDF.
    density.soluteDensity (concentration) of the solute in the complete simulation box.Float64In units of molecules/$\textrm{\AA}^3$
    density.solventDensity (concentration) of the solvent in the complete simulation box.Float64In units of molecules/$\textrm{\AA}^3$
    density.solvent_bulkDensity (concentration) of the solute in the bulk region.Float64In units of molecules/$\textrm{\AA}^3$
    volumeVolume measures.VolumeContains the total volume of the simulation, the bulk volume, the volume of the solute domain and the shell volume of each bin of the histogram. These are computed by numerical integration from the random distributions.
    filesList of files read.Vector{String}
    weightsWeights of each file in the final counts.Vector{Float64}If the trajectories have different lengths or number of frames, the weights are adapted accordingly.

    Other Result parameters available which are set at Options:

    ParameterMeaningType of valueComment
    nbinsNumber of bins of the histograms.Int
    dbulkDistance from solute of bulk solution.Float64
    cutoffMaximum distance to be considered for histograms.Float64
    autocorrelationThe solute is the same as the solvent?BoolAutomatically set if solute == solvent.
    soluteProperties of the soluteAtomSelectionContains the number of atoms, number of atoms per molecule and number of molecules of the solute.
    solventProperties of the solvent.AtomSelectionContains the number of atoms, number of atoms per molecule and number of molecules of the solvent.
    irefatomThis is a reference atom that is used to generate random rotations and translations internally.IntCounts of the distributions for this atom are performed automatically to obtain radial (or proximal) distribution functions. Can be used for testing purposes.
    rdf_countThis is the md_count minimum distance count of irefatom.Vector{Float64}This corresponds to the conventional radial distribution function if the solute contains only one atom.
    rdf_count_randomMinimum distance of irefatom count for the random distribution.Vector{Float64}
    rdfDistribution function computed from the irefatom distribution. It is a conventional rdf if the solvent has only one atom.Vector{Float64}
    kb_rdfKirkwood-Buff integral computed from the irefatom distribution.Vector{Float64}This must converge, at long distances, to the same value as kb, and can be used for testing.
    optionsCalculation options.OptionsCarries (some redundant) options set by the user.
    lastframe_readLast frame read from the trajectory.Int
    n_frames_readNumber of frames read from the trajectory.IntCan differ from lastframe_read if stride != 1

    Reference functions

    ComplexMixtures.Result — Type
    mutable struct Result

    Structure to contain the results of the MDDF calculation.

    • Version::VersionNumber

    • nbins::Int64

    • dbulk::Float64

    • cutoff::Float64

    • d::Vector{Float64}

    • md_count::Vector{Float64}

    • md_count_random::Vector{Float64}

    • coordination_number::Vector{Float64}

    • coordination_number_random::Vector{Float64}

    • mddf::Vector{Float64}

    • kb::Vector{Float64}

    • autocorrelation::Bool

    • solute::AtomSelection

    • solvent::AtomSelection

    • solute_group_count::Vector{Vector{Float64}}

    • solvent_group_count::Vector{Vector{Float64}}

    • rdf_count::Vector{Float64}

    • rdf_count_random::Vector{Float64}

    • sum_rdf_count::Vector{Float64}

    • sum_rdf_count_random::Vector{Float64}

    • rdf::Vector{Float64}

    • kb_rdf::Vector{Float64}

    • density::ComplexMixtures.Density

    • volume::ComplexMixtures.Volume

    • files::Vector{ComplexMixtures.TrajectoryFileOptions}

    • weights::Vector{Float64}

    The Result{Vector{Float64}} parametric type is necessary only for reading the JSON3 saved file.

    source
    ComplexMixtures.load — Method
    load(filename::String, [::Type{Result}=Result])

    Function to load the json saved results file into, by default, the Result data structure. The second parameter is optional for loading Result objects.

    Example

    using ComplexMixtures: load
 R = load("results.json")
 #or
-R = load("results.json", Result)
    source
    Base.merge — Method
    merge(r::Vector{Result})

    This function merges the results of MDDF calculations obtained by running the same analysis on multiple trajectories, or multiple parts of the same trajectory. It returns a Result structure of the same type, with all the functions and counters representing averages of the set provided weighted by the number of frames read in each Result set.

    source
    ComplexMixtures.Density — Type
    mutable struct Density

    Structure to contain the density values obtained from the calculation.

    • solute::Float64

    • solvent::Float64

    • solvent_bulk::Float64

    source
    +R = load("results.json", Result)source
    ComplexMixtures.save — Method
    save(filename::String, R::Result)

    Function to write the result data structure to a json file.

    source
    Base.merge — Method
    merge(r::Vector{Result})

    This function merges the results of MDDF calculations obtained by running the same analysis on multiple trajectories, or multiple parts of the same trajectory. It returns a Result structure of the same type, with all the functions and counters representing averages of the set provided weighted by the number of frames read in each Result set.

    source
    ComplexMixtures.overview — Method
    overview(R::Result)

    Function that outputs the volumes and densities in the most natural units.

    source
    ComplexMixtures.Density — Type
    mutable struct Density

    Structure to contain the density values obtained from the calculation.

    • solute::Float64

    • solvent::Float64

    • solvent_bulk::Float64

    source
    diff --git a/dev/save/index.html b/dev/save/index.html index cb08ba79..26502b7f 100644 --- a/dev/save/index.html +++ b/dev/save/index.html @@ -3,4 +3,4 @@ R::Result, filename::String; solute_group_names::Vector{String} = R.solute.group_names, solvent_group_names::Vector{String} = R.solvent.group_names, -)

    Function to write the final results to output files as simple tables that are human-readable and easy to analyze with other software

    If the solute and solvent group names are defined in R, the solute_group_names and solvent_group_names arguments are not necessary. If they are not defined, the user can pass the names of the groups as strings in the solute_group_names and solvent_group_names arguments.

    source +)

    Function to write the final results to output files as simple tables that are human-readable and easy to analyze with other software

    If the solute and solvent group names are defined in R, the solute_group_names and solvent_group_names arguments are not necessary. If they are not defined, the user can pass the names of the groups as strings in the solute_group_names and solvent_group_names arguments.

    source diff --git a/dev/selection/index.html b/dev/selection/index.html index 2bfd5a16..4b5229ee 100644 --- a/dev/selection/index.html +++ b/dev/selection/index.html @@ -59,7 +59,7 @@ julia> result = mddf(trajectory, Options(bulk_range=(8.0, 12.0))); -julia> acidic_residue_contributions = contributions(result, SoluteGroup("acidic residues"))

    Reference functions

    ComplexMixtures.AtomSelection — Type
    struct AtomSelection

    Structure that contains the information about the solute and solvent molecules.

    • nmols::Int64

    • natomspermol::Int64

    • indices::Vector{Int64}

    • custom_groups::Bool

    • group_atom_indices::Vector{Vector{Int64}}

    • group_names::Vector{String}

    source
    ComplexMixtures.AtomSelection — Method

    AtomSelection constructors

    The AtomSelection structure carries the information of the molecules that are going to be used to compute the MDDF. The structure can be initialized in different ways:

    1. Initialize the structure providing a vector of PDBTools.Atom(s).
        AtomSelection(
+julia> acidic_residue_contributions = contributions(result, SoluteGroup("acidic residues"))

    Reference functions

    ComplexMixtures.AtomSelection — Type
    struct AtomSelection

    Structure that contains the information about the solute and solvent molecules.

    • nmols::Int64

    • natomspermol::Int64

    • indices::Vector{Int64}

    • custom_groups::Bool

    • group_atom_indices::Vector{Vector{Int64}}

    • group_names::Vector{String}

    source
    ComplexMixtures.AtomSelection — Method

    AtomSelection constructors

    The AtomSelection structure carries the information of the molecules that are going to be used to compute the MDDF. The structure can be initialized in different ways:

    1. Initialize the structure providing a vector of PDBTools.Atom(s).
        AtomSelection(
         atoms::AbstractVector{<:PDBTools.Atom}; 
         nmols::Int = 0, 
         natomspermol::Int = 0,
@@ -108,7 +108,7 @@
 AtomSelection 
     3 atoms belonging to 3 molecule(s).
     Atoms per molecule: 1
-    Number of groups: 2
    source
    ComplexMixtures.SoluteGroup — Type

    SoluteGroup and SolventGroup data structures.

    These structures are used to select groups of atoms to extract their contributions from the MDDF results.

    Most tipically, the groups are defined from a selection of atoms with the PDBTools package, or by providing directly the indices of teh atoms in the structure.

    Alternativelly, if the groups were predefined, the groups can be selected by group index or group name.

    The possible constructors are:

    SoluteGroup(atoms::Vector{PDBTools.Atom})
+    Number of groups: 2
    source
    ComplexMixtures.SoluteGroup — Type

    SoluteGroup and SolventGroup data structures.

    These structures are used to select groups of atoms to extract their contributions from the MDDF results.

    Most tipically, the groups are defined from a selection of atoms with the PDBTools package, or by providing directly the indices of teh atoms in the structure.

    Alternativelly, if the groups were predefined, the groups can be selected by group index or group name.

    The possible constructors are:

    SoluteGroup(atoms::Vector{PDBTools.Atom})
 SoluteGroup(atom_indices::Vector{Int})
 SoluteGroup(atom_names::Vector{String})
 SoluteGroup(group_name::String)
@@ -140,7 +140,7 @@
 julia> SoluteGroup(collect(eachresidue(atoms))[2]) # PDBTools.Residue(s)
 SoluteGroup defined by:
     atom_indices: [ 13, 14, ..., 22, 23 ] - 11 atoms
-
    source
    ComplexMixtures.SolventGroup — Type

    SoluteGroup and SolventGroup data structures.

    These structures are used to select groups of atoms to extract their contributions from the MDDF results.

    Most tipically, the groups are defined from a selection of atoms with the PDBTools package, or by providing directly the indices of teh atoms in the structure.

    Alternativelly, if the groups were predefined, the groups can be selected by group index or group name.

    The possible constructors are:

    SoluteGroup(atoms::Vector{PDBTools.Atom})
+
    source
    ComplexMixtures.SolventGroup — Type

    SoluteGroup and SolventGroup data structures.

    These structures are used to select groups of atoms to extract their contributions from the MDDF results.

    Most tipically, the groups are defined from a selection of atoms with the PDBTools package, or by providing directly the indices of teh atoms in the structure.

    Alternativelly, if the groups were predefined, the groups can be selected by group index or group name.

    The possible constructors are:

    SoluteGroup(atoms::Vector{PDBTools.Atom})
 SoluteGroup(atom_indices::Vector{Int})
 SoluteGroup(atom_names::Vector{String})
 SoluteGroup(group_name::String)
@@ -172,7 +172,7 @@
 julia> SoluteGroup(collect(eachresidue(atoms))[2]) # PDBTools.Residue(s)
 SoluteGroup defined by:
     atom_indices: [ 13, 14, ..., 22, 23 ] - 11 atoms
-
    source
    ComplexMixtures.atom_group — Method
    atom_group(atsel::AtomSelection, i::Int)
 atom_group(atsel::AtomSelection, groupname::String)
 
 atom_group(atsel::AtomSelection, i::Int)
@@ -194,7 +194,7 @@
  3
 
 julia> atom_group_name(atsel, 1)
-"G1"
    source
    ComplexMixtures.atom_group_name — Method
    atom_group_name(atsel::AtomSelection, i::Int)
 atom_group_names(atsel::AtomSelection)

    Return the name of the group of atoms with index i. The atom_group_names function returns a vector with the names of all the groups.

    Example

    julia> using ComplexMixtures
 
 julia> atsel = AtomSelection([1,2,3], natomspermol=1, group_atom_indices=[[1,2],[3]], group_names=["G1", "G2"])
@@ -209,7 +209,7 @@
 julia> atom_group_names(atsel)
 2-element Vector{String}:
  "G1"
- "G2"
    source
    ComplexMixtures.atom_group_names — Method
    atom_group_name(atsel::AtomSelection, i::Int)
 atom_group_names(atsel::AtomSelection)

    Return the name of the group of atoms with index i. The atom_group_names function returns a vector with the names of all the groups.

    Example

    julia> using ComplexMixtures
 
 julia> atsel = AtomSelection([1,2,3], natomspermol=1, group_atom_indices=[[1,2],[3]], group_names=["G1", "G2"])
@@ -224,4 +224,4 @@
 julia> atom_group_names(atsel)
 2-element Vector{String}:
  "G1"
- "G2"
    source
    + "G2"source diff --git a/dev/tools/index.html b/dev/tools/index.html index f28df55e..683670b7 100644 --- a/dev/tools/index.html +++ b/dev/tools/index.html @@ -40,7 +40,7 @@ # Compute the coordination number residue50_coordination = coordination_number(solute, R.solute_atom, R, group) # Output the average number of TMAO molecules within 5 Angstroms of residue 50 -residue50_coordination[findlast(<(5), R.d)]source

    2D density map per residue

    The ResidueContributions object

    One nice way to visualize the accumulation or depletion of a solvent around a macromolecule (a protein, for example), is to obtain a 2D map of the density as a function of the distance from its surface. For example, in the figure below the density of a solute (here, Glycerol), in the neighborhood of a protein is shown:

    +residue50_coordination[findlast(<(5), R.d)]source

    2D density map per residue

    The ResidueContributions object

    One nice way to visualize the accumulation or depletion of a solvent around a macromolecule (a protein, for example), is to obtain a 2D map of the density as a function of the distance from its surface. For example, in the figure below the density of a solute (here, Glycerol), in the neighborhood of a protein is shown:

    Here, one can see that Glycerol accumulates on Asp76 and on the proximity of hydrogen-bonding residues (Serine residues mostly). This figure was obtained by extracting from atomic contributions of the protein the contribution of each residue to the MDDF, coordination numbers or minimum-distance counts.

    Compat

    All features described in this section are only available in v2.8.0 or greater.

    The computation of the contributions of each residue can be performed with the convenience function ResidueContributions, which creates an object containing the contributions of the residues to the mddf (or coordination numbers, or minimum-distance counts), the residue names, and distances:

    ComplexMixtures.ResidueContributions — Type
    ResidueContributions (data structure)

    Constructor function:

    ResidueContributions(
     results::Result, atoms::AbstractVector{PDBTools.Atom};
@@ -95,7 +95,7 @@
 contourf(rc_diff) # plots a contour map of the difference
 # multiply and divide by scalars
 rc3 = 3 * rc1
-rc4 = rc2 / 2
    Compat

    Slicing, indexing, and multiplication and divison by scalars were introduces in v2.7.0. Saving and loading was introduced in v2.8.0.

    source

    The output of ResidueContributions is by default shown as a simple unicode plot:

    +rc4 = rc2 / 2
    Compat

    Slicing, indexing, and multiplication and divison by scalars were introduces in v2.7.0. Saving and loading was introduced in v2.8.0.

    source

    The output of ResidueContributions is by default shown as a simple unicode plot:

    The ResidueContribution object can be used to produce a high-quality contour plot using the Plots.contourf function:

    Plots.contourf — Method
    contourf(
     rc::ResidueContributions; 
@@ -111,7 +111,7 @@
 
 julia> rc = ResidueContributions(results, atoms; oneletter=true)
 
-julia> plt = contourf(rc; step=5)

    This will produce a plot with the contribution of each residue to the solute-solvent pair distribution function, as a contour plot, with the residues in the x-axis and the distance in the y-axis.

    To customize the plot, use the Plot.contourf keyword parameters, for example:

    julia> plt = contourf(rc; step=5, size=(800,400), title="Title", clims=(-0.1, 0.1))
    Compat

    This function requires loading the Plots package and is available in ComplexMixtures v2.5.0 or greater.

    Support for all Plots.contourf parameters was introduced in ComplexMixtures v2.6.0.

    source

    A complete example of its usage can be seen here.

    Indexing, slicing, arithmetic operations

    The ResidueContributions object can be indexes and sliced, for the analysis of the contributions of specific residues or range of residues:

    rc = ResidueContributions(results1, select(atoms, "protein")); 
+julia> plt = contourf(rc; step=5)

    This will produce a plot with the contribution of each residue to the solute-solvent pair distribution function, as a contour plot, with the residues in the x-axis and the distance in the y-axis.

    To customize the plot, use the Plot.contourf keyword parameters, for example:

    julia> plt = contourf(rc; step=5, size=(800,400), title="Title", clims=(-0.1, 0.1))
    Compat

    This function requires loading the Plots package and is available in ComplexMixtures v2.5.0 or greater.

    Support for all Plots.contourf parameters was introduced in ComplexMixtures v2.6.0.

    source

    A complete example of its usage can be seen here.

    Indexing, slicing, arithmetic operations

    The ResidueContributions object can be indexes and sliced, for the analysis of the contributions of specific residues or range of residues:

    rc = ResidueContributions(results1, select(atoms, "protein")); 
 rc_7 = rc[7] # contributions of residue 7
 rc_range = rc[20:50] # contributions of a range of residues

    Slicing will return a new ResidueContributions object.

    Additionally, these ResidueContributions objects can be subtracted, divided, summed, or multiplied, to compare contributions of residues among different simulations. Typically, if one wants to compare the solvation of residues in two different simulations, one can do:

    # first simulation (for example, low temperature)
 rc1 = ResidueContributions(results1, select(atoms, "protein")); 
@@ -134,10 +134,10 @@
 rc_loaded = load("residue_contributions.json", ResidueContributions)

    Note that the load function requires, as a second argument, the ResidueContributions type, to differentiate the method from the loading of the Result data structure.

    ComplexMixtures.load — Method
    load(filename::String, ResidueContributions)

    Function to load the residue contributions saved into a JSON file into the ResidueContributions data structure.

    Example

    using ComplexMixtures
 rc = ResidueContributions(resutls, SoluteGroup(protein))
 save("residue_contributions.json", rc)
-rc = load("residue_contributions.json", ResidueContributions)
    source
    ComplexMixtures.save — Method
    save(filename::String, rc::ResidueContributions)

    Save the ResidueContributions object to a JSON file.

    using ComplexMixtures
+rc = load("residue_contributions.json", ResidueContributions)
    source
    ComplexMixtures.save — Method
    save(filename::String, rc::ResidueContributions)

    Save the ResidueContributions object to a JSON file.

    using ComplexMixtures
 rc = ResidueContributions(resutls, SoluteGroup(protein))
 save("residue_contributions.json", rc)
-rc = load("residue_contributions.json", ResidueContributions)
    source
    Tip

    These ResidueContributions methods are convenience functions only.

    Basically, we are extracting the contribution of each residue independently and building a matrix where each row represents a distance and each column a residue. Using PDBTools, this can be done with, for example: 

    residues = collect(eachresidue(protein))
+rc = load("residue_contributions.json", ResidueContributions)
    source
    Tip

    These ResidueContributions methods are convenience functions only.

    Basically, we are extracting the contribution of each residue independently and building a matrix where each row represents a distance and each column a residue. Using PDBTools, this can be done with, for example: 

    residues = collect(eachresidue(protein))
 residue_contributions = zeros(length(R.d),length(residues))
 for (i,residue) in pairs(residues)
   c = contributions(results, SoluteGroup(residue)) 
@@ -151,11 +151,11 @@
 
 julia> R = ComplexMixtures.load("./results.json");
 
-julia> grid = grid3D(R, atoms, "grid.pdb");

    Examples of how the grid can be visualized are provided in the user guide of ComplexMixtures.

    source

    The call to grid3D will write an output a PDB file with the grid points, which loaded in a visualization software side-by-side with the protein structure, allows the production of the images shown. The grid.pdb file contains a regular PDB format where:

    • The positions of the atoms are grid points.
    • The identity of the atoms correspond to the identity of the protein atom contributing to the MDDF at that point (the closest protein atom).
    • The temperature-factor column (beta) contains the relative contribution of that atom to the MDDF at the corresponding distance.
    • The occupancy field contains the distance itself.

    For example, the distribution function of a hydrogen-bonding liquid solvating a protein will display a characteristic peak at about 1.8Å. The MDDF at that distance can be decomposed into the contributions of all atoms of the protein which were found to form hydrogen bonds to the solvent. A 3D representation of these contributions can be obtained by computing, around a static protein (solute) structure, which are the regions in space which are closer to each atom of the protein. The position in space is then marked with the atom of the protein to which that region "belongs" and with the contribution of that atom to the MDDF at each distance within that region. A special function to compute this 3D distribution is provided here: grid3D.

    This is better illustrated by a graphical representation. In the figure below we see a 3D representation of the MDDF of Glycerol around a protein, computed from a simulation of this protein in a mixture of water and Glycerol. A complete set of files and a script to reproduce this example is available here.

    +julia> grid = grid3D(R, atoms, "grid.pdb");

    Examples of how the grid can be visualized are provided in the user guide of ComplexMixtures.

    source

    The call to grid3D will write an output a PDB file with the grid points, which loaded in a visualization software side-by-side with the protein structure, allows the production of the images shown. The grid.pdb file contains a regular PDB format where:

    • The positions of the atoms are grid points.
    • The identity of the atoms correspond to the identity of the protein atom contributing to the MDDF at that point (the closest protein atom).
    • The temperature-factor column (beta) contains the relative contribution of that atom to the MDDF at the corresponding distance.
    • The occupancy field contains the distance itself.

    For example, the distribution function of a hydrogen-bonding liquid solvating a protein will display a characteristic peak at about 1.8Å. The MDDF at that distance can be decomposed into the contributions of all atoms of the protein which were found to form hydrogen bonds to the solvent. A 3D representation of these contributions can be obtained by computing, around a static protein (solute) structure, which are the regions in space which are closer to each atom of the protein. The position in space is then marked with the atom of the protein to which that region "belongs" and with the contribution of that atom to the MDDF at each distance within that region. A special function to compute this 3D distribution is provided here: grid3D.

    This is better illustrated by a graphical representation. In the figure below we see a 3D representation of the MDDF of Glycerol around a protein, computed from a simulation of this protein in a mixture of water and Glycerol. A complete set of files and a script to reproduce this example is available here.

    In the figure on the left, the points in space around the protein are selected with the following properties: distance from the protein smaller than 2.0Å and relative contribution to the MDDF at the corresponding distance of at least 10% of the maximum contribution. Thus, we are selecting the regions of the protein corresponding to the most stable hydrogen-bonding interactions. The color of the points is the contribution to the MDDF, from blue to red. Thus, the most reddish-points corresponds to the regions where the most stable hydrogen bonds were formed. We have marked two regions here, on opposite sides of the protein, with arrows.

    Clicking on those points we obtain which are the atoms of the protein contributing to the MDDF at that region. In particular, the arrow on the right points to the strongest red region, which corresponds to an Aspartic acid. These residues are shown explicitly under the density (represented as a transparent surface) on the figure in the center.

    The figure on the right displays, overlapped with the hydrogen-bonding residues, the most important contributions to the second peak of the distribution, corresponding to distances from the protein between 2.0 and 3.5Å. Notably, the regions involved are different from the ones forming hydrogen bonds, indicating that non-specific interactions with the protein (and not a second solvation shell) are responsible for the second peak.

    Computing radial distribution functions

    The distributions returned by the mddf function (the mddf and rdf vectors), are normalized by the random reference state or using a site count based on the numerical integration of the volume corresponding to each minimum-distance to the solute.

    If, however, the solute is defined by a single atom (as the oxygen atom of water, for example), the numerical integration of the volume can be replaced by a simple analytical spherical shell volume, reducing noise. The ComplexMixtures.gr function returns the radial distribution function and the KB integral computed from the results, using this volume estimate: 

    g, kb = ComplexMixtures.gr(R)

    By default, the single-reference count (rdf_count) of the Result structure will be used to compute the radial distribution function. The function can be called with explicit control of all input parameters: 

    g, kb = ComplexMixtures.gr(r,count,density,binstep)

    where:

    ParameterDefinitionResult structure output data to provide
    rVector of distancesThe d vector
    countNumber of site counts at each rThe rdf or mddf vectors
    densityBulk densityThe density.solvent_bulk or density.solvent densities.
    binstepThe histogram stepThe options.binstep

    Example:

    ...
 R = mddf(trajectory, options)
-g, kb = ComplexMixtures.gr(R.d,R.rdf_count,R.density.solvent_bulk,R.options.binstep)
    ComplexMixtures.gr — Method
    gr(R::Result) = gr(R.d,R.rdf_count,R.density.solvent_bulk,R.files[1].options.binstep)

    If a Result structure is provided without further details, use the rdf count and the bulk solvent density.

    source
    ComplexMixtures.gr — Method
    gr(r::Vector{Float64}, count::Vector{Float64}, density::Float64, binstep::Float64)

    Computes the radial distribution function from the count data and the density.

    This is exactly a conventional g(r) if a single atom was chosen as the solute and solvent selections.

    Returns both the g(r) and the kb(r)

    source

    Overview of the solvent and solute properties

    The output to the REPL of the Result structure provides an overview of the properties of the solution. The data can be retrieved into a data structure using the overview function. Examples: 

    ...
+g, kb = ComplexMixtures.gr(R.d,R.rdf_count,R.density.solvent_bulk,R.options.binstep)
    ComplexMixtures.gr — Method
    gr(R::Result) = gr(R.d,R.rdf_count,R.density.solvent_bulk,R.files[1].options.binstep)

    If a Result structure is provided without further details, use the rdf count and the bulk solvent density.

    source
    ComplexMixtures.gr — Method
    gr(r::Vector{Float64}, count::Vector{Float64}, density::Float64, binstep::Float64)

    Computes the radial distribution function from the count data and the density.

    This is exactly a conventional g(r) if a single atom was chosen as the solute and solvent selections.

    Returns both the g(r) and the kb(r)

    source

    Overview of the solvent and solute properties

    The output to the REPL of the Result structure provides an overview of the properties of the solution. The data can be retrieved into a data structure using the overview function. Examples: 

    ...
 
 julia> results = mddf(trajectory, Options(bulk_range=(8.0, 12.0)))
 
@@ -210,4 +210,4 @@
 
 julia> atoms = readPDB("system.pdb", "protein")
 
-julia> plt = contourf_per_residue(results, atoms; oneletter=true)

    This will produce a plot with the contribution of each residue to the solute-solvent pair distribution function, as a contour plot, with the residues in the x-axis and the distance in the y-axis.

    The resulting plot can customized using the standard mutating plot! function, for example, 

    julia> plot!(plt, size=(800, 400), title="Contribution per residue")
    Compat

    This function requires loading the Plots package and is available in ComplexMixtures v2.2.0 or greater.

    The type and clims arguments, and the support for a step in xticks_range were introduced in ComplexMixtures v2.3.0.

    source
    +julia> plt = contourf_per_residue(results, atoms; oneletter=true)

    This will produce a plot with the contribution of each residue to the solute-solvent pair distribution function, as a contour plot, with the residues in the x-axis and the distance in the y-axis.

    The resulting plot can customized using the standard mutating plot! function, for example, 

    julia> plot!(plt, size=(800, 400), title="Contribution per residue")
    Compat

    This function requires loading the Plots package and is available in ComplexMixtures v2.2.0 or greater.

    The type and clims arguments, and the support for a step in xticks_range were introduced in ComplexMixtures v2.3.0.

    source
    diff --git a/dev/trajectory/index.html b/dev/trajectory/index.html index 478205af..09661fd9 100644 --- a/dev/trajectory/index.html +++ b/dev/trajectory/index.html @@ -1,2 +1,2 @@ -Loading the trajectory · ComplexMixtures.jl
    GitHub

    Loading trajectories

    To initialize a trajectory file for computation, use the command

    trajectory = Trajectory("trajectory.xtc",solute,solvent)

    where solute and solvent are defined with the AtomSelection function described before. This function opens the stream for reading frames, which are read once a time when the coordinates are required for computing the MDDF.

    The Trajectory function uses Chemfiles in background, and thus the most common trajectory formats are supported, as the ones produced with NAMD, Gromacs, LAMMPS, Amber, etc.

    Tip

    The format of the trajectory file is automatically determined by Chemfiles from the extension of the file. However, it can be provided by the user with the format keyword, for example:

    trajectory = Trajectory("trajectory.xtc",solute,solvent,format="xtc")

    Reference functions

    ComplexMixtures.Trajectory — Type
    Trajectory(filename::String, solute::AtomSelection, solvent::AtomSelection; format::String = "", chemfiles = false)

    Trajectory constructor data type.

    Defaults to reading with the Chemfiles infrastructure, except for DCD and PDB trajectory files, if the "PDBTraj" option is provided.

    See memory issue (https://github.com/chemfiles/Chemfiles.jl/issues/44)

    source
    +Loading the trajectory · ComplexMixtures.jl
    GitHub

    Loading trajectories

    To initialize a trajectory file for computation, use the command

    trajectory = Trajectory("trajectory.xtc",solute,solvent)

    where solute and solvent are defined with the AtomSelection function described before. This function opens the stream for reading frames, which are read once a time when the coordinates are required for computing the MDDF.

    The Trajectory function uses Chemfiles in background, and thus the most common trajectory formats are supported, as the ones produced with NAMD, Gromacs, LAMMPS, Amber, etc.

    Tip

    The format of the trajectory file is automatically determined by Chemfiles from the extension of the file. However, it can be provided by the user with the format keyword, for example:

    trajectory = Trajectory("trajectory.xtc",solute,solvent,format="xtc")

    Reference functions

    ComplexMixtures.Trajectory — Type
    Trajectory(filename::String, solute::AtomSelection, solvent::AtomSelection; format::String = "", chemfiles = false)

    Trajectory constructor data type.

    Defaults to reading with the Chemfiles infrastructure, except for DCD and PDB trajectory files, if the "PDBTraj" option is provided.

    See memory issue (https://github.com/chemfiles/Chemfiles.jl/issues/44)

    source
    diff --git a/dev/updating_scripts/index.html b/dev/updating_scripts/index.html index bb88acd1..26248243 100644 --- a/dev/updating_scripts/index.html +++ b/dev/updating_scripts/index.html @@ -1,3 +1,3 @@ Updating scripts · ComplexMixtures.jl
    GitHub

    Updating scripts from v1 to v2

    The syntax chances necessary to update script from version 1.X to 2.X of the package are:

    Atom selections

    The previous Selection structure was renamed to AtomSelection for clarity.

    • Before:
    water = Selection(water; natomspermol=3)
    • Now:
    water = AtomSelection(water; natomspermol=3)

    Group contributions syntax

    The syntax to computing group contributions is improved. Previously, the contrib or contributions functions required three somewhat redundant parameters.

    • Before:

    The call to contributions required 3 parameters: the Selection structure, the matrix of contributions, and the indexes of the atoms for which the contributions were desired:

    h_contributions = contributions(solvent, R.solvent_atom, h_indexes)
    • Now:

    The contributions are extracted from the Result data structure, by providing either a SoluteGroup or SolventGroup object, which are setup with the group names, group indexes, atom names, or atom indexes:

    h_contributions = contributions(R, SolventGroup(h_indexes))

    Frame weights

    frame_weights is now an option of the mddf execution. That is previously, they were defined in the Options data structure, and now they are passed to the mddf function.

    • Before:
    options = Options(frame_weights=[1.0, 2.0], bulk_range=(8.0, 12.0))
-results = mddf(trajectory, options)
    • Now:
    results = mddf(trajectory, options; frame_weights=[1.0, 2.0])
    +results = mddf(trajectory, options)
    results = mddf(trajectory, options; frame_weights=[1.0, 2.0])