docs formatting changes

docs/src/contrib.md

@@ -33,7 +33,7 @@ the contributions of every type of atom of the solute and the solvent.
 These data is available at the `results.solute_atom` and
 `results.solvent_atom` arrays: 
 
-```julia
+```julia-repl
 julia> results.solute_atom
 50×1463 Array{Float64,2}:
  0.0  0.0      0.0  …  0.0  0.0  0.0
@@ -49,7 +49,6 @@ julia> results.solvent_atom
  ...
  0.26087    0.26087    0.173913
  0.25641    0.0854701  0.170940
-
 ```
 
 Here, `50` is the number of bins of the histogram, whose distances are
@@ -63,13 +62,12 @@ The three columns of the `results.solvent_atom` array correspond to the
 thee atoms of the water molecule in this example. The sequence of atoms
 correspond to that of the PDB file, but can be retrieved with:
 
-```julia
+```julia-repl
 julia> solvent.names
 3-element Array{String,1}:
  "OH2"
  "H1"
  "H2"
-
 ```
 
 Therefore, if the first column of the `results.solvent_atom` vector is
@@ -82,7 +80,6 @@ using Plots
 plot(results.d,results.mddf,label="Total MDDF",linewidth=2)
 plot!(results.d,results.solvent_atom[:,1],label="OH2",linewidth=2)
 plot!(xlabel="Distance / Å",ylabel="MDDF")
-
 ```
 
 ```@raw html
@@ -112,7 +109,7 @@ provide a list of indexes to the `contrib` function. For example,
 to select the hydrogen atoms, which are the second and third atoms of the 
 water molecule, use:
 
-```julia
+```julia-repl
 julia> indexes = [ 2, 3 ]
 julia> h_contrib = contrib(solvent,R.solvent_atom,indexes)
 500-element Array{Float64,1}:
@@ -121,14 +118,13 @@ julia> h_contrib = contrib(solvent,R.solvent_atom,indexes)
  ⋮
  0.7742706465861815
  0.8084139794974875
-
 ```
+
 Plotting both the oxygen (`index = 1`) and hydrogen contributions
 results in:
 
 ```@raw html
 <img src="../figures/h_and_oh2.png" width="60%">
-
 ```
 
 ### Selecting by atom name
@@ -141,7 +137,6 @@ oxygen = ["OH2"]
 o_contrib = contrib(solvent,R.solvent_atom,oxygen) 
 hydrogens = ["H1","H2"]
 h_contrib = contrib(solvent,R.solvent_atom,hydrogens)
-
 ```
 
 The above plot can be obtained with:
@@ -151,7 +146,6 @@ plot(results.d,results.mddf,label="Total MDDF",linewidth=2)
 plot!(results.d,o_contrib,label="OH2",linewidth=2)
 plot!(results.d,h_contrib,label="Hydrogen atoms",linewidth=2)
 plot!(xlabel="Distance / Å",ylabel="MDDF")
-
 ```
 
 ## General selections using PDBTools
@@ -172,8 +166,8 @@ charged_contrib = contrib(solute,R.solute_atom,charged_residues)
 
 neutral_residues = PDBTools.select(atoms,"neutral")
 neutral_contrib = contrib(solute,R.solute_atom,neutral_residues)
-
 ```
+
 The `charged` and `neutral` outputs are vectors containing the
 contributions of these residues to the total MDDF. The corresponding
 plot is:   
@@ -183,13 +177,11 @@ plot(results.d,results.mddf,label="Total MDDF",linewidth=2)
 plot!(results.d,charged_contrib,label="Charged residues",linewidth=2)
 plot!(results.d,neutral_contrib,label="Neutral residues",linewidth=2)
 plot!(xlabel="Distance / Å",ylabel="MDDF")
-
 ```
 Resulting in:
 
 ```@raw html
 <img src="../figures/charged_and_neutral.png" width="60%">
-
 ```
 
 Note here how charged residues contribute strongly to the peak at

docs/src/examples.md

@@ -18,8 +18,10 @@ Image of the system of the example: a protein solvated by a mixture of glycreol
 - Download and install [Julia](https://julialang.org)
 
 - Install the required packages. Within Julia, do:
-```julia
-julia> ] add ComplexMixtures, PDBTools, Plots, LaTeXStrings, Formatting
+```julia-repl
+julia> import Pkg
+
+julia> Pkg.add(["ComplexMixtures", "PDBTools", "Plots", "LaTeXStrings", "Formatting"])
 ```
 
 - Get the files:
@@ -45,7 +47,7 @@ This example illustrates the regular usage of `ComplexMixtures`, to compute the
 
 ```bash
 cd ComplexMixturesExamples/Protein_in_Glycerol/MDDF
-julia mddf.jl
+julia -t auto mddf.jl
 ```
 
 ### Detailed explanation of the example:
@@ -76,7 +78,7 @@ solvent = Selection(glyc,natomspermol=14)
 
 Read and setup the Trajectory structure required for the computations:
 ```julia
-trajectory = Trajectory("../Data/glyc50.dcd",solute,solvent)
+trajectory = Trajectory("../Data/glyc50_complete.dcd",solute,solvent)
 ```
 
 Run the calculation and get results:
@@ -128,11 +130,13 @@ First, we will plot the MDDF and the corresponding Kirkwood-Buff integral, which
 
 ```julia
 plot(layout=(1,2))
-plot!(results.d,results.mddf,
-      xlabel=L"r/\AA",ylabel="mddf",subplot=1)
+plot!(results.d,results.mddf,xlabel=L"r/\AA",ylabel="mddf",subplot=1)
 hline!([1],linestyle=:dash,linecolor=:gray,subplot=1)
-plot!(results.d,results.kb/1000, #to L/mol
-      xlabel=L"r/\AA",ylabel=L"G_{us}/\mathrm{L~mol^{-1}}",subplot=2)
+plot!(
+    results.d,results.kb/1000, #to L/mol
+    xlabel=L"r/\AA",ylabel=L"G_{us}/\mathrm{L~mol^{-1}}",
+    subplot=2
+)
 plot!(size=(800,300),margin=4mm)
 savefig("./mddf.pdf")
 ```
@@ -145,7 +149,7 @@ This will produce the following plot:
 </center>
 ```
 
-#### Atomic contributions to the MDDF
+### Atomic contributions to the MDDF
 
 Selecting the atoms corresponding to the hydroxyl groups, and of the aliphatic carbons of Glycerol. Here we list the types of the atoms as specified by the force-field.
 ```julia
@@ -282,13 +286,17 @@ labels = PDBTools.oneletter.(resname.(residues)).*format.(resnum.(residues))
 And, finally, we produce the plot, with a series of options that make this particular contour plot look nice:
 
 ```julia
-contourf(irange,R.d[idmin:idmax],rescontrib[idmin:idmax,irange],
-         color=cgrad(:tempo),linewidth=0.1,linecolor=:black,
-         colorbar=:none,levels=5,
-         xlabel="Residue",ylabel=L"r/\AA",
-         xticks=(irange,labels[irange]),xrotation=60,
-         xtickfont=font(6,plot_font),
-         size=(500,280))
+contourf(
+    irange, # x
+    R.d[idmin:idmax], # y
+    rescontrib[idmin:idmax,irange], # z
+    xlabel="Residue", ylabel=L"r/\AA",
+    xticks=(irange,labels[irange]), xrotation=60,
+    xtickfont=font(6,plot_font),
+    color=cgrad(:tempo), linewidth=0.1, linecolor=:black,
+    colorbar=:none, levels=5,
+    size=(500,280)
+)
 ```
 
 The final figure is saved as a `pdf` file:
@@ -375,11 +383,14 @@ solute = Selection(protein,nmols=1)
 The 3D grid representing the density around the protein is computed with the `grid3D` function provided by `ComplexMixtures`. It receives the `solute` structure (of type `Selection`), the list of solute atoms (of type `PDBTools.Atoms`, as the `protein` selection above), the name of the output file and some optional parameters to define the grid. Here we compute the grid only between 1.5 and 3.5Å, characterizing the first and second solvation shells. The grid has by default a `step` of 0.5Å. 
 
 ```julia
-grid = grid3D(solute=solute,
-              solute_atoms=protein,
-              mddf_result=R,
-              output_file="grid.pdb",
-              dmin=1.5,dmax=3.5)
+grid = grid3D(
+    solute=solute,
+    solute_atoms=protein,
+    mddf_result=R,
+    output_file="grid.pdb",
+    dmin=1.5,
+    dmax=3.5
+)
 ```
 
 The command above will generate the grid, save it to `grid.pdb` and let it available in the `grid.pdb` array of atoms, for further inspection, if desired. 

docs/src/installation.md

@@ -4,24 +4,21 @@ First you need to install the Julia language in your platform, from:
 [http://julialang.org](http://julialang.org). Julia version 1.6 or greater is required.
 
 Next, run julia, and within the julia REPL interface, install the ComplexMixtures package using
-```julia
+```julia-repl
 julia> import Pkg
 
 julia> Pkg.add("ComplexMixtures")
-
 ```
-or simply
-```julia
+or simply (you cannot copy/paste this, the `]` will take you to the `pkg>` prompt):
+```julia-repl
 julia> ] add ComplexMixtures
-
 ```
 
 To follow all the examples provided in this manual, the 
 [PDBTools](http://m3g.iqm.unicamp.br/PDBTools) 
 and [Plots](http://docs.juliaplots.org/latest/) have to be installed as well:
-```julia
+```julia-repl
 julia> ] add PDBTools, Plots
-
 ```
 
 If you are first-time `julia` user, load these packages for the first
@@ -30,7 +27,7 @@ take quite a while when done for the first time, because it is compiled
 at this point (this was greatly improved in Julia versions greater than 1.6, which
 are highly recommended). To load the packages, use:
 
-```
+```julia
 using ComplexMixtures, PDBTools, Plots
 ```
 
@@ -41,23 +38,18 @@ be used following the instructions and examples.
     By loading the package with 
     ```julia
     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
     ```julia
     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
-    accronym. For example:
+    To avoid having to write `ComplexMixtures` all the time, define an accronym. For example:
     ```julia
-    import ComplexMixtures 
-    const CM = ComplexMixtures
+    import ComplexMixtures as CM
     CM.mddf(...)
-
     ```
 

docs/src/multiple.md

@@ -11,14 +11,13 @@ Let us assume that we have three Gromacs trajectories, with file names
 these file names:
 
 ```julia
-trajs = [ "traj1.xtc" , "traj2.xtc" , "traj3.xtc" ]
+trajectory_files = [ "traj1.xtc" , "traj2.xtc" , "traj3.xtc" ]
 ```
 
-And define a vector of `Result` types with 3 positions, with undefined
-initialization:
+And define an empty vector of `Result` structures:
 
 ```julia
-results = Vector{Result}(undef,3)
+results = Result[]
 ```
 
 ### Run the calculations in a loop
@@ -30,9 +29,10 @@ simple loop, such as
 atoms = PDBTools.readPDB("./system.pdb")
 solute = Selection(atoms,"protein",nmols=1)
 solvent = Selection(atoms,"resname TMAO",,natomspermol=14)
-for i in 1:3 # alternatively use 1:length(trajs) 
-  trajectory = Trajectory(trajs[i],solute,solvent)
-  results[i] = mddf(trajectory)
+for file in trajectory_files
+  trajectory = Trajectory(file,solute,solvent)
+  # compute the MDDF data and push the result to the results array
+  push!(results, mddf(trajectory))
 end
 ```
 
@@ -58,7 +58,7 @@ can be used to merge previously merged results with new results as well.
     The names of the files and
     and weights are stored in the `R.files` and `R.weights` vectors of
     the results structure:
-    ```julia
+    ```julia-repl
     julia> R.files
     3-element Array{String,1}:
      "./traj1.xtc"

docs/src/quickguide.md

@@ -55,10 +55,9 @@ julia> include("example.jl")
 ```
 or directly with:
 ```
-% julia -t auto example.jl
+julia -t auto example.jl
 ```
-where `-t auto` is optional and defines how many processors will be used
-in the calculation. It is highly recommended to use multi-threading!
+where `-t auto` will launch `julia` with multi-threading. It is highly recommended to use multi-threading!
 
 !!! note
     Julia compiles the code the first time it is run in each section. Thus, running script from the command line with, for example, `julia -t auto example.jl` may appear slow, particularly if you are modifying the script interactively. Ideally, *do not restart Julia*, just repeatedly include your script in the same Julia section. The second time the script is loaded will be much faster. For example:

docs/src/results.md

@@ -11,7 +11,7 @@ such that the `results` variable contain the `Result` data structure. By
 default, the histograms contain 500 bins (`binstep=0.002` and
 `cutoff=10.`) such that all data-vectors will contain 500 lines.
 
-To know how to save and load saved data, read the [next](@ref save) section.
+To learn how to save and load saved data, read the [next](@ref save) section.
 
 ## The Result data structure: main data
 
@@ -24,15 +24,14 @@ The following vector will contain values ranging from 0. to `cutoff`,
 and the distance at each bin is the distance in that bin for which half
 of the volume of the bin is within `d`, and half of the volume is above
 `d`, if the volume was spherical: 
-```julia
+```julia-repl
 julia> results.d
 500-element Array{Float64,1}:
  0.015874010519682
  0.033019272488946275
  ⋮
  9.970010030080179
  9.99001000999998
-
 ```
 
 ## Minimum-distance distribution function: `results.mddf`
@@ -41,7 +40,7 @@ The `results.mddf` vector will contain the main result, which the
 minimum-distance distribution function. For a properly-sampled
 simulation, it will be zero at very short distances and converge to 1.0
 for distances smaller than the `cutoff`:
-```julia
+```julia-repl
 julia> results.mddf
 500-element Array{Float64,1}:
  0.0
@@ -70,7 +69,7 @@ plot(results.d,results.mddf,xlabel="d/A",ylabel="mddf(d) / L/mol")
 The `results.kb` vector will contain the Kirkwood-Buff integral computed
 as a function of the minimum-distance to the solute. For properly
 sampled simulations, it is expected to converge at large distances.  
-```julia
+```julia-repl
 julia> results.kb
 500-element Array{Float64,1}:
      0.0
@@ -79,7 +78,6 @@ julia> results.kb
      ⋮
     0.72186381783
     1.13624162115
-
 ```
 
 A typical plot of `results.kb` as a function of `results.d` will look