schrodinger.application.desmond.arkdb module¶

class schrodinger.application.desmond.arkdb.DSC¶

Bases: schrodinger.application.desmond.constants.Constants

Data selection codes. See select_data below for its usage.

ANY_VALUE = '<<any-value>>'¶

NO_VALUE = '<<absence>>'¶

class schrodinger.application.desmond.arkdb.ForEachDo(items)¶

Bases: tuple

An advanced tuple container that is able to apply any method call to itself to all its elements. For example:

a = ForEachDo([" a ", "b", " c"])
# Constructs a `ForEachDo` object with the three string elements.

assert isinstance(a, tuple)
# A `ForEachDo` instance is really a `tuple` instance.

assert ("a", "b", "c") == a.strip()
# `strip()` is applied to each element, and the results are aggregated
# into a tuple.

exception schrodinger.application.desmond.arkdb.CompositeKeySyntaxError¶: Bases: SyntaxError

exception schrodinger.application.desmond.arkdb.ArkDbGetError¶: Bases: KeyError

exception schrodinger.application.desmond.arkdb.ArkDbPutError¶: Bases: Exception

exception schrodinger.application.desmond.arkdb.ArkDbDelError¶: Bases: Exception

class schrodinger.application.desmond.arkdb.ArkDb(fname=None, string=None, db=None)¶

Bases: object

Abstracts the key-value database where analysis results are stored.

__init__(fname=None, string=None, db=None)¶

property val¶

get(key: str, default=<class 'schrodinger.application.desmond.arkdb.ArkDbGetError'>)¶

Gets a value keyed by key. Note that None is a normal return value and does NOT mean that the key was not found.

Raises

CompositeKeySyntaxError – if key has a syntax error. You normally should NOT catch this exception, because this means your code has a syntactical error.
ArkDbGetError – if key is not found in the database. You can optionally change raising the exception to returning a default value by specifying the “default” argument.

Explanation on the value of a key:

The value is generally a composite key like “a.b.c[1].d”, where “a”, “b”, “c”, “[1]”, and “d” are the subkeys or array-indices at each hierarchical level.
For array indices, sometimes the exact number is unknown a priori, e.g., “ResultLambda0.Keywords[<number>].ProtLigInter”, where the <number> cannot be specified in the source code. For cases like this, we have to iterate over the “ResultLambda0.Keywords” list and find “ProtLigInter” by matching the keyword. Note that it’s possible (at least in principle) that there may be multiple matching elements.
In order to express the above indexing ideas, we introduce four new syntax components here:
- [i] Iterates over elements in the list and returns the first
  matching element. For getting, putting, finding, and deleting.
- [*] Iterates over elements in the list and returns a tuple of all
  matching elements. Only for getting, finding, and deleting.
- [$] Insert at the end of the list. Only for putting.
- [@] Similar to [$] except that this is for insertion into an
  arbitrary position in the list. This is to be used with a number immediately followed, e.g., [@]123, and the number specifies the position in the list. Only for putting.
We may call these meta-indices.

Examples:
- “ResultLambda0.Keywords[i].ProtLigInter”: Gets the first “ProtLigInter” data.
- “ResultLambda0.Keywords[*].ProtLigInter”: Gets all “ProtLigInter” data, and returns a tuple.
- “ResultLambda0.Keywords[@]0.ProtLigInter”: Inserts a new “ProtLigInter” data at “ResultLambda0.Keywords[0]”. Note the difference from using “ResultLambda0.Keywords[0]”, which is to change the existing data.
- “ResultLambda0.Keywords[$].ProtLigInter”: Appends a new “ProtLigInter” data to “ResultLambda0.Keywords”.

put(key: str, value)¶

Puts a value associated with the given key into this database. value can be either of a scalar type, or of list, or an empty dict ({}), or of sea.Sea. key can be a composite key, see the docstring of ArkDb.get for detail.

Raises

CompositeKeySyntaxError – if key has a syntax error. You normally should NOT catch this exception, because this means your code has a syntactical error.
ArkDbPutError – if putting failed.

delete(key: str, matches: Optional[Union[str, Iterable[str]]] = None, ignore_badkey=False)¶

Deletes a given key and the value from the database. If the key is not found, ArkDbDelError will be raised unless ignore_badkey is True.

matches, if specified, provides one or more key-value pairs for checking on the value. If and only if all key-value pairs are found in the value, the key and the value will be deleted from the database. Each key-value pair is a string in the format of “<key>=<value>”. Note that the key and the value are connected by a single “=” symbol, no spaces allowed in the connection. Key is in the extended standard composite format (see the docstring of the ArkDb class above). Value is in the ARK format (note that spaces are allowed in the value). The value part is optional, when it’s missing, the “=” symbol should be absent as well, and this function will only look for the key in db and disregard the value.

Examples:

db.delete("a.b.c")
db.delete("a.b.d[i].e")
db.delete("a.b.d[i]", matches="e")
db.delete("a.b.d[i]", matches=("e=5", "h=10"))

find(key: str, picker: Union[int, Iterable[int], Callable] = None) → Union[Tuple, schrodinger.application.desmond.arkdb.ForEachDo]¶

Finds the given key and returns the corresponding data as a ForEachDo object. The ForEachDo object allows to iterate over the found data, each as a new ArkDb (or its subclass) object. It also allows us to concatenate operations on the found data.

Example:

db.find("stage[*].simulate").put("ensemble", "NVT")
# Resets all simulate stages' "ensemble" parameter's value to "NVT".

If the key is not found, this method will return () (i.e., empty tuple).

Parameters

picker –

This is to cherry-pick the found data. The follow types or values are supported:

None: All found data will be returned.
int: Among the found data, a single datum as indexed by picker will be returned. The index is zero-based.
List[int]: Among the found data, multiple data as indexed by picker elements will be returned. The indices are zero-based.
Callable: picker will be called on each found data, and the results will be filter-ed and returned.

Example:

db.find("stage[*].task", picker=1)             .put("set_family.simulate.temperature", 300)
# Mutates the second "task" stage.

db.find("stage[*].simulate.restrain", picker=lambda x: x.parent())             .put("temperature", 400)
# For any simulate stages with "restrain" setting, resets temperature
# to 400.

write(fname: str)¶

class schrodinger.application.desmond.arkdb.Datum(key: Optional[str], val=None)¶

Bases: object

An instance of this class represents a particular datum in the database. A datum could be a scalar value, or a list/dict object. Each datum is assigned a key for identification in the database. The key can be accessed via the key public attribute. The actual value of the datum is obtained by the val public attribute.

N.B.: A limitation on the val’s value: For putting, the value cannot be a dict object.

__init__(key: Optional[str], val=None)¶: Creates a Datum object with the given key and the default value val. key’s value can be None, and in this case the get_from method will always return the default value val.

property key¶

get_from(arkdb)¶

Gets the value of this datum from the database arkdb. The new value is used to update the public attribute val and is also returned.

Raises

ArkDbGetError – if the key is not found in the database.
CompositeKeySyntaxError – if the key has a syntax error.

put_to(arkdb)¶

Saves the value of this datum into the database arkdb.

Raises

ArkDbPutError – if saving the datum fails.
CompositeKeySyntaxError – if the key has a syntax error.

del_from(arkdb)¶

Deletes the key and the value of this datum from the database arkdb, Noop if the key is None.

Raises

ArkDbDelError – if the key is not found in the database.
CompositeKeySyntaxError – if the key has a syntax error.

schrodinger.application.desmond.arkdb.select_data(data: Iterable[schrodinger.application.desmond.arkdb.Datum], **match) → List[schrodinger.application.desmond.arkdb.Datum]¶

The following are from the real world:

Keywords = [
  {RMSD = {
     ASL = "((protein and not (m.n 3) and backbone) and not (a.e H) )"
     Frame = 0
     Panel = pl_interact_survey
     Result = [8.57678438812e-15 0.837188833342 ]
     SelectionType = Backbone
     Tab = pl_rmsd_tab
     Type = ASL
     Unit = Angstrom
   }
  }

  {RMSD = {
     ASL = "m.n 1"
     FitBy = "protein and not (m.n 3)"
     Frame = 0
     Panel = pl_interact_survey
     Result = [3.54861302804e-15 1.36992917763]
     SelectionType = Ligand
     Tab = pl_rmsd_tab
     Type = Ligand
     Unit = Angstrom
     UseSymmetry = true
   }
  }
]

There are two dict data keyed by “RMSD”. If, for example, we want to select the one with “SelectionType” being “Ligand”, we can use this function for that:

rmsds = arkdb.get("Keywords[*].RMSD")
select_data(rmsds, SelectionType="Ligand")

Parameters: **match – Key-value pairs for matching data. The data elements should be dict objects. All elements that have all key-value pairs specified by match are returned. Note that for floating numbers, if the relative or the absolute difference is less than 1E-7, the two numbers are considered the same.

See DSC above for special codes to be used in match’s values. This function returns an empty list if no matches found.

schrodinger.application.desmond.arkdb.expect_single_datum(data, exc, **match)¶: Similar to select_data, except that this function expects one and only one dict object that matches. If that’s not the case, an exception of the type type(exc) will be raised. The error message of exc is used to describe the key used to get data. On success, a single dict object is returned.