Data query#

Rules to query nested task documents and dictionaries.

get_property_from_object(obj, query_string)[source]#

Get a property value from a generic nested object.

Parameters:

  • obj (Object) – An object to recursively parse property from, typically a emmet-core.TaskDoc generated as vasp task output by atomate2.

  • query_string (str) –

    A string that defines the rule to query the object. Three special characters are reserved: “.”, “-” and “^”:

    Dot “.” represents levels of reference: For example, “output.volume” means to retrieve the obj.output.volume. Dictionary querying is also supported, where “.” in the query string will represent the key to each level.

    If a level of reference is a list or tuple:

    1. Using f”{some index}-” as the prefix to this level will yield the corresponding key/attribute of the “some_ind“‘th member in the list.

    2. Using “^” as the prefix to this level will yield the corresponding key/attribute of all the members in the list and return them as a list in the original order.

    3. Using f”{some_ind}-” as the prefix to this level will yield the corresponding key/attribute of the first member in the list.

    4. Do not use “-” or “^” prefix when the corresponding level is not a list or tuple. If a corresponding level is a set, a random element will be yielded.

    For example, “calcs_reversed.0-output.outcar.magnetization.^tot” will give you the total magnetization on each site of the structure in the final ionic step, if the input object is a valid emmet-core TaskDoc.

    If a string with no special character is given, we will iteratively search through each level of attributes and dict keys until the key/attribute with the same name as the given string is found, or all key/attributes have been explored.

    If you decide to use special characters, please always make sure you have specified the exact full path to retrieve the desired item.

Returns:

The result of query.

Return type:

Any

query_keypath(obj, keypath)[source]#

Query attributes of an object along a path.

Parameters:

  • obj (Object or dict) – The object to be queried.

  • keypath (list of str) – A path of attribute names to query.

Returns:

The result of query.

Return type:

Any

query_name_iteratively(obj, name)[source]#

Query an attribute from a nested object.

Note

The first match encountered at the lowest search level will always be returned first.

Parameters:

  • obj (Object or dict) – The object to be queried.

  • name (str) – The attribute name.

Returns:

The result of query.

Return type:

Any