API Documentation

Cif(s::AbstractPath;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.

Cif(s::AbstractString;verbose=false,version=0,source=p"")

Process contents of s as 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.

keys(c::Cif)

The names of all blocks in c, not including any save frames.

first(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.

length(c::Cif)

The number of blocks in n.

haskey(c::Cif,name)

Whether c has a block named name.

getindex(c::Cif,n)

c[n] returns the block case-insensitively named n in c.

setindex!(c::Cif,v,n)

c[n] = s sets block n to v in c.

show(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".

A CIF data block or save frame containing no nested save frames.

A CIF block potentially containing save frames. Save frames cannot be nested.

keys(b::CifContainer)

All data names in b

haskey(b::CifContainer,s::String)

Returns true if b contains a value for case-insensitive data name s

iterate(b::CifContainer)

Iterate over all data names in b.

getindex(b::CifContainer,s::String)

b[s] returns all values for case-insensitive data name s in b as an Array{CifValue,1}

get(b::CifContainer,s::String,a)

Return b[s]. If s is missing, return a. s is case-insensitive.

getindex(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.

setindex!(b::CifContainer,v,s)

Set the value of s in b to v

delete!(b::CifContainer,s)

Remove the value of s from b

The 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}.

get_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.

add_to_loop!(b::CifContainer, tgt, newname)

Add dataname tgt to the loop containing newname. Values for tgt must already be present (e.g. by calling b[tgt]=values) and have the same length as other values in the loop.

create_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.

get_frames(f::CifBlock{V})

Return all nested CIF containers in f as a Cif object.

A DDLm Dictionary holds information about data names including executable methods for deriving missing values.

DDLm_Dictionary(c::Cif;ignore_imports=false)

Create a DDLm_Dictionary from c. ignore_imports = true will ignore any import attributes.

DDLm_Dictionary(a::AbstractPath;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.

keys(d::DDLm_Dictionary)

Return a list of datanames defined by the dictionary, including any aliases.

getindex(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).

delete!(d::DDLm_Dictionary,k::String)

Remove all information from d associated with dataname k

get_dic_namespace(d::DDLm_Dictionary)

Return the namespace declared by the dictionary, or ddlm if none present.

list_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.

find_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.

find_category(d::DDLm_Dictionary,dataname)

Find the category of dataname by looking up d.

find_object(d::DDLm_Dictionary,dataname)

Find the object_id of dataname by looking up d.

is_category(d::DDLm_Dictionary,name)

Return true if name is a category according to d.

get_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.

get_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.

get_default(d::DDLm_Dictionary,s)

Return the default value for s or missing if none defined.

lookup_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

show(io::IO, mime, x)

The display functions ultimately call show in order to write an object x as a given mime type to a given I/O stream io (usually a memory buffer), if possible. In order to provide a rich multimedia representation of a user-defined type T, it is only necessary to define a new show method for T, via: show(io, ::MIME"mime", x::T) = ..., where mime is a MIME-type string and the function body calls write (or similar) to write that representation of x to io. (Note that the MIME"" notation only supports literal strings; to construct MIME types in a more flexible manner use MIME{Symbol("")}.)

For example, if you define a MyImage type and know how to write it to a PNG file, you could define a function show(io, ::MIME"image/png", x::MyImage) = ... to allow your images to be displayed on any PNG-capable AbstractDisplay (such as IJulia). As usual, be sure to import Base.show in order to add new methods to the built-in Julia function show.

Technically, the MIME"mime" macro defines a singleton type for the given mime string, which allows us to exploit Julia's dispatch mechanisms in determining how to display objects of any given type.

The default MIME type is MIME"text/plain". There is a fallback definition for text/plain output that calls show with 2 arguments, so it is not always necessary to add a method for that case. If a type benefits from custom human-readable output though, show(::IO, ::MIME"text/plain", ::T) should be defined. For example, the Day type uses 1 day as the output for the text/plain MIME type, and Day(1) as the output of 2-argument show.

Examples

julia> struct Day
           n::Int
       end

julia> Base.show(io::IO, ::MIME"text/plain", d::Day) = print(io, d.n, " day")

julia> Day(1)
1 day

Container types generally implement 3-argument show by calling show(io, MIME"text/plain"(), x) for elements x, with :compact => true set in an IOContext passed as the first argument.

show(io::IO,::MIME"text/cif",ddl2_dic::AbstractCifDictionary)

Output ddl2_dic to IO in CIF format

DDL2_Dictionary

The type of DDL2 dictionaries.

DDL2_Dictionary(c::Cif)

Create a DDL2_Dictionary from c.

DDL2_Dictionary(a::AbstractPath;verbose=false)

Create a DDL2_Dictionary given filename a. verbose = true will print extra debugging information during reading.

keys(d::DDL2_Dictionary)

Return a list of datanames defined by the dictionary, including any aliases.

getindex(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).

get_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.

get_default(d::DDL2_Dictionary,dataname)

Return the default value for dataname or missing if none defined.

show(io::IO, mime, x)

The display functions ultimately call show in order to write an object x as a given mime type to a given I/O stream io (usually a memory buffer), if possible. In order to provide a rich multimedia representation of a user-defined type T, it is only necessary to define a new show method for T, via: show(io, ::MIME"mime", x::T) = ..., where mime is a MIME-type string and the function body calls write (or similar) to write that representation of x to io. (Note that the MIME"" notation only supports literal strings; to construct MIME types in a more flexible manner use MIME{Symbol("")}.)

For example, if you define a MyImage type and know how to write it to a PNG file, you could define a function show(io, ::MIME"image/png", x::MyImage) = ... to allow your images to be displayed on any PNG-capable AbstractDisplay (such as IJulia). As usual, be sure to import Base.show in order to add new methods to the built-in Julia function show.

Technically, the MIME"mime" macro defines a singleton type for the given mime string, which allows us to exploit Julia's dispatch mechanisms in determining how to display objects of any given type.

The default MIME type is MIME"text/plain". There is a fallback definition for text/plain output that calls show with 2 arguments, so it is not always necessary to add a method for that case. If a type benefits from custom human-readable output though, show(::IO, ::MIME"text/plain", ::T) should be defined. For example, the Day type uses 1 day as the output for the text/plain MIME type, and Day(1) as the output of 2-argument show.

Examples

julia> struct Day
           n::Int
       end

julia> Base.show(io::IO, ::MIME"text/plain", d::Day) = print(io, d.n, " day")

julia> Day(1)
1 day

Container types generally implement 3-argument show by calling show(io, MIME"text/plain"(), x) for elements x, with :compact => true set in an IOContext passed as the first argument.

show(io::IO,::MIME"text/cif",ddl2_dic::AbstractCifDictionary)

Output ddl2_dic to IO in CIF format

A DataSource, when provided with a string referring to a data name from a namespace known to the data source, returns an array of values that are either Native (already Julia types) or Text (requiring interpretation to create Julia types).

TypedDataSource(data,dictionary)

A TypedDataSource is a DataSource that returns items with the correct type and aliases resolved, as specified in the associated CIF dictionary.