ACORN Object Descriptor Interface

In order for the database to be useful after several years, we need to keep some extra information about variables that get passed around. We obviously can’t keep copies of every variable (especially true for large matrices); however, we can keep certain statistics, such as shape, type and other standard statistical measures. The machinery for describing objects is quite generic and includes support for attributes, instance methods and calls to other functions that can return information for a given object.

Descriptor methods are contained within JSON files (named package.json, where ‘package’ is the name of the package where the object is defined). These JSON files describe dictionaries where the FQDN of an object is the key, and the value is a dictionary with attributes and values that describe how to describe the object. An object’s descriptor dictionary can have the following kinds of fields:

  • attribute: can be any attribute of the object; it can also be a FQDN for an attribute, specified with a ‘.’-separated list. E.g., columns.values.
  • instance: is a special keyword that specifies an instance method to be called on the object. It’s format is described below.

Attribute Descriptor Fields

Attributes are added to the descriptor (dictionary) for an object by specifying the name of the attribute as a key and another dictionary as the value. If the value dictionary is empty, then the attribute’s value will be attached to the description under the same name as the original attribute. However, it can also be transformed using these options:

  • rename: expose the value under a new name when describing the object.

  • slice: if the object is a list or array, you can select columns of the array using slice syntax. name:slice specifies that the result of taking the slice should be set on the descriptor under name. slice can be a ‘,’-separated list of indices to take. For example: 0,1,2 translates to obj[0][1][2]. .. code-block:: json

    {“values”: {“slice”: [“mean:1”, “std:2”]}}

    will take the second column of values attribute and label it as mean on the new object. It will take the third column of values and place it under the attribute std. If a name is not specified (i.e., no : is present in the slice), then it is just labelled by its index in the slice list.

  • transform: apply a function to the value of the attribute. Functions can have numpy, math, scipy in their names. For example, to use the square-root of the length of an object, we would use: .. code-block:: json

    {“length”: {“transform”: [“numpy.sqrt”]}}

    which would take attribute length and apply numpy.sqrt to it. If multiple transforms are specified in the list, they will be chained, so that the result of the previous item in the list is past to the next transformation.

Note

only one of slice or rename can be specified

Instance Method Descriptor Fields

The instance method descriptors work identically to the standard attribute descriptors except that instead of operating on a specific attribute of the object instance, they operate directly on the instance itself. The options above for rename and slice work exactly the same way. However, the transform option behaves differently.

If the transform has self. in its name, then self is replaced by the object instance. These methods can also be chained and mixed with the numpy, math and scipy calls.

{"instance": {"transform": ["self.head", "self.describe", "self.get_values",
"numpy.sqrt"]}}

would be equivalent to numpy.sqrt(obj.head().describe().get_values()).

API Documentation for the Descriptor Machinery

Methods for describing the objects within packages that are not instantiated by the user in the scope of __main__.

acorn.logging.descriptors.describe(o)[source]

Describes the object using developer-specified attributes specific to each main object type.

Returns:keys are specific attributes tailored to the specific object type, though fqdn is common to all descriptions; values are the corresponding attribute values which are simple types that can easily be serialized to JSON.
Return type:dict
acorn.logging.descriptors.json_describe(o, fqdn, descriptor=None)[source]

Describes the specified object using the directives in the JSON descriptor, if available.

Parameters:
  • o – object to describe.
  • fqdn (str) – fully-qualified domain name of the object.
  • descriptor (dict) – keys are attributes of o; values are transform functions to apply to the attribute so that only a single value is returned.
Returns:

keys are specific attributes tailored to the specific object type, though fqdn is common to all descriptions; values are the corresponding attribute values which are simple types that can easily be serialized to JSON.
Return type:

dict