rename PDB to PDBFormat etc.

Author: jgreener64

.gitignore

@@ -5,5 +5,6 @@ docs/build/
 docs/site/
 .DS_Store
 benchmark/tune.json
+benchmark/results
 Manifest.toml
 *.swp

benchmark/benchmarks.jl

@@ -1,15 +1,18 @@
 # Benchmark suite for BioStructures
-# Run with something like:
+# Run with the following from the package base directory:
 #   using BioStructures
 #   using PkgBenchmark
 #   results = benchmarkpkg(".")
 #   export_markdown(out_file, results)
 
 using BioStructures
 using BenchmarkTools
+using BioAlignments
 import BioCore # Imported to avoid clash with BioGenerics distance
 using BioSequences
-import MMTF as MMTFPkg # Imported to avoid clash with MMTF name
+using Graphs
+import MMTF # Imported to avoid clash with writemmtf
+using MetaGraphs
 using Random
 
 # Use files in BioFmtSpecimens
@@ -21,22 +24,22 @@ temp_filename, io = mktemp()
 close(io)
 
 pdbids = ["1AKE", "1EN2", "1SSU"]
-formats = Dict("PDB"=> PDB, "mmCIF"=> MMCIF, "MMTF"=> MMTF)
-writefunctions = Dict("PDB"=> writepdb, "mmCIF"=> writemmcif, "MMTF"=> writemmtf)
+formats = Dict("PDB" => PDBFormat, "mmCIF" => MMCIFFormat, "MMTF" => MMTFFormat)
+writefunctions = Dict("PDB" => writepdb, "mmCIF" => writemmcif, "MMTF" => writemmtf)
 
 const SUITE = BenchmarkGroup(
-        [],
-        "read"   => BenchmarkGroup([], [f=> BenchmarkGroup() for f in keys(formats)]...),
-        "write"  => BenchmarkGroup([], [f=> BenchmarkGroup() for f in keys(formats)]...),
-        "dict"   => BenchmarkGroup(),
-        "model"  => BenchmarkGroup(),
-        "collect"=> BenchmarkGroup(),
-        "spatial"=> BenchmarkGroup(),
+    [],
+    "read"    => BenchmarkGroup([], [f => BenchmarkGroup() for f in keys(formats)]...),
+    "write"   => BenchmarkGroup([], [f => BenchmarkGroup() for f in keys(formats)]...),
+    "dict"    => BenchmarkGroup(),
+    "model"   => BenchmarkGroup(),
+    "collect" => BenchmarkGroup(),
+    "spatial" => BenchmarkGroup(),
 )
 
 struc = Dict{String, MolecularStructure}()
 for pdbid in pdbids
-    struc[pdbid] = read(testfilepath("PDB", "$pdbid.pdb"), PDB)
+    struc[pdbid] = read(testfilepath("PDB", "$pdbid.pdb"), PDBFormat)
 end
 
 for pdbid in pdbids

docs/src/api.md

@@ -9,7 +9,7 @@ Package extensions are used in order to reduce the number of dependencies:
 - To use `pairalign`, [`superimpose!`](@ref), [`rmsd`](@ref)/[`displacements`](@ref) with the `superimpose` option or [`Transformation`](@ref) on structural elements, call `using BioSequences, BioAlignments`.
 - To use `DataFrame`, call `using DataFrames`.
 - To use `MetaGraph`, call `using Graphs, MetaGraphs`.
-- To use [`MMTFDict`](@ref) or [`writemmtf`](@ref), call `import MMTF as MMTFPkg` (to avoid clashing with [`BioStructures.MMTF`](@ref)).
+- To use [`MMTFDict`](@ref) or [`writemmtf`](@ref), call `import MMTF`.
 - To use [`rundssp!`](@ref), [`rundssp`](@ref) or the `run_dssp` option for `read`/[`retrievepdb`](@ref), call `using DSSP_jll`.
 - To use [`runstride!`](@ref), [`runstride`](@ref) or the `run_stride` option for `read`/[`retrievepdb`](@ref), call `using STRIDE_jll`.
 

docs/src/documentation.md

@@ -21,11 +21,11 @@ downloadpdb("1EN2")
 To parse a PDB file into a Structure-Model-Chain-Residue-Atom framework:
 
 ```julia-repl
-julia> struc = read("/path/to/pdb/file.pdb", PDB)
+julia> struc = read("/path/to/pdb/file.pdb", PDBFormat)
 MolecularStructure 1EN2.pdb with 1 models, 1 chains (A), 85 residues, 754 atoms
 ```
 
-mmCIF files can be read into the same data structure with `read("/path/to/cif/file.cif", MMCIF)`.
+mmCIF files can be read into the same data structure with `read("/path/to/cif/file.cif", MMCIFFormat)`.
 The keyword argument `gzip`, default `false`, determines if the file is gzipped.
 If you want to read an mmCIF file into a dictionary to query yourself (e.g. to access metadata fields), use [`MMCIFDict`](@ref):
 
@@ -41,7 +41,7 @@ julia> mmcif_dict["_entity_src_nat.common_name"]
 A [`MMCIFDict`](@ref) can be accessed in similar ways to a standard dictionary, and if necessary the underlying dictionary of [`MMCIFDict`](@ref) `d` can be accessed with `d.dict`.
 Note that the values of the dictionary are always an `Array{String,1}`, even if only one value was read in or the data is numerical.
 
-MMTF files can be read into the same data structure with `read("/path/to/mmtf/file.mmtf", MMTF)` once you have imported MMTF.jl with `import MMTF as MMTFPkg`.
+MMTF files can be read into the same data structure with `read("/path/to/mmtf/file.mmtf", MMTFFormat)` once you have imported MMTF.jl.
 The keyword argument `gzip`, default `false`, determines if the file is gzipped.
 In a similar manner to mmCIF dictionaries, a MMTF file can be read into a dictionary with [`MMTFDict`](@ref).
 The values of the dictionary are a variety of types depending on the [MMTF specification](https://github.com/rcsb/mmtf/blob/master/spec.md).
@@ -545,10 +545,10 @@ The secondary structure code of a residue or atom can be accessed after assignin
 To assign secondary structure when reading the structure:
 ```julia
 # Assign secondary structure using DSSP
-read("/path/to/pdb/file.pdb", PDB, run_dssp=true)
+read("/path/to/pdb/file.pdb", PDBFormat, run_dssp=true)
 
 # Assign secondary structure using STRIDE
-read("/path/to/pdb/file.pdb", PDB, run_stride=true)
+read("/path/to/pdb/file.pdb", PDBFormat, run_stride=true)
 ```
 [`rundssp!`](@ref), [`runstride!`](@ref), [`rundssp`](@ref) and [`runstride`](@ref) can also be used to assign secondary structure to a [`MolecularStructure`](@ref) or [`Model`](@ref):
 ```julia
@@ -593,10 +593,10 @@ To download a PDB file in PDB, XML, mmCIF or MMTF format use the `format` argume
 
 ```julia
 # To get mmCIF
-downloadpdb("1ALW", dir="path/to/pdb/directory", format=MMCIF)
+downloadpdb("1ALW", dir="path/to/pdb/directory", format=MMCIFFormat)
 
 # To get XML
-downloadpdb("1ALW", dir="path/to/pdb/directory", format=PDBXML)
+downloadpdb("1ALW", dir="path/to/pdb/directory", format=PDBXMLFormat)
 ```
 
 To apply a function to a downloaded file and delete the file afterwards:
@@ -609,7 +609,7 @@ Or, using Julia's `do` syntax:
 
 ```julia
 downloadpdb("1ALW") do fp
-    s = read(fp, PDB)
+    s = read(fp, PDBFormat)
     # Do something
 end
 ```
@@ -622,11 +622,11 @@ In this case download the mmCIF file or MMTF file instead.
 To parse an existing PDB file into a Structure-Model-Chain-Residue-Atom framework:
 
 ```julia-repl
-julia> struc = read("/path/to/pdb/file.pdb", PDB)
+julia> struc = read("/path/to/pdb/file.pdb", PDBFormat)
 MolecularStructure 1EN2.pdb with 1 models, 1 chains (A), 85 residues, 754 atoms
 ```
 
-Read a mmCIF/MMTF file instead by replacing [`PDB`](@ref) with [`MMCIF`](@ref)/[`MMTF`](@ref).
+Read a mmCIF/MMTF file instead by replacing [`PDBFormat`](@ref) with [`MMCIFFormat`](@ref)/[`MMTFFormat`](@ref).
 Various options can be set through optional keyword arguments when parsing PDB/mmCIF/MMTF files:
 
 | Keyword Argument                 | Description                                                                            |
@@ -712,7 +712,7 @@ A [`MMCIFDict`](@ref) can also be written using [`writemmcif`](@ref):
 writemmcif("1EN2_out.dic", mmcif_dict)
 ```
 
-To write out a MMTF file, call `import MMTF as MMTFPkg` and use the [`writemmtf`](@ref) function with any element type or a [`MMTFDict`](@ref) as an argument.
+To write out a MMTF file, import MMTF.jl and use the [`writemmtf`](@ref) function with any element type or a [`MMTFDict`](@ref) as an argument.
 The `gzip` keyword argument, default `false`, determines whether to gzip the written file.
 
 Unlike for the collection functions, `expand_disordered` is set to `true` when writing files as it is usually desirable to retain all entities.
@@ -748,15 +748,15 @@ l = pdbentrylist()
 To download the entire RCSB PDB database in your preferred file format:
 
 ```julia
-downloadentirepdb(dir="path/to/pdb/directory", format=MMTF)
+downloadentirepdb(dir="path/to/pdb/directory", format=MMTFFormat)
 ```
 
 This operation takes a lot of disk space and time to complete, depending on internet connection.
 
 To update your local PDB directory based on the weekly status list of new, modified and obsolete PDB files from the RCSB server:
 
 ```julia
-updatelocalpdb(dir="path/to/pdb/directory", format=MMTF)
+updatelocalpdb(dir="path/to/pdb/directory", format=MMTFFormat)
 ```
 
 Obsolete PDB files are stored in the auto-generated `obsolete` directory inside the specified local PDB directory.
@@ -1440,7 +1440,7 @@ You can view BioStructures data types:
 
 ```julia
 struc = retrievepdb("1AKE")
-viewstruc(struc['A'], surface=Surface(Dict("colorscheme"=> "greenCarbon")))
+viewstruc(struc['A'], surface=Surface(Dict("colorscheme" => "greenCarbon")))
 ```
 
 ```@raw html

docs/src/examples.md

@@ -9,7 +9,7 @@ Here we give further examples, showing what you can do with the package.
 using BioStructures
 using Statistics
 
-struc = read("1AKE.pdb", PDB)
+struc = read("1AKE.pdb", PDBFormat)
 res_list = collectresidues(struc, standardselector)
 
 function sidechainheavyselector(a::AbstractAtom)
@@ -86,7 +86,7 @@ scatter(
 
 ```julia
 downloadpdb("1SSU")
-struc_nmr = read("1SSU.pdb", PDB)
+struc_nmr = read("1SSU.pdb", PDBFormat)
 rmsd(struc_nmr[5], struc_nmr[10], superimpose=false, rmsdatoms=heavyatomselector)
 displacements(struc_nmr[5], struc_nmr[10], superimpose=false, rmsdatoms=heavyatomselector)
 ```
@@ -96,8 +96,8 @@ displacements(struc_nmr[5], struc_nmr[10], superimpose=false, rmsdatoms=heavyato
 ```julia
 l = pdbentrylist()
 for p in l
-    downloadpdb(p, format=MMCIF) do fp
-        s = read(fp, MMCIF)
+    downloadpdb(p, format=MMCIFFormat) do fp
+        s = read(fp, MMCIFFormat)
         nres = countresidues(s, standardselector)
         if nres > 0
             frac = countresidues(s, standardselector, x -> resname(x) == "CYS") / nres

ext/BioStructuresMMTFExt.jl

@@ -2,58 +2,58 @@ module BioStructuresMMTFExt
 
 using BioStructures
 using BioSymbols
-import MMTF as MMTFPkg # Imported to avoid clash with MMTF name
+import MMTF # Imported to avoid clash with writemmtf
 
 # Create an empty MMTF dictionary
 # Matches the decoded form of a MMTF file using MMTF.jl
 # Encoding and decoding this Dict gives an identical Dict
 BioStructures.MMTFDict() = MMTFDict(Dict{String, Any}(
-    "altLocList"         => Char[],
-    "atomIdList"         => Int32[],
-    "bFactorList"        => Float32[],
-    "bioAssemblyList"    => Any[],
-    "bondAtomList"       => Int32[],
-    "bondOrderList"      => Int8[],
-    "chainIdList"        => String[],
-    "chainNameList"      => String[],
-    "chainsPerModel"     => Any[],
-    "depositionDate"     => "",
-    "entityList"         => Any[],
-    "experimentalMethods"=> Any[],
-    "groupIdList"        => Int32[],
-    "groupList"          => Any[],
-    "groupsPerChain"     => Any[],
-    "groupTypeList"      => Int32[],
-    "insCodeList"        => Char[],
-    "mmtfProducer"       => "",
-    "mmtfVersion"        => "",
-    "ncsOperatorList"    => Any[],
-    "numAtoms"           => 0,
-    "numBonds"           => 0,
-    "numChains"          => 0,
-    "numGroups"          => 0,
-    "numModels"          => 0,
-    "occupancyList"      => Float32[],
-    "releaseDate"        => "",
-    "resolution"         => 0.0,
-    "rFree"              => "",
-    "rWork"              => "",
-    "secStructList"      => Int8[],
-    "sequenceIndexList"  => Int32[],
-    "spaceGroup"         => "",
-    "structureId"        => "",
-    "title"              => "",
-    "unitCell"           => Any[],
-    "xCoordList"         => Float32[],
-    "yCoordList"         => Float32[],
-    "zCoordList"         => Float32[],
+    "altLocList"          => Char[],
+    "atomIdList"          => Int32[],
+    "bFactorList"         => Float32[],
+    "bioAssemblyList"     => Any[],
+    "bondAtomList"        => Int32[],
+    "bondOrderList"       => Int8[],
+    "chainIdList"         => String[],
+    "chainNameList"       => String[],
+    "chainsPerModel"      => Any[],
+    "depositionDate"      => "",
+    "entityList"          => Any[],
+    "experimentalMethods" => Any[],
+    "groupIdList"         => Int32[],
+    "groupList"           => Any[],
+    "groupsPerChain"      => Any[],
+    "groupTypeList"       => Int32[],
+    "insCodeList"         => Char[],
+    "mmtfProducer"        => "",
+    "mmtfVersion"         => "",
+    "ncsOperatorList"     => Any[],
+    "numAtoms"            => 0,
+    "numBonds"            => 0,
+    "numChains"           => 0,
+    "numGroups"           => 0,
+    "numModels"           => 0,
+    "occupancyList"       => Float32[],
+    "releaseDate"         => "",
+    "resolution"          => 0.0,
+    "rFree"               => "",
+    "rWork"               => "",
+    "secStructList"       => Int8[],
+    "sequenceIndexList"   => Int32[],
+    "spaceGroup"          => "",
+    "structureId"         => "",
+    "title"               => "",
+    "unitCell"            => Any[],
+    "xCoordList"          => Float32[],
+    "yCoordList"          => Float32[],
+    "zCoordList"          => Float32[],
 ))
 
 function BioStructures.MMTFDict(filepath::AbstractString; gzip::Bool=false)
-    return MMTFDict(MMTFPkg.parsemmtf(filepath; gzip=gzip))
+    return MMTFDict(MMTF.parsemmtf(filepath; gzip=gzip))
 end
 
-BioStructures.MMTFDict(io::IO; gzip::Bool=false) = MMTFDict(MMTFPkg.parsemmtf(io; gzip=gzip))
+BioStructures.MMTFDict(io::IO; gzip::Bool=false) = MMTFDict(MMTF.parsemmtf(io; gzip=gzip))
 
 Base.getindex(mmtf_dict::MMTFDict, field::AbstractString) = mmtf_dict.dict[field]
 
@@ -77,15 +77,15 @@ function Base.show(io::IO, mmtf_dict::MMTFDict)
 end
 
 function Base.read(input::IO,
-            ::Type{MMTF};
+            ::Type{MMTFFormat};
             structure_name::AbstractString="",
             remove_disorder::Bool=false,
             read_std_atoms::Bool=true,
             read_het_atoms::Bool=true,
             run_dssp::Bool=false,
             run_stride::Bool=false,
             gzip::Bool=false)
-    d = MMTFDict(MMTFPkg.parsemmtf(input; gzip=gzip))
+    d = MMTFDict(MMTF.parsemmtf(input; gzip=gzip))
     return MolecularStructure(
         d;
         structure_name=structure_name,
@@ -188,7 +188,7 @@ end
 function BioStructures.writemmtf(output::Union{AbstractString, IO},
                 d::MMTFDict;
                 gzip::Bool=false)
-    MMTFPkg.writemmtf(d.dict, output; gzip=gzip)
+    MMTF.writemmtf(d.dict, output; gzip=gzip)
     return
 end
 
@@ -248,10 +248,10 @@ function BioStructures.writemmtf(output::Union{AbstractString, IO},
                 # Checking for similar entities is non-trivial so we treat
                 #   each molecule as a separate entity
                 push!(d["entityList"], Dict{Any, Any}(
-                    "chainIndexList"=> Any[length(d["chainIdList"]) - 1],
-                    "description"   => "",
-                    "sequence"      => "", # This is changed later
-                    "type"          => ishetero(res) ? "non-polymer" : "polymer"
+                    "chainIndexList" => Any[length(d["chainIdList"]) - 1],
+                    "description"    => "",
+                    "sequence"       => "", # This is changed later
+                    "type"           => ishetero(res) ? "non-polymer" : "polymer",
                 ))
             end
             if !ishetero(res)
@@ -282,15 +282,15 @@ function BioStructures.writemmtf(output::Union{AbstractString, IO},
 
             if group_i == 0
                 push!(d["groupList"], Dict{Any, Any}(
-                    "groupName"       => resname(res),
-                    "bondAtomList"    => Any[],
-                    "elementList"     => Any[element(at) for at in ats_res],
+                    "groupName"        => resname(res),
+                    "bondAtomList"     => Any[],
+                    "elementList"      => Any[element(at) for at in ats_res],
                     # MMTF specifies missing charges as zero
-                    "formalChargeList"=> Any[charge(at) == "" ? 0 : parse(Int64, charge(at)) for at in ats_res],
-                    "singleLetterCode"=> "",
-                    "chemCompType"    => "",
-                    "atomNameList"    => Any[at_names...],
-                    "bondOrderList"   => Any[]
+                    "formalChargeList" => Any[charge(at) == "" ? 0 : parse(Int64, charge(at)) for at in ats_res],
+                    "singleLetterCode" => "",
+                    "chemCompType"     => "",
+                    "atomNameList"     => Any[at_names...],
+                    "bondOrderList"    => Any[],
                 ))
             end
 

src/BioStructures.jl

@@ -41,7 +41,7 @@ include("spatial.jl")
                     ATOM      8  CE  MET A   1      -3.296  14.391  24.798  1.00 54.68           C
                     END
                     """)
-            struc = read(path, PDB)
+            struc = read(path, PDBFormat)
             show(devnull, struc)
             collectatoms(struc, sel"serial < 5")
         end