API Documentation
CIF files
A Cif
is a collection of CifContainer
s indexed by a String
label.
CrystalInfoFramework.Cif
— MethodCif(somepath; verbose=false, native=true, version=0)
Read in filename s
as a CIF file. If verbose
is true, print progress information during parsing. If native
is false
, use the C-language parser provided by cif_api_jll
. version
may be 1
, 2
or 0
(default) for auto-detected CIF version. version
is only respected by the native parser. The libcif
parser will always auto-detect.
Note that the cif_api parser is not currently working on Windows, so is disabled.
Currently the native parser is around 3 times faster than the cifapi parser when compilation time is not included, and uses 6-10 times as much memory. However, from a cold start (e.g. in a standalone script) the cifapi parser is around 30% faster.
CrystalInfoFramework.cif_from_string
— Methodcif_from_string(s::AbstractString; verbose=false, version=0, source="")
Process s
as the text of a CIF file using the native Julia parser. If verbose
is true, print progress information during parsing. version
may be 1
, 2
or 0
(default) for auto-detected CIF version. If source
is provided, it is a filesystem location to record as the source for s
.
Base.keys
— Methodkeys(c::Cif)
The names of all blocks in c
, not including any save frames.
Base.first
— Methodfirst(c::Cif)
The first block in c
, which may not be the first block that appears in the physical file. This is useful when only one block is present.
Base.length
— Methodlength(c::Cif)
The number of blocks in n
.
Base.haskey
— Methodhaskey(c::Cif,name)
Whether c
has a block named name
.
Base.getindex
— Methodgetindex(c::Cif,n)
c[n]
returns the block case-insensitively named n
in c
.
Base.setindex!
— Methodsetindex!(c::Cif,v,n)
c[n] = s
sets block n
to v
in c
.
Base.show
— Methodshow(io::IO,::MIME"text/plain",c::Cif)
Display a text representation of c
to io
. This text representation is not guaranteed to be syntactically correct CIF. To display c
as a CIF file, use ::MIME"text/cif"
.
Base.show
— Methodshow(io::IO,::MIME"text/cif",c::Cif; ordering = [])
Write the contents of c
as a CIF file to io
, ordering each of the CifContainers according to ordering
.
CIF blocks
Concrete types of CifContainer
s are Block
and CifBlock
. Only the latter may contain nested save frames. CifContainer
s act like Dict{String,Array{CifValue,1}}
dictionaries indexed by data name.
CrystalInfoFramework.Block
— TypeA CIF data block or save frame containing no nested save frames.
CrystalInfoFramework.CifBlock
— TypeA CIF block potentially containing save frames. Save frames cannot be nested.
Base.keys
— Methodkeys(b::CifContainer)
All data names in b
Base.haskey
— Methodhaskey(b::CifContainer,s::String)
Returns true
if b
contains a value for case-insensitive data name s
Base.iterate
— Methoditerate(b::CifContainer)
Iterate over all data names in b
.
Base.getindex
— Methodgetindex(b::CifContainer,s::String)
b[s]
returns all values for case-insensitive data name s
in b
as an Array{CifValue,1}
Base.get
— Methodget(b::CifContainer,s::String,a)
Return b[s]
. If s
is missing, return a
. s
is case-insensitive.
Base.getindex
— Methodgetindex(b::CifContainer,s::Dict)
Return the set of values in b
corresponding to the data name values provided in s
. The keys of s
must be datanames found in b
. A DataFrame is returned. The keys of s
are case-insensitive.
Base.setindex!
— Methodsetindex!(b::CifContainer,v,s)
Set the value of s
in b
to v
Base.delete!
— Methoddelete!(b::CifContainer,s)
Remove the value of s
from b
CIF values
Data names are associated with arrays of values of type CifValue
. Single-valued data names are associated with arrays with a single element.
CrystalInfoFramework.CifValue
— TypeThe syntactical type of data held in a CIF file. A value is of type String
, Vector{CifValue}
, Dict{String,CifValue}
, Missing
or Nothing
. In all cases the values returned for a given data name are in an Array{CifValue,1}
.
Loops
CIF blocks contain key-value pairs and loops. The following methods give access to these loops.
CrystalInfoFramework.get_loop
— Functionget_loop(b::CifContainer,s)
A DataFrame
built from data items in the same loop as s
. If no data are available, an empty DataFrame
is returned.
CrystalInfoFramework.add_to_loop!
— Functionadd_to_loop!(b::CifContainer, tgt, newname)
Add dataname newname
to the loop containing tgt
. Values for newname
must already be present (e.g. by calling b[newname]=values
) and have the same length as other values in the loop.
CrystalInfoFramework.create_loop!
— Functioncreate_loop!(b::CifContainer,names)
Create a loop in b
from the datanames in names
. Datanames previously assigned to other loops are transferred to the new loop. All data attached to names
should have the same length.
Save frames
CIF data files do not contain save frames, however CIF dictionaries use them extensively. The contents of save frames are invisible to all methods except show
. They can be accessed using get_frames
, which returns a Cif
object.
CrystalInfoFramework.get_frames
— Methodget_frames(f::CifBlock{V})
Return all nested CIF containers in f
as a Cif
object.
CIF dictionaries
DDLm Dictionaries
Dictionaries published by the International Union of Crystallography use the DDLm attribute set.
CrystalInfoFramework.DDLm_Dictionary
— TypeA DDLm Dictionary holds information about data names including executable methods for deriving missing values.
CrystalInfoFramework.DDLm_Dictionary
— MethodDDLm_Dictionary(c::Cif;ignore_imports=false)
Create a DDLm_Dictionary
from c
. ignore_imports = true
will ignore any import
attributes.
CrystalInfoFramework.DDLm_Dictionary
— MethodDDLm_Dictionary(a; verbose=false, ignore_imports="None",
+cache_imports=false)
Create a DDLm_Dictionary
given filename a
. verbose = true
will print extra debugging information during reading.ignore_imports = :None
will ignore any import
attributes. Other options are :Full
and :Contents
to ignore imports with the respective mode
, and :all
to ignore all imports. cache_imports
will store the contents of imported files (Contents
mode only) but will not merge the contents into the importing definition.
Setting ignore_imports
to :None (the default) merges all information in imported files into the dictionary, replacing the import
attribute.
By default imports are cached, even if they are not merged. cache_imports
can be set to false
to completely ignore any import attributes.
cache_imports
is ignored if ignore_imports
is :None.
If a non-absolute location for imported dictionaries is specified, they are searched for relative to the same directory as the importing dictionary, unless import_dir
is specified, in which case the search is relative to that directory.
Base.keys
— Methodkeys(d::DDLm_Dictionary)
Return a list of datanames defined by the dictionary, including any aliases.
Base.getindex
— Methodgetindex(d::DDLm_Dictionary,k)
d[k] returns the definition for data name k
as a Dict{Symbol,DataFrame}
where Symbol
is the attribute category (e.g. :name
).
Base.delete!
— Methoddelete!(d::DDLm_Dictionary,k::String)
Remove all information from d
associated with dataname k
CrystalInfoFramework.get_dic_namespace
— Methodget_dic_namespace(d::DDLm_Dictionary)
Return the namespace declared by the dictionary, or ddlm
if none present.
CrystalInfoFramework.list_aliases
— Methodlist_aliases(d::DDLm_Dictionary,name;include_self=false)
List aliases of name
listed in d
. If not include_self
, remove name
from the returned list.
CrystalInfoFramework.find_name
— Methodfind_name(d::DDLm_Dictionary,name)
Find the canonical name for name
in d
. If name
is not present, return name
unchanged. If accessed in cat/obj format, search also child categories. Note that the head category may not have a category associated with it. If name
is the dictionary title it is returned as is.
CrystalInfoFramework.find_category
— Methodfind_category(d::DDLm_Dictionary,dataname)
Find the category of dataname
by looking up d
.
CrystalInfoFramework.find_object
— Methodfind_object(d::DDLm_Dictionary,dataname)
Find the object_id
of dataname
by looking up d
.
CrystalInfoFramework.is_category
— Methodis_category(d::DDLm_Dictionary,name)
Return true if name
is a category according to d
.
CrystalInfoFramework.get_categories
— Methodget_categories(d::DDLm_Dictionary, referred=false)
List all categories defined in DDLm Dictionary d
. If referred
is true
, categories for which data names are defined, but no category is defined, are also included.
CrystalInfoFramework.get_keys_for_cat
— Methodget_keys_for_cat(d::DDLm_Dictionary,cat;aliases=false)
List all category key data names for cat
listed in d
. If aliases
, include alternative names for the key data names.
CrystalInfoFramework.get_default
— Methodget_default(d::DDLm_Dictionary,s)
Return the default value for s
or missing
if none defined.
CrystalInfoFramework.lookup_default
— Methodlookup_default(dict::DDLm_Dictionary,dataname::String,cp)
Index into any default lookup table defined in dict
for dataname
using an index value from cp
. cp
is any object with a property name as specified by def_index_id
in the definition of dataname
such that cp.<def_index_id>
returns a single value
Base.show
— Methodshow(io::IOContext,MIME("text/cif"),ddlm_dic::DDLm_Dictionary;header="")
Output ddlm_dic
in CIF format. header
contains text that will be output in a comment box at the top of the file, which will replace any header comment stored in ddlm_dic
.
DDL2 Dictionaries
DDL2 dictionaries are published and maintained by the worldwide Protein Data Bank (wwPDB).
CrystalInfoFramework.DDL2_Dictionary
— TypeDDL2_Dictionary
The type of DDL2 dictionaries.
CrystalInfoFramework.DDL2_Dictionary
— MethodDDL2_Dictionary(c::Cif)
Create a DDL2_Dictionary from c
.
CrystalInfoFramework.DDL2_Dictionary
— MethodDDL2_Dictionary(a; verbose=false)
Create a DDL2_Dictionary
given filename a
. verbose = true
will print extra debugging information during reading.
Base.keys
— Methodkeys(d::DDL2_Dictionary)
Return a list of datanames defined by the dictionary, including any aliases.
Base.getindex
— Methodgetindex(d::DDL2_Dictionary,k)
d[k] returns the definition for data name k
as a Dict{Symbol,DataFrame}
where Symbol
is the attribute category (e.g. :item_name
).
CrystalInfoFramework.get_categories
— Methodget_categories(d::DDL2_Dictionary; referred = false)
List all categories defined in d
. If referred
is true
, categories for which data names are defined, but no category is defined, are also included.
CrystalInfoFramework.get_default
— Methodget_default(d::DDL2_Dictionary,dataname)
Return the default value for dataname
or missing
if none defined.
Base.show
— Methodshow(io::IOContext,::MIME"text/cif",ddl2_dic::DDL2_Dictionary)
Output ddl2_dic
in CIF format. IOContext
can be used to control the output layout using the following keywords:
strict: follow the IUCr layout rules