From dfea543e99e844e5929cea0b5296af70d6cab1f1 Mon Sep 17 00:00:00 2001 From: Leandro Martinez Date: Wed, 4 Dec 2024 09:05:17 -0300 Subject: [PATCH 1/2] remove deprecated contourf_per_residue function --- docs/src/tools.md | 10 ---- ext/Plotting.jl | 108 +++++------------------------------------ src/ComplexMixtures.jl | 2 - src/tools/plotting.jl | 19 -------- 4 files changed, 12 insertions(+), 127 deletions(-) delete mode 100644 src/tools/plotting.jl diff --git a/docs/src/tools.md b/docs/src/tools.md index 9e6cf4d8..afa244c6 100644 --- a/docs/src/tools.md +++ b/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}) -``` - - diff --git a/ext/Plotting.jl b/ext/Plotting.jl index cff1b3ca..b9f1be23 100644 --- a/ext/Plotting.jl +++ b/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 diff --git a/src/ComplexMixtures.jl b/src/ComplexMixtures.jl index 12a9cf26..00072df9 100644 --- a/src/ComplexMixtures.jl +++ b/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") diff --git a/src/tools/plotting.jl b/src/tools/plotting.jl deleted file mode 100644 index ae6de792..00000000 --- a/src/tools/plotting.jl +++ /dev/null @@ -1,19 +0,0 @@ -""" - contourf_per_residue - -This function requires loading the `Plots` package. - -""" -function contourf_per_residue(args...; kwargs...) - throw(ArgumentError("""\n - - contourf_per_residue could not be run. This can have two causes: - - 1. This function requires loading the `Plots` package. - Use `using Plots` before calling this function. - 2. The function was called with the wrong arguments. - Please read the documentation, by typing `? contourf_per_residue`. - - """)) -end - From c2a92e6c043fd8d1919c9e3739d2188e268b62e2 Mon Sep 17 00:00:00 2001 From: Leandro Martinez Date: Wed, 4 Dec 2024 09:05:32 -0300 Subject: [PATCH 2/2] organize documentation --- docs/src/contributions.md | 21 ++++++++++++++------- docs/src/multiple.md | 8 ++++++++ docs/src/options.md | 4 ++++ docs/src/results.md | 3 --- docs/src/save.md | 12 ++++++++++++ docs/src/selection.md | 29 ++++++++++++++++------------- src/AtomSelection.jl | 6 ++---- 7 files changed, 56 insertions(+), 27 deletions(-) diff --git a/docs/src/contributions.md b/docs/src/contributions.md index db6693ce..1abbd71f 100644 --- a/docs/src/contributions.md +++ b/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 -``` diff --git a/docs/src/multiple.md b/docs/src/multiple.md index 6d67d7e3..749ef526 100644 --- a/docs/src/multiple.md +++ b/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 diff --git a/docs/src/options.md b/docs/src/options.md index 5123c5d3..feaf5e07 100644 --- a/docs/src/options.md +++ b/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 diff --git a/docs/src/results.md b/docs/src/results.md index 8822d86d..6ba08237 100644 --- a/docs/src/results.md +++ b/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 ``` diff --git a/docs/src/save.md b/docs/src/save.md index 90bff9a8..3a20715d 100644 --- a/docs/src/save.md +++ b/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 diff --git a/docs/src/selection.md b/docs/src/selection.md index 8fb15b5e..634f0325 100644 --- a/docs/src/selection.md +++ b/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 ``` - - - - - - - - diff --git a/src/AtomSelection.jl b/src/AtomSelection.jl index 3f8f8918..6121000c 100644 --- a/src/AtomSelection.jl +++ b/src/AtomSelection.jl @@ -189,7 +189,7 @@ 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, @@ -197,7 +197,6 @@ The structure can be initialized in different ways: 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,7 +235,7 @@ 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, @@ -244,7 +243,6 @@ julia> length(atom_group_names(atsel)) 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.