filter create

filter create filtername ?attribute value?...

filter create filtername dict

Filter(filtername,?attribute,value?...)

Filter(filtername,dict)

Filter.Create(filtername,?attribute,value?...)

Filter.Create(filtername,dict)

Create a new filter. In case the filter already exists, this is the same as filter set . A default filter without any other configured attributes does nothing and lets everything pass. The supported attributes and values are explained in the paragraph on the filter set command.

The return value is the filter name or reference.

filter defined

filter defined filtername

Filter.Defined(filtername/fref)

A boolean check whether the filter is available. In case it is not yet in memory, an attempt is made to auto-load or auto-instantiate it. For a command variant without auto-loading, see filter exists .

filter exists

filter exists filtername

f.exists()

Filter.Exists(filtername/fref)

A boolean test whether the filter is current defined and loaded. No attempt is made to auto-load it. For a command with auto-loading, see filter defined .

filter delete

filter delete ?filtername?..

f.delete()

Filter.Delete(?filtername/fref?,...)

Delete zero or more filters. Note that it is possible to delete built-in filters. An attempt to delete a non-exiting filter raises an error. The return value of this command is the number of deleted filters.

filter get

filter get filtername attribute

f.attribute

f[attribute]

f.get(attribute)

Filter.Get(filtername/fref,attribute)

Query an attribute from a filter definition. The supported attributes are detailed in the paragraph on the filter set subcommand.

If the specified filter is not yet loaded, an attempt to auto-load a definition file is made.

filter list

filter list ?pattern?

Filter.List(?pattern=?)

Get a list of all currently loaded filters, including the built-in filter definitions. If desired, a string match pattern can be supplied to filter the reported set.

filter load

filter load filtername

filter load all

Filter.Load(filtername)

Filter.Load(“all”)

Attempt to explicitly load a filter via the auto-loader mechanism. If the filter is already in memory, the command has no effect. In case auto-loading fails, an error results. The return value is the filter table slot index the filter is loaded into for Tcl , or a filter reference for Python .

The second form of the command scans the currently set filter search path and loads all accessible filters which are not yet in memory. Filters which are already active in the running application are not unloaded, and only a single instance of each I/O filter, even if present under various alias names in the filter directories, is loaded. This form of the command does not return a value.

filter query

filter query keyword ?objectclass? ?mode? ?casesensitivity?

Filter.Query(keyword=,?objclass=?,?mode=?,?casesensitivity=?)

Search the internal filter database by matching the keyword against a standard set of filter attributes, such as name, description, keywords, category, comment and UUID s. Only the current memory database is checked, no auto-loading or repository checks are performed.

By default all filter definitions are matched. The object class argument (such as atom ) can be used to limit the search to filters using a property of a specific property class. Providing an empty argument is the same as omitting the argument.

The optional mode argument changes the string comparison mode. The default is equal , other possibilities are substring , left (match beginning of string), right (match end of string), like (as the SQL operator), glob or regexp .

The final argument can be case (case-sensitive matching) or nocase (case-insensitive comparison, this is the default).

The return value is a list of the names or references of the matched filters.

filter read

filter read filename/dirname

filter read all

Filter.Read(filename=)

Filter.Read(“all”)

Read a filter definition file with one or more filter definitions, a directory containing such definition files, or the filter definition files contained in all accessible directories found in the filter auto-load path. In case a filter is already defined in the current interpreter, its definition is overwritten by what is found in the input file.

The return value is a list of two elements. The first element is the total number of filter definitions read from the file. The second element is the name ( Tcl ) or reference ( Python ) of the first filter read.

filter readblob

filter readblob datablob

Filter.Readblob(data=)

Read a filter definition from an in-memory XML blob. This blob can only contain a single filter definition. In the Python case, the data blob can be either a Unicode string, or a byte array.

The return value is the name ( Tcl ) or reference ( Python ) of the newly read filter definition.

filter ref

Filter.Ref(filtername)

Python -only method to get a reference of the filter, which allows terser attribute retrieval commands and other operations.

filter set

filter set filtername ?attribute value?...

filter set filtername dict

f.set(?attribute,value?,...)

f.set(dict)

f.attribute = value

f[attribute] = value

Filter.Set(filtername/fref,?attribute,value?,...)

Filter.Set(filtername/fref,dict)

Set one or more filter attributes. Some of the attributes listed below are read-only. They are included here because the filter get subcommand refers to this section. The following attributes are supported:

• address_city
  The city part of the author contact address.
• address_country
  The country part of the author contact address, following the ISO3166 standard.
• address_state
  The state part of the author contact address. Empty if not applicable.
• address_street
  The street address part of the author contact address. Includes floor, house number, etc.
• address_zip
  The ZIP code or other applicable postal code of the author contact address.
• affiliation
  The institution the author of the filter definition works for.
• affiliationduns
  The DUNS registration ID of the affiliated institution. This is primarily useful for US government projects.
• affiliationurl
  The URL of the affiliated institution.
• aliases
  A list of alias names for the filter.
• author
  The name of the author of the filter definition as free text.
• authorurl
  A URL with information on the author, or an empty string if unset.
• category
  A category string to be used if the filter is stored in a repository.
• classuuid
  The base class UUID of this filter.
• comment
  A free-form comment string.
• date
  The date of the last change in the filter definition.
• description
  A short single-line description of the filter, suitable for use in menus and similar circumstances.
• doi
  A digital object identifier for the filter, if defined.
• email
  An email contact address of the author of the filter.
• field
  The name of a field of the filter property. In case the complete property is used, which is the default, this is an empty string. This field may also be set directly by using field notation in the property attribute.
• fieldindex
  In case a only a field of the filter property is used for comparison, this is the numerical index, starting with 0, of the field in the property. This is a read-only attribute and automatically updated then setting the field attribute. If the complete property data is used, by the filter, the value of this attribute is -1.
• file
  The full path name of the file the filter definition was read from, or an empty string if the filter is built-in or defined in the script. This is a read-only attribute.
• flags
  Various flags to modify the operation of the filter. The flag set can be any combination of words from the set
• notavail_fail
  If set, the filter fails if the filter property cannot be computed, but no error is raised
• notavail_pass
  If set, filter always passes if the filter property cannot be computed, but no error is raised
• nocompute
  If set, do not attempt to compute the filter property on the filtered object, if it is not yet present, this condition is treated as a failed computation
• recompute
  If set, the filter property is recomputed once when the filter data is prepared for a filter operation. For example, the property of an atom filter is re-computed once before an ens atoms command, but not for the filter test of each individual atom.

The get variant of this command can additionally return several flag words describing the current internal state of the filter definition.

• infourl
  A URL with information on the filter, or an empty string if unset.
• keywords
  A list of keywords associated with the filter.
• license
  The license class associated with this filter Setting the license to a standard type updates the associated URL with a standard location.
• licenseurl
  A URL with details about the filter license.
• literature
  A free-form literature reference.
• mode
  The filter operation mode. This is an important, but complex attribute. The default value is simple , and this is what is needed in almost all standard applications. The possible values for this attribute are:
• simple
  Straightforward application of the filter. The property values of the filtered chemistry objects are directly compared to the filter values. In case the filter property has a width of more than one slot (see width attribute of property definitions), it is sufficient if any of the multiple values passes the filter.
• all
  Only usable for properties with a width of more than one. In this mode, all of the multiple property slot values of a chemistry object must pass the filter.
• diff
  Only usable for properties with a width of more than one. In this mode, among the multiple property slot values on a tested object there must be some which pass, and some which fail.
• allatoms
  Instead of using the filtered chemistry object, use all atoms the chemistry object contains. All atoms must pass the filter condition.
• someatoms
  Instead of using the filtered chemistry object, use all atoms the chemistry object contains. Some atoms must pass the filter condition.
• noatoms
  Instead of using the filtered chemistry object, use all atoms the chemistry object contains. No atoms must pass the filter condition.
• diffatoms
  Instead of using the filtered chemistry object, use all atoms the chemistry object contains. There must be atoms which pass the filter as well as atoms which fail.
• allneighbors
  Instead of using the filtered chemistry object, use all neighbor objects of the same type. All neighbors must pass the filter condition. Currently, neighborship is only defined for atom and bond objects.
• someneighbors
  Instead of using the filtered chemistry object, use all neighbor objects of the same type. All neighbors must pass the filter condition. Currently, neighborship is only defined for atom and bond objects.
• noneighbors
  Instead of using the filtered chemistry object, use all neighbor objects of the same type. All neighbors must pass the filter condition. Currently, neighborship is only defined for atom and bond objects.
• diffneighbors
  Instead of using the filtered chemistry object, use all neighbor objects of the same type. There must be neighbors that pass the filter condition as well as neighbors which fail. Currently, neighborship is only defined for atom and bond objects.
• name
  The primary name of the filter. Since alias names are also used to resolve a filter reference, this may be different from the argument supplied in the command.
• operator
  The operator used for comparing the filter value(s) to the property values of the compared chemical objects. It can be one of
• exact
  object and primary filter value must match
• smaller
  object value must be smaller than the primary filter value
• larger
  object value must be larger than the primary filter value
• range
  object value must be between the primary and secondary filter values
• not
  object and primary filter value must not match
• bitset
  object value must have all on bits in the primary filter value also set
• bitunset
  object value must not have any bit of the on bits in the filter value set
• alternative
  object value must be equal to the primary or secondary filter value
• neither
  object value must be different both from both filter values
• le
  object value must be larger or equal to the primary filter value
• ne
  object value must be smaller or equal to the primary filter value

The standard mathematical operator notation >, >=,== etc. may also be used to identify the operator.

• orcid
  The ORCID code of the author (see www.orcid.org).
• path
  The repository path for displaying hierarchical repository trees. This attribute is independent of any file system paths.
• phone
  A contact phone number of the author.
• property
  The name of the property associated with the filter. In the context of the filter create or filter set commands, the property name argument may include a field component. If a field is specified as part of the name, the propertyfield and propertyfieldindex attributes are also set as a side effect. Example:

filter create alphac property A_RESIDUE(atomtag) value “CA” operator =

This defines a filter alphac which selects all atoms which have the value CA in the field atomtag of the A_RESIDUE property, which is for example filled when reading PDB files. With a filter get command, the reported property name is still only A_RESIDUE . The field information can be obtained via the propertyfield attribute.

• propertyfield
  This is a read-only attribute. It reports the name of the field of the filter property, if such a field was specified. For filters which do not use fields, the result is an empty string.
• propertyfieldindex
  This is a read-only attribute. It returns the index of the field of the filter property, if such a field was specified. For filters which do not use fields, the result is minus one.
• references
  Cross references of the filter. This is a nested list of class UUID s and reference type tags.
• regid
  If the filter is registered, this is its registration ID. Unregistered filters have a zero registration ID.
• slot
  This is a read-only attribute. It reports the index of the filter definition in the filter table. This is useful for debugging only.
• value1
  The primary filter comparison value. This may also be simply written as value without the rank indicator. The value can be specified in any notation which can parsed as data value of the filter property. Changed filter values are parsed after the filter set or filter get command has processed all its arguments. The order of arguments does not matter, but at the end of the command, the property and data value must be compatible.
• value2
  The secondary filter comparison value. The same restrictions apply as for the primary filter comparison value.
• value3
  The auxiliary filter comparison value. The same restrictions apply as for the primary filter comparison value. This value is not used directly in conjunction with any of the scriptable comparison operators, but it does have a role in some internal functions.
• values
  Return a list of the filter comparison values (individually accessible as value1..3 attributes) which are actually used in this filter definition. This is a read-only attribute.
• version
  The version of the filter definition. This is a string in a 1.2.3 (or shortened) style.
• versionuuid
  The version UUID associated with this filter version.

If the filter argument is not yet loaded, an attempt to auto-load the definition file is made.

filter string

filter string filtername

f.string()

Filter.String(filter=)

Encode the filter as XML blob and return the blob as result. The blob format is the same as output by the filter write command.

filter subcommands

filter subcommands

dir(Filter)

Get a list of all supported subcommands of the filter command in this particular application.

filter write

filter write filtername ?filename?

f.write(?filename=?)

Filter.Write(filter=,?filename=?)

Write the current definition of the filter to a file in XML format. The file can be loaded into future script interpreters explicitly (see filter read command) or implicitly via the filter definition auto-load mechanism. If no file name is given, the name of the file is automatically constructed from the filter name in lower case and the suffix .fil. In addition to normal file names, the magic names stdout and stderr may be used, as well as already opened Tcl or Python socket and file handles, plus pipes indicated by a file name which starts with “|”. Writing to Tcl channels is not supported on the MS Windows platform.

The command returns the (possibly auto-generated) file name.

It is possible and sometimes useful to write out built-in filter definitions.