rename specialize_resnames!

Author: jgreener64

NEWS.md

@@ -1,5 +1,9 @@
 # BioStructures.jl release notes
 
+## v4.7.0 - Sep 2025
+
+* `specializeresnames!` is added, allowing residues to be renamed to reflect the bonding topology.
+
 ## v4.6.1 - Sep 2025
 
 * mmCIF file parsing is made more robust with respect to the available fields, and for example will use `_atom_site.label_atom_id` when `_atom_site.auth_atom_id` is not available.

docs/src/documentation.md

@@ -568,7 +568,7 @@ Similar to [`ContactMap`](@ref), contacts are found between any element type pas
 So if you wanted the graph of chain contacts in a protein complex you could give a [`Model`](@ref) as the first argument.
 
 Calling `MetaGraph` on a [`Chain`](@ref) without a contact distance does something different: it constructs a graph of atoms where edges are determined by the known bonds of standard amino acids in the chain.
-Hydrogens should be present and atom names should match those in OpenMM. See [`specialize_resnames!`](@ref) to
+Hydrogens should be present and atom names should match those in OpenMM. See [`specializeresnames!`](@ref) to
 ensure that residue names have been specialized to their actual configuration in the protein:
 
 ```julia-repl
@@ -586,11 +586,11 @@ julia> mg = MetaGraph(struc_M3YHX5["A"]; strict=false)
 {1833, 1850} undirected Int64 metagraph with Float64 weights defined by :weight (default weight 1.0)
 ```
 
-but if you really want to get all the bonds, you'd better use the default `strict=true`.
+But if you really want to get all the bonds, you'd better use the default `strict=true`.
 Fortunately, this example only requires residue renaming:
 
 ```julia-repl
-julia> specialize_resnames!(struc_M3YHX5)
+julia> specializeresnames!(struc_M3YHX5)
 MolecularStructure AF-M3YHX5-F1-model_v4_hydrogens.cif with 1 models, 1 chains (A), 112 residues, 1833 atoms
 
 julia> mg = MetaGraph(struc_M3YHX5["A"])

src/model.jl

@@ -39,7 +39,6 @@ export
     defaultresname,
     defaultresidue,
     resnames,
-    specialize_resnames!,
     sscode,
     sscode!,
     chain,
@@ -56,6 +55,7 @@ export
     modelnumbers,
     models,
     defaultmodel,
+    specializeresnames!,
     sequentialresidues,
     collect,
     collectmodels,
@@ -1099,15 +1099,19 @@ This is the `Model` with the lowest model number.
 defaultmodel(struc::MolecularStructure) = first(sort(collect(values(models(struc)))))
 
 """
-    specialize_resnames!(r)
+    specializeresnames!(el)
 
-If `r` is a histidine residue, rename it to reflect a specific protonation configuration (HID,
-HIE, or HIP) based on the presence of HD1 and HE2 atoms. For any other residue,
-`r` will be unchanged.
+Rename residues to reflect the bonding topology.
+
+Renames histidine residues to reflect a specific protonation configuration
+(HID, HIE, or HIP) based on the presence of HD1 and HE2 atoms.
+Renames N-terminal and C-terminal (e.g. ALA -> NALA) residues based on the
+presence of certain atoms.
+Other residues remain unchanged.
 
 Hydrogens must have been assigned prior to calling this function.
 """
-function specialize_resnames!(r::Residue)
+function specializeresnames!(r::Residue)
     rname = resname(r)
     if rname == "HIS"
         hd1 = findatombyname(r, "HD1"; strict=false)
@@ -1130,21 +1134,24 @@ function specialize_resnames!(r::Residue)
     end
     return r
 end
-specialize_resnames!(r::DisorderedResidue) = (foreach(specialize_resnames!, collectresidues(r; expand_disordered=true)); r)
-function specialize_resnames!(c::Chain)
+
+specializeresnames!(r::DisorderedResidue) = (foreach(specializeresnames!, collectresidues(r; expand_disordered=true)); r)
+
+function specializeresnames!(c::Chain)
     for (key, res) in c.residues
         if isa(res, DisorderedResidue)
             # Create a new `names` dictionary with specialized residue names
-            names = Dict((specialize_resnames!(r); resname(r, strip=false) => r) for r in values(res.names))
+            names = Dict((specializeresnames!(r); resname(r, strip=false) => r) for r in values(res.names))
             c.residues[key] = DisorderedResidue(names, resname(res.names[defaultresname(res)]))
         else
-            specialize_resnames!(res)
+            specializeresnames!(res)
         end
     end
     return c
 end
-specialize_resnames!(m::Model) = (foreach(specialize_resnames!, m); m)
-specialize_resnames!(s::MolecularStructure) = (foreach(specialize_resnames!, s); s)
+
+specializeresnames!(m::Model) = (foreach(specializeresnames!, m); m)
+specializeresnames!(s::MolecularStructure) = (foreach(specializeresnames!, s); s)
 
 # Sort lists of elements
 

test/runtests.jl

@@ -3512,7 +3512,7 @@ end
     @test_throws KeyError MetaGraph(struc_1AKE["A"])   # it's missing hydrogens
     struc_M3YHX5 = read(joinpath(@__DIR__, "data", "AF-M3YHX5-F1-model_v4_hydrogens.cif"), MMCIFFormat)
     @test_throws KeyError MetaGraph(struc_M3YHX5["A"]; strict=true)  # residues need to be renamed
-    specialize_resnames!(struc_M3YHX5)
+    specializeresnames!(struc_M3YHX5)
     mg = MetaGraph(struc_M3YHX5["A"]; strict=true)
     @test nv(mg) == 1833
 
@@ -3648,9 +3648,9 @@ end
     rm(temp_filename)
 end
 
-@testset "ff19SB-compliant residue names for added hydrogens" begin
+@testset "Renaming residues" begin
     struc = read(joinpath(@__DIR__, "data", "AF-M3YHX5-F1-model_v4_hydrogens.cif"), MMCIFFormat)
-    specialize_resnames!(struc)
+    specializeresnames!(struc)
     A = struc["A"]
     @test resname(first(A)) == "NMET"
     @test resname(last(A)) == "CSER"
@@ -3673,7 +3673,7 @@ end
     r = struc_1res['A'][1]
     @test r isa DisorderedResidue
     @test resname(defaultresidue(r)) == "HIS"
-    specialize_resnames!(struc_1res)
+    specializeresnames!(struc_1res)
     r = struc_1res['A'][1]
     @test r isa DisorderedResidue
     @test resname(defaultresidue(r)) == "HIE"