Skip to content

Commit 85e1155

Browse files
lmiqlmiq
committed
docs reorganization
1 parent 4a5ac12 commit 85e1155

File tree

5 files changed

+160
-98
lines changed

5 files changed

+160
-98
lines changed

‎docs/make.jl

+27-18
Original file line numberDiff line numberDiff line change
@@ -13,25 +13,34 @@ makedocs(
1313
sitename="ComplexMixtures.jl",
1414
pages=[
1515
"Introduction" => "index.md",
16-
"Installation" => "installation.md",
17-
"Parallel execution" => "parallel.md",
16+
"Install and run" => Any[
17+
"Installation" => "installation.md",
18+
"Parallel execution" => "parallel.md",
19+
"From Python" => "python.md",
20+
],
1821
"Quick Guide" => "quickguide.md",
19-
"Examples:" => "examples.md",
20-
" ◦ Protein in water/glycerol" => "example1.md",
21-
" ◦ Polyacrylamide in DMF" => "example2.md",
22-
" ◦ POPC membrane in water/ethanol" => "example3.md",
23-
" ◦ Water/Glycerol mixture" => "example4.md",
24-
"Set solute and solvent" => "selection.md",
25-
"Computing the MDDF" => "mddf.md",
26-
"Results" => "results.md",
27-
"Atomic and group contributions" => "contributions.md",
28-
"Save and load" => "save.md",
29-
"Multiple trajectories" => "multiple.md",
30-
"Options" => "options.md",
31-
"Density maps" => "density_maps.md",
32-
"Tools" => "tools.md",
33-
"From Python" => "python.md",
34-
"Updating scripts" => "updating_scripts.md",
22+
"Examples" => Any[
23+
"Running the examples" => "examples.md",
24+
"Protein in water/glycerol" => "example1.md",
25+
"Polyacrylamide in DMF" => "example2.md",
26+
"POPC membrane in water/ethanol" => "example3.md",
27+
"Water/Glycerol mixture" => "example4.md",
28+
],
29+
"Setup and run" => Any[
30+
"Set solute and solvent" => "selection.md",
31+
"Computing the MDDF" => "mddf.md",
32+
"Save and load" => "save.md",
33+
"Multiple trajectories" => "multiple.md",
34+
"Options" => "options.md",
35+
],
36+
"Analysis" => Any[
37+
"Results" => "results.md",
38+
"Atomic and group contributions" => "contributions.md",
39+
"Density maps" => "density_maps.md",
40+
"Coordination numbers" => "coordination_numbers.md",
41+
"Tools" => "tools.md",
42+
],
43+
# "Updating scripts" => "updating_scripts.md",
3544
"References" => "references.md",
3645
],
3746
)

‎docs/src/coordination_numbers.md

+79
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
```@meta
2+
CollapsedDocStrings = true
3+
```
4+
5+
# [Coordination numbers](@id coordination_number)
6+
7+
## Extract coordination numbers
8+
9+
The coordination number is the numerical count of how many molecules of a solvent is within a certain distance
10+
from the solute. The following function provides the functionality of retrieving coordination numbers and atom
11+
groups contributions to these numbers, given a `Result` data structure:
12+
13+
```@autodocs
14+
Modules = [ComplexMixtures]
15+
Pages = ["coordination_number.jl"]
16+
```
17+
18+
The function can be called without any argument besides the `Result` data structure, in which case the coordination number of the complete solute will
19+
be returned, as a function of the distance.
20+
21+
Alternatively, subgroups of the solute or the solvent can be selected, by providing `SoluteGroup` or `SolventGroup` objects as second arguments,
22+
initialized with the atoms of the subgroup, as a list of indices or a list of atoms generated by `PDBTools`. Note that, if a `SolventGroup`
23+
is defined we obtain the contributions of those solvent atoms to the coordination number *of the solute* (for instance, the sum of the
24+
contributions of all solvent atoms is the coordination number of the solute).
25+
26+
## Example
27+
28+
In the following example we compute the coordination number of the atoms of `residue 50` (which belongs to the solute - a protein) with the solvent atoms of TMAO, as a function of the distance. The plot produced will show side by side the residue contribution to the MDDF and the corresponding coordination number.
29+
30+
```julia
31+
# Load necessary packages
32+
using ComplexMixtures, PDBTools
33+
# Load data structure and previously computed results from a mddf calculation
34+
pdb = read_pdb("test/data/NAMD/structure.pdb")
35+
R = load("test/data/NAMD/protein_tmao.json")
36+
# Define which is the solute
37+
solute = AtomSelection(PDBTools.select(pdb, "protein"), nmols=1)
38+
# We intend to compute the contributions of residue 50 only
39+
residue50 = PDBTools.select(pdb, "residue 50")
40+
# Compute the group contribution to the MDDF
41+
residue50_contribution = contributions(R, SoluteGroup(residue50))
42+
# Now compute the coordination number
43+
residue50_coordination = coordination_number(R, SoluteGroup(residue50))
44+
#
45+
# Plot with twin y-axis
46+
#
47+
using Plots
48+
plot(R.d, residue50_contribution,
49+
xaxis="distance / Å",
50+
yaxis="MDDF contribution",
51+
linewidth=2, label=nothing, color=1
52+
)
53+
plot!(twinx(),R.d, residue50_coordination,
54+
yaxis="Coordination number",
55+
linewidth=2, label=nothing, color=2
56+
)
57+
plot!(title="Residue 50", framestyle=:box, subplot=1)
58+
```
59+
60+
With appropriate input data, this code produces:
61+
62+
```@raw html
63+
<center>
64+
<img width=60% src="../figures/coordination.png" width=80%>
65+
</center>
66+
```
67+
!!! tip
68+
There are some systems for which the normalization of the distributions is not
69+
necessary or possible. It is still possible to compute the coordination numbers,
70+
by running, instead of `mddf`, the `coordination_number` function:
71+
```
72+
coordination_number(trajectory_file, solute, solvent, options::Options)
73+
```
74+
This call will return a `Result` data structure but with all fields requiring
75+
normalization with zeros. In summary, this result
76+
data structure can be used to compute the coordination numbers, but not the MDDF, RDF, or KB integrals.
77+
78+
!!! compat
79+
The independent computation of coordination numbers was introduced in version 1.1.

‎docs/src/quickguide.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11

22
# Quick Guide
33

4-
Of course, follow the [installation](@ref Installation) instructions first.
5-
A complete working example is shown below, and in the section that follows each
6-
command is described in detail.
4+
First, follow the [installation](@ref Installation) instructions.
5+
Below is a complete working example, followed by detailed descriptions
6+
of each command.
77

88
## Basic example
99

‎docs/src/references.md

+50-1
Original file line numberDiff line numberDiff line change
@@ -43,4 +43,53 @@ If this package was useful to you, please cite the following papers:
4343

4444
* [MDLovoFit](http://m3g.iqm.unicamp.br/mdlovofit/home.shtml): Automatic identification of mobile and rigid substructures in molecular dynamics simulations and fractional structural fluctuation analysis.
4545

46-
46+
## Breaking changes
47+
48+
The syntax changes necessary to update script from version `1.X` to `2.X` of
49+
the package are:
50+
51+
### Atom selections
52+
53+
The previous `Selection` structure was renamed to `AtomSelection` for clarity.
54+
- Before:
55+
```julia
56+
water = Selection(water; natomspermol=3)
57+
```
58+
- Now:
59+
```julia
60+
water = AtomSelection(water; natomspermol=3)
61+
```
62+
63+
### Group contributions syntax
64+
65+
The syntax to computing group contributions is improved. Previously, the `contrib` or
66+
`contributions` functions required three somewhat redundant parameters.
67+
- Before:
68+
The call to `contributions` required 3 parameters: the `Selection` structure,
69+
the matrix of contributions, and the indexes of the atoms for which the
70+
contributions were desired:
71+
```julia
72+
h_contributions = contributions(solvent, R.solvent_atom, h_indexes)
73+
```
74+
- Now:
75+
The contributions are extracted from the `Result` data structure, by
76+
providing either a `SoluteGroup` or `SolventGroup` object, which are
77+
setup with the group names, group indexes, atom names, or atom indexes:
78+
```julia
79+
h_contributions = contributions(R, SolventGroup(h_indexes))
80+
```
81+
82+
### Frame weights
83+
84+
`frame_weights` is an option of the `mddf` execution. That is previously,
85+
they were defined in the `Options` data structure, and now they are passed
86+
to the `mddf` function.
87+
- Before:
88+
```julia
89+
options = Options(frame_weights=[1.0, 2.0], bulk_range=(8.0, 12.0))
90+
results = mddf(trajectory_file, solute, solvent, options)
91+
```
92+
- Now:
93+
```julia
94+
results = mddf(trajectory_file, solute, solvent, options; frame_weights=[1.0, 2.0])
95+
```

‎docs/src/tools.md

+1-76
Original file line numberDiff line numberDiff line change
@@ -1,87 +1,12 @@
11
# [Coordination numbers](@id Tools)
22

3-
- [Coordination numbers](@ref coordination_number)
4-
- [Overview of the solvent and solute properties](@ref overview)
53
- [Computing radial distribution functions](@ref radial_distribution)
4+
- [Overview of the solvent and solute properties](@ref overview)
65

76
```@meta
87
CollapsedDocStrings = true
98
```
109

11-
## [Coordination numbers](@id coordination_number)
12-
13-
The coordination number is the numerical count of how many molecules of a solvent is within a certain distance
14-
from the solute. The following function provides the functionality of retrieving coordination numbers and atom
15-
groups contributions to these numbers, given a `Result` data structure:
16-
17-
```@autodocs
18-
Modules = [ComplexMixtures]
19-
Pages = ["coordination_number.jl"]
20-
```
21-
22-
The function can be called without any argument besides the `Result` data structure, in which case the coordination number of the complete solute will
23-
be returned, as a function of the distance.
24-
25-
Alternatively, subgroups of the solute or the solvent can be selected, by providing `SoluteGroup` or `SolventGroup` objects as second arguments,
26-
initialized with the atoms of the subgroup, as a list of indices or a list of atoms generated by `PDBTools`. Note that, if a `SolventGroup`
27-
is defined we obtain the contributions of those solvent atoms to the coordination number *of the solute* (for instance, the sum of the
28-
contributions of all solvent atoms is the coordination number of the solute).
29-
30-
### Example
31-
32-
In the following example we compute the coordination number of the atoms of `residue 50` (which belongs to the solute - a protein) with the solvent atoms of TMAO, as a function of the distance. The plot produced will show side by side the residue contribution to the MDDF and the corresponding coordination number.
33-
34-
```julia
35-
# Load necessary packages
36-
using ComplexMixtures, PDBTools
37-
# Load data structure and previously computed results from a mddf calculation
38-
pdb = read_pdb("test/data/NAMD/structure.pdb")
39-
R = load("test/data/NAMD/protein_tmao.json")
40-
# Define which is the solute
41-
solute = AtomSelection(PDBTools.select(pdb, "protein"), nmols=1)
42-
# We intend to compute the contributions of residue 50 only
43-
residue50 = PDBTools.select(pdb, "residue 50")
44-
# Compute the group contribution to the MDDF
45-
residue50_contribution = contributions(R, SoluteGroup(residue50))
46-
# Now compute the coordination number
47-
residue50_coordination = coordination_number(R, SoluteGroup(residue50))
48-
#
49-
# Plot with twin y-axis
50-
#
51-
using Plots
52-
plot(R.d, residue50_contribution,
53-
xaxis="distance / Å",
54-
yaxis="MDDF contribution",
55-
linewidth=2, label=nothing, color=1
56-
)
57-
plot!(twinx(),R.d, residue50_coordination,
58-
yaxis="Coordination number",
59-
linewidth=2, label=nothing, color=2
60-
)
61-
plot!(title="Residue 50", framestyle=:box, subplot=1)
62-
```
63-
64-
With appropriate input data, this code produces:
65-
66-
```@raw html
67-
<center>
68-
<img width=60% src="../figures/coordination.png" width=80%>
69-
</center>
70-
```
71-
!!! tip
72-
There are some systems for which the normalization of the distributions is not
73-
necessary or possible. It is still possible to compute the coordination numbers,
74-
by running, instead of `mddf`, the `coordination_number` function:
75-
```
76-
coordination_number(trajectory_file, solute, solvent, options::Options)
77-
```
78-
This call will return a `Result` data structure but with all fields requiring
79-
normalization with zeros. In summary, this result
80-
data structure can be used to compute the coordination numbers, but not the MDDF, RDF, or KB integrals.
81-
82-
!!! compat
83-
The independent computation of coordination numbers was introduced in version 1.1.
84-
8510
## [Computing radial distribution functions](@id radial_distribution)
8611

8712
The distributions returned by the `mddf` function (the `mddf` and

0 commit comments

Comments
 (0)