filter create

filter create filtername ?attribute value?..

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.

filter defined

filter defined filtername

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

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

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

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?

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

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?

Search the internal filter database by matching the keyword against a standard set of filter attributes, such as name, description, keywords, category, comment and UUIDs. 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 version UUIDs of the matched filters.

filter read

filter read filename

Read a filter definition file with one or more filter definitions. In case a filter is already defined, 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 of the first filter read.

filter set

filter set filtername ?attribute value?...

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:

• affiliation
  The institution the author of the filter definition works for.
• 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.
• 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 subfield 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 subfield 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.
• 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 subfield and subfieldindex 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 atotmag of the A_RESIDUE property, which is for example filled when reading PDB files.

• references
  Cross references of the filter. This is a nested list of class UUIDs and reference type tags.
• regid
  If the filter is registered, this is its registration ID. Unregistered filters have a zero registration ID.
• 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.
• version
  The version of the filter definition as free-form string.
• 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 subcommands

filter subcommands

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

filter write

filter write filtername ?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 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.

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