Merge pull request #60 from m3g/doc_organization

Doc organization

docs/src/contributions.md

@@ -1,3 +1,7 @@
+```@meta
+CollapsedDocStrings = true
+```
+
 # [Atomic and group contributions](@id contributions)
 
 One of the interesting features of Minimum-Distance distributions is
@@ -37,8 +41,16 @@ the contributions of every type of atom of the solute and the solvent.
 These contributions can be retrieved using the `contributions` function,
 with the `SoluteGroup` and `SolventGroup` selectors.
 
-For example, if the MDDF of water (solvent) relative to a solute was computed,
-and water has atom names `OH2, H1, H2`, one can retrieve the contributions
+```@docs
+contributions
+SolventGroup
+SoluteGroup
+```
+
+### Example: computing the oxygen contributions of water
+
+Here we show the MDDF of water (solvent) relative to a solute.
+Water molecules have atom names `OH2, H1, H2`, one can retrieve the contributions
 of the oxygen atom with:
 
 ```julia
@@ -140,8 +152,3 @@ hydrogen-bonding distances, but much less in general. Of course all
 selection options could be used, to obtain the contributions of specific
 types of residues, atoms, the backbone, the side-chains, etc. 
 
-## Reference functions
-
-```@docs
-contributions
-```

docs/src/multiple.md

@@ -1,3 +1,7 @@
+```@meta
+CollapsedDocStrings = true
+```
+
 # Working with multiple trajectories
 
 Very commonly, one has multiple trajectories of the same system, and we
@@ -53,6 +57,10 @@ second and third trajectories have 1000 frames each, the first
 trajectory will have a weight of 0.5 on the final results. The `merge` function
 can be used to merge previously merged results with new results as well.
 
+```@docs
+merge
+```
+
 !!! tip
 
     The names of the files and

docs/src/options.md

@@ -1,3 +1,7 @@
+```@meta
+CollapsedDocStrings = true
+```
+
 # [Options](@id options)
 
 There are some options to control what exactly is going to be computed

docs/src/results.md

@@ -181,9 +181,6 @@ The complete data available is:
 
 ```@docs
 Result
-load(::String, ::Type{Result})
-save(::String, ::Result)
-merge(::Vector{Result})
 overview(::Result)
 ComplexMixtures.Density
 ```

docs/src/save.md

@@ -1,3 +1,7 @@
+```@meta
+CollapsedDocStrings = true
+```
+
 # [Save and load results](@id save)
 
 Three functions serve the purpose of saving and loading the results
@@ -12,6 +16,10 @@ where `results` is the output data structure of the `mddf()`
 calculation, and `results.json` is the output file to be created. The
 file is written in `JSON` format, thus is not naturally human-readable.
 
+```@docs
+save(::String, ::Result)
+```
+
 ## Load saved data
 
 ```julia
@@ -20,6 +28,10 @@ results = load("results.json")
 The `load` function reads the output of the `save` function above,
 and restores the results data structure.
 
+```@docs
+load(::String, ::Type{Result})
+```
+
 ## Write data in a human-readable format
 
 If you Want the results to be written as simple ASCII tables such that

docs/src/selection.md

@@ -1,3 +1,6 @@
+```@meta
+CollapsedDocStrings = true
+```
 
 # [Solute and solvent selections](@id selections)
 
@@ -8,6 +11,15 @@ To construct a `AtomSelection` data structure, one needs to provide, at least,
 the (1-based) indices of the atoms that belong to the selection, and either
 the number of atoms of each molecule or the number of molecules in the selection.
 
+```@docs
+AtomSelection
+AtomSelection(::Any)
+```
+
+Alternatively, and more practically, atom selections defined by the `PDBTools`
+package, which can interface with the selection syntax of `VMD`, can be used,
+as described in the following sections.
+
 ## Using the PDBTools package
 
 The [PDBTools](https://m3g.github.io/PDBTools) package helps the construction of 
@@ -157,17 +169,8 @@ julia> result = mddf(trajectory_file, solute, solvent, Options(bulk_range=(8.0,
 julia> acidic_residue_contributions = contributions(result, SoluteGroup("acidic residues"))
 ```
 
-## Reference functions
-
-```@autodocs
-Modules = [ComplexMixtures]
-Pages = ["AtomSelection.jl"]
+```@docs
+atom_group
+atom_group_name
+atom_group_names
 ```
-
-
-
-
-
-
-
-

docs/src/tools.md

@@ -189,13 +189,3 @@ julia> overview = overview(results);
 julia> overview.solute_molar_volume
 657.5051512801567
 ```
-
-## Legacy 
-
-The legacy function `contourf_per_residue` provides a direct way to produce contour plots:
-
-```@docs
-contourf_per_residue(::Result, ::AbstractVector{PDBTools.Atom})
-```
-
-

ext/Plotting.jl

@@ -163,96 +163,7 @@ function _density2D(
     return plt
 end
 
-#
-# This is a legacy function, will probably be deprecated some day.
-#
-ComplexMixtures.contourf_per_residue(rc::ResidueContributions; kwargs...) = Plots.contourf(rc; kwargs...)
-"""
-    contourf_per_residue(
-        results::Result, atoms::AbstractVector{<:PDBTools.Atom}; 
-        residue_range=nothing, 
-        dmin=1.5, dmax=3.5, 
-        oneletter=false,
-        xlabel="Residue",
-        ylabel="r / Å",
-        type=:mddf,
-        clims=nothing,
-        colorscale=:tempo,
-    )
-
-Plot the contribution of each residue to the solute-solvent pair distribution function as a contour plot.
-This function requires loading the `Plots` package.
-
-# Arguments
-
-- `results::Result`: The result of a `mddf` call.
-- `atoms::AbstractVector{<:Atom}`: The atoms of the solute.
-
-# Optional arguments
-
-- `residue_range`: The range of residues to plot. Default is all residues. Use
-  a step to plot every `n` residues, e.g., `1:2:30`.
-- `dmin::Real`: The minimum distance to plot. Default is `1.5`.
-- `dmax::Real`: The maximum distance to plot. Default is `3.5`.
-- `oneletter::Bool`: Use one-letter residue codes. Default is `false`. One-letter codes are only available for the 20 standard amino acids.
-- `xlabel` and `ylabel`: Labels for the x and y axes. Default is `"Residue"` and `"r / Å"`.
-- `type::Symbol`: That data to plot. Default is `:mddf` for MDDF contributions. Options are `:coordination_number`, and `:mddf_count`.
-- `clims`: The color limits for the contour plot.
-- `colorscale`: The color scale for the contour plot. Default is `:tempo`. We suggest `:bwr` if the zero
-  is at the middle of the color scale (use `clims` to adjust the color limits).
-
-# Example
-
-```julia-repl
-julia> using ComplexMixtures, Plots, PDBTools
-
-julia> results = load("mddf.json")
-
-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-repl
-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.
-
-"""
-function ComplexMixtures.contourf_per_residue(
-    results::Result, atoms::AbstractVector{<:Atom};
-    residue_range::AbstractRange=resnum(first(atoms)):resnum(last(atoms)),
-    dmin=1.5, dmax=3.5,
-    type=:mddf,
-    kargs...
-)
-    first_atom = findfirst(at -> resnum(at) == first(residue_range), atoms)
-    last_atom = findfirst(at -> resnum(at) == last(residue_range), atoms)
-    if isnothing(first_atom) || isnothing(last_atom)
-        throw(ArgumentError("""\n
-
-            The residue_range $residue_range is out of bounds.
-
-            The first and last residue numbers of the selection are: $(resnum(first(atoms))) and $(resnum(last(atoms))).
-
-        """
-        ))
-    end
-    rc = ResidueContributions(results, atoms[first_atom:last_atom]; dmin, dmax, type)
-    return Plots.contourf(rc; step=step(residue_range), kargs...)
-end
-
-@testitem "contourf/contourf_per_residue" begin
+@testitem "contourf" begin
     using ComplexMixtures
     using ComplexMixtures.Testing
     using Plots
@@ -308,24 +219,29 @@ end
 
     # Slice and plot
     rc2 = rc[10:5:20]
-    plt = contourf_per_residue(results, protein; residue_range=50:2:70)
+    plt = contourf(rc2)
+    savefig(plt, tmpplot)
+    @test isfile(tmpplot)
+
+    plt = contourf(rc2, oneletter=true)
     savefig(plt, tmpplot)
     @test isfile(tmpplot)
 
-    plt = contourf_per_residue(results, protein; residue_range=50:75, oneletter=true)
+    plt = contourf(rc[1:25])
     savefig(plt, tmpplot)
     @test isfile(tmpplot)
 
-    plt = contourf_per_residue(results, protein; residue_range=50:75)
+    plt = contourf(rc[1:2:25])
     savefig(plt, tmpplot)
     @test isfile(tmpplot)
 
-    plt = contourf_per_residue(results, protein; residue_range=50:2:70)
+    plt = contour(rc[1:2:25])
     savefig(plt, tmpplot)
     @test isfile(tmpplot)
 
-    @test_throws ArgumentError contourf_per_residue(results, SoluteGroup("ALA"))
-    @test_throws ArgumentError contourf_per_residue(results, protein; residue_range=50:80)
+    plt = heatmap(rc[1:2:25])
+    savefig(plt, tmpplot)
+    @test isfile(tmpplot)
 
 end
 

src/AtomSelection.jl

@@ -189,15 +189,14 @@ 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::Integer = 0, 
         natomspermol::Integer = 0,
         group_atom_indices::Union{Nothing,Vector{<:Vector{<:Int}}} = nothing,
         group_names::Vector{<:AbstractString} = String[]
     ) 
-```
 
 The indices of the atoms will be retrived from the
 indices of the atoms as defined in the PDB file, thus the PDB file must correspond to the same
@@ -236,15 +235,14 @@ julia> length(atom_group_names(atsel))
 
 2. Lower level: initialize the structure providing the index of atoms and groups.
 
-```
+
     AtomSelection(
         indices::AbstractVector{<:Integer};
         nmols::Int = 0,
         natomspermol::Int = 0,
         group_atom_indices::Union{Nothing,AbstractVector{<:AbstractVector{<:Int}}} = nothing,
         group_names::AbstractVector{<:AbstractString} = String[]
     )
-```
 
 Construct an AtomSelection structure from the most low-level information: the index of atoms and groups.
 

src/ComplexMixtures.jl

@@ -35,7 +35,6 @@ export contributions
 export coordination_number
 export gr
 export grid3D
-export contourf_per_residue
 
 # Module for testing
 include("./Testing.jl")
@@ -83,7 +82,6 @@ include("./tools/coordination_number.jl")
 include("./tools/gr.jl")
 include("./tools/grid3D.jl")
 include("./tools/write.jl")
-include("./tools/plotting.jl")
 
 # Precompilation directives
 include("precompile.jl")