Python Client¶

The SAL Python client provides all the SAL operations and a set of Python classes that wrap the SAL data-classes.

To ease user interaction with the data system, the client uses Python objects to represent the objects in the data-tree. client side validation of data.

SALClient Class¶

class sal.client.SALClient(host, verify_https_cert=True)¶

The Simple Access Layer (SAL) python client.

To connect to a SAL server, the server URL must be supplied via the host attribute. The host string must be a valid url, including the scheme:

https://sal.server.local

A port number may be included:

https://sal.server.local:5000

The client will attempt a connection to the specified server to confirm the url points to a valid server. If a SAL server is not found, or an incompatible version of the server is identified (for example if the server is using a newer version of the API), a ConnectionError exception will be raised.

If the server requires authentication this may be discovered by inspecting the value of the auth_required attribute. If the server requires authentication this will be set to True.

By default, authentication credentials will be request as needed by the client. Using an access method that requires authentication will result in the client requesting a username and password. The authentication token will be stored and used across sessions until it expires.

If more explicit control over authentication is required, the user can explicitly call the authenticate method. Password prompting can be disabled by setting the attribute prompt_for_password to False.

If authentication is successful, an authentication token will be returned by the server. The token grants access to the server for a limited time window, determined by the server administrator. Once the token expires the user will need to re-authenticate. The attribute auth_token will contain the token for the current session. The token is tied to the IP address of the machine it was requested with.

While not recommended, a credentials file may be created containing the username and password to pass to a server. The password in the file is clear-text and therefore must be protected by the user. The format of the credentials file is as follows:

[HOSTNAME] user=USERNAME password=PASSWORD

For example:

[https://sal.server1.com] user=admin password=secret

[https://sal.server2.com] user=datauser password=secret2

By default the client will look for a file called $HOME/.sal/credentials. If this file is found to contain valid data for a server, the password prompt will not be shown. Alternate credential file paths can be passed via arguments to the authenticate method.

For developers, when instancing the client it is possible to disable SSL certificate checks by setting the verify_https_cert argument to False .

Parameters:	host – The SAL server URL. verify_https_cert – Perform SSL certificate validation (default=True).
Raises:	ConnectionError – If the client fails to connect to a SAL server.

authenticate(user=None, password=None, credentials=None)¶

Authenticates the client with the server.

Authentication may be performed by passing a username/password to the method or via a credentials file.

If the method is called without the necessary arguments, and password prompting is enabled, it will prompt the user for a username and/or password.

If prompting is disabled and no arguments are supplied, the client will attempt to identify credentials from the default credentials file: $HOME/.sal/credentials.

Parameters:	user – Username string. password – Password string. credentials – Credentials file path.
Raises:	AuthenticationFailed – If authentication with the server fails.

copy(target, source)¶

Copy the node specified by the source path to the target path location.

Copy will not create any missing intermediate nodes to the target path, these must be created manually before the copy operation is performed. These cannot be created automatically as the branch metadata, such as the description, cannot be automatically populated.

Parameters:	target – A target node path. source – A source node path.
Raises:	InvalidPath – If the supplied path is invalid. NodeNotFound – If the path does not point ot a node. PermissionDenied – If the group does not have permission to access the node.

delete(path)¶

Delete the node specified by the path.

If a branch node is deleted, all its descendants are also deleted.

Parameters:	path – A valid node path.
Raises:	InvalidPath – If the supplied path is invalid. NodeNotFound – If the path does not point ot a node. PermissionDenied – If the group does not have permission to access the node.

get(path, summary=False)¶

Returns node data for the specific path.

The object returned depends on the type of node pointed to by the path. If the path identifies a branch node, a Branch object is returned. Leaf nodes return the data object stored on that node.

For leaf nodes, users can request the full data object or a reduced summary object (containing only the object meta data). If the summary argument is set to false (the default) the full data object is returned, if true a data summary is returned. The summary argument has no effect for branch nodes.

Parameters:	path – A valid node path. summary – Return a summary object (default: False).
Returns:	A `Branch`, `DataObject` or `DataSummary` object.
Raises:	InvalidPath – If the supplied path is invalid. NodeNotFound – If the path does not point ot a node. PermissionDenied – If the group does not have permission to access the node.

list(path)¶

Returns node meta data for the specific path.

The object returned depends on the type of node pointed to by the path. If the path identifies a branch node, a BranchReport object is returned. For leaf nodes, a LeafReport object is returned.

Parameters:	path – A valid node path.
Returns:	A `BranchReport` or `LeafReport` object.
Raises:	InvalidPath – If the supplied path is invalid. NodeNotFound – If the path does not point ot a node. PermissionDenied – If the group does not have permission to access the node.

put(path, content)¶

Creates/updates node data at the specific path.

Put may be used to create or update branch and leaf nodes. Overwriting an existing node with new content will update the existing node. In the case of a branch node this will update the branch metadata without affecting the descendant nodes. Writing a new data object to a leaf node will replace the existing data object.

To create a branch node, a Branch object must be supplied as the put content.

To create a leaf node, a suitable DataObject subclass must be provided. A leaf node will be created to encapsulate the DataObject.

Put will not create any missing intermediate nodes to the target path, these must be created manually before the put operation is performed. These cannot be created automatically as the branch metadata, such as the description, can not be automatically populated.

Parameters:	path – A valid node path. content – A `Branch` or `DataObject` instance.
Raises:	InvalidPath – If the supplied path is invalid. NodeNotFound – If the path does not point ot a node. PermissionDenied – If the group does not have permission to access the node.

host¶

The SAL server host URL.

This attribute can be used to obtain the current host URL or set a new host url.

version = '1.2.2'¶: The client version string.

Report Classes¶

These classes are returned by list() operations and provide information on the data-tree nodes. To simplify working interactively, the __repr__() method has been overridden in these classes to print a summary of the report to the console.

class sal.core.object.BranchReport(description, branches, leaves, timestamp, revision_current=1, revision_latest=1, revision_modified=None)¶

Describes the contents of a branch node.

Parameters:

description – The branch description.
branches – A list of branch nodes names.
leaves – A list of leaf (name, ObjectReport) tuples.
timestamp – The time the node was modified in ISO 8601 format or a datetime object.
revision_current – Revision number of returned data.
revision_latest – Head revision number.
revision_modified – List of revision numbers in which the node was modified.

to_dict()¶

Serialises the object into a dictionary.

Returns:	Serialised object.

class sal.core.object.LeafReport(description, cls, group, version, timestamp, revision_current=1, revision_latest=1, revision_modified=None)¶

Describes the contents of a leaf node.

Parameters:

description – The branch description.
cls – Data object class.
group – Data object group.
version – Data object version.
timestamp – The time the node was modified in ISO 8601 format or a datetime object.
revision_current – Revision number of returned data.
revision_latest – Head revision number.
revision_modified – List of revision numbers in which the node was modified.

to_dict()¶

Serialises the object into a dictionary.

Returns:	Serialised object.

class sal.core.object.ObjectReport(cls, group, version)¶

Describes the type of a data object.

Parameters:	cls – Object class. group – Object group. version – Object version.

Branch Class¶

The branch class represents a branch object, it is returned by a get() operation on a branch node. The same object is passed to put() to create a branch node in the data-tree.

class sal.core.object.Branch(description)¶

An object representing a data tree branch node.

A node description string must be provided.

Parameters:	description – A description string.

classmethod from_dict(d)¶

Instances the class from a dictionary representation.

Parameters:	d – Dictionary containing a serialised object.
Returns:	An object instance.

to_dict()¶

Serialises the object into a dictionary.

Returns:	Serialised object.

description¶: A string describing the branch contents.

Data Classes¶

The Python client contains a set of Python objects that represent the SAL data classes. These objects provide richer access to the data stored in a SAL data-object, typically providing calculated attributes and automatic validation of data.

Base Classes¶

All the Python data-classes are derived from a common set of base classes.

Full Object:

class sal.core.object.DataObject(description)¶

Abstract base class representing a SAL data object.

A DataObject represents a discrete chunk of data stored by the SAL system, such as a signal, image, or audio recording. A SAL leaf node contains a single DataObject.

A new SAL data class is defined by extending DataObject and defining an associated DataSummary class. The data object is then registered with SAL using the register decorator found in this module:

@register
class MyNewType(DataObject):
    etc...

Concrete classes derived from DataObject must populate four class attributes:

CLASS: A string that uniquely identifies the class to the SAL server and client.
GROUP: A string that specifies the data class groups the class belongs to.
VERSION: An integer specifying the version of the data class.
SUMMARY_CLASS: The summary class associated with the data class.  

The string attributes CLASS and GROUP must be lower-case and contain only alphanumeric characters, ‘_’, ‘-‘ and no whitespace. e.g. CLASS = ‘signal’, GROUP = ‘signal_dimension’

VERSION must be an integer greater than zero. The version of a data class should be incremented if the storage representation of the class changes. This ensures it is simple for developers to identify different representations of a data class stored in the data system.

The SUMMARY_CLASS attribute must be a reference to the DataSummary class returned by the DataObject when summary() is called. e.g. SUMMARY_CLASS = MyNewTypeSummary

The from_dict() and to_dict() methods must be implemented. To simplify development of to_dict() a helper method _new_dict() is provided. The _new_dict() method will return a dictionary pre-populated with the data class metadata keys.

CLASS = None¶

GROUP = None¶

VERSION = -1¶

classmethod from_dict(d)¶

Instances the class from a dictionary representation.

Parameters:	d – Dictionary containing a serialised object.
Returns:	An object instance.

classmethod is_compatible(d)¶

Checks the dictionary contains the correct header information for the data class.

Returns True if the correct class, group, version and type attributes are defined, False is returned otherwise.

Parameters:	d – Dictionary containing serialised class data.
Returns:	True if compatible, False otherwise.

summary()¶

Returns a summary of the data object.

Returns:	A DataSummary object.

to_dict()¶

Returns a dictionary representation of the data object.

Returns:	A data object dictionary.

SUMMARY_CLASS = None¶: The summary class associated with this data class.

Summary Object:

class sal.core.object.DataSummary(description)¶

Abstract base class representing a SAL data summary.

A DataSummary object is a reduced representation, or summary, of the data stored in a DataObject. A summary object will typically contain the DataObject metadata, but not the data arrays.

The values of the CLASS, GROUP and VERSION attributes of the summary class must match the values in the associated DataObject.

CLASS = None¶

GROUP = None¶

VERSION = -1¶

classmethod from_dict(d)¶

Instances the class from a dictionary representation.

Parameters:	d – Dictionary containing a serialised object.
Returns:	An object instance.

classmethod is_compatible(d)¶

Checks the dictionary contains the correct header information for the data class.

Returns True if the correct class, group, version and type attributes are defined, False is returned otherwise.

Parameters:	d – Dictionary containing serialised class data.
Returns:	True if compatible, False otherwise.

to_dict()¶

Returns a dictionary representation of the data object.

Returns:	A data object dictionary.

Scalar Class¶

Full Object:

class sal.dataclass.Scalar(value, description=None)¶

A SAL data class that contains a single value.

Holds a single scalar value and an associated description.

Value may be one of the following types:

Python types:

bool, int, float, str

Numpy:

int8, int16, int32, int64, uint8, uint16, uint32, uint64, float32, float64, bool

Python types are automatically promoted to the equivalent numpy types.

Parameters:	value – The scalar value. description – A string describing the scalar (default=’A scalar value.’).

SUMMARY_CLASS¶: alias of ScalarSummary

classmethod from_dict(d)¶

Instances the object from a dictionary representation.

Parameters:	d – Dictionary containing a serialised object.
Returns:	An object instance.

summary()¶

Returns a summary of the Scalar object.

Returns:	A ScalarSummary object.

to_dict()¶

Returns a dictionary representation of the object.

Returns:	A data object dictionary.

value¶: The scalar value.

Summary Object:

class sal.dataclass.ScalarSummary(description=None)¶

The summary object for Scalar.

See the Scalar class for more information.

Parameters:	description – A string describing the scalar (default=’A scalar value.’).

classmethod from_dict(d)¶

Instances the object from a dictionary representation.

Parameters:	d – Dictionary containing a serialised object.
Returns:	An object instance.

to_dict()¶

Returns a dictionary representation of the object.

Returns:	A data object dictionary.

String Class¶

Full Object:

class sal.dataclass.String(value, description=None)¶

A SAL data class that contains a string.

Holds a single string and an associated description. The string must be a python str object.

Parameters:	value – The string. description – A string describing the string contents (default=’A string.’).

SUMMARY_CLASS¶: alias of StringSummary

classmethod from_dict(d)¶

Instances the object from a dictionary representation.

Parameters:	d – Dictionary containing a serialised object.
Returns:	An object instance.

summary()¶

Returns a summary of the Scalar object.

Returns:	A ScalarSummary object.

to_dict()¶

Returns a dictionary representation of the object.

Returns:	A data object dictionary.

value¶: The string contents.

Summary Object:

class sal.dataclass.StringSummary(description=None)¶

The summary object for String.

See the String class for more information.

Parameters:	description – A string describing the contents of the string (default=’A string.’).

classmethod from_dict(d)¶

Instances the object from a dictionary representation.

Parameters:	d – Dictionary containing a serialised object.
Returns:	An object instance.

to_dict()¶

Returns a dictionary representation of the object.

Returns:	A data object dictionary.

Dictionary Class¶

Full Object:

class sal.dataclass.Dictionary(items=None, description=None)¶

A SAL data class containing a collection of key-value pairs.

A dictionary class contains a collection of data values indexed by a key. The key is a string (e.g. ‘enabled’, ‘gain’) that is unique in the dictionary. The key strings must consist of only the characters:

[a-z] [0-9] . - _

Associated with each key is a value. The following types are supported for the item values:

Python types:

bool, int, float, str

Numpy:

int8, int16, int32, int64, uint8, uint16, uint32, uint64, float32, float64, bool

Python types are automatically promoted to the equivalent numpy types.

This object behaves like a standard python dictionary and supports nearly all the basic dictionary operations.

Parameters:	items – A dictionary containing item values. description – A string describing the dictionary (default=’A dictionary.’).

SUMMARY_CLASS¶: alias of DictionarySummary

classmethod from_dict(d)¶

Instances the object from a dictionary representation.

Parameters:	d – Dictionary containing a serialised object.
Returns:	An object instance.

summary()¶

Returns a summary of the Dictionary object.

Returns:	A DictionarySummary object.

to_dict()¶

Returns a dictionary representation of the object.

Returns:	A data object dictionary.

Summary Object:

class sal.dataclass.DictionarySummary(description=None)¶

The summary object for Dictionary.

See the Dictionary class for more information.

Parameters:	description – A string describing the dictionary (default=’A dictionary.’).

classmethod from_dict(d)¶

Instances the object from a dictionary representation.

Parameters:	d – Dictionary containing a serialised object.
Returns:	An object instance.

to_dict()¶

Returns a dictionary representation of the object.

Returns:	A data object dictionary.

Array Class¶

Full Object:

class sal.dataclass.Array(shape, data=None, dtype=None, description=None)¶

A SAL data class representing an N-dimensional array.

The data array shape is is a tuple defining the length of each dimension. For example:

Array(shape=(50,)) creates a 50 element 1D array

Array(shape=(10, 10)) creates a 10x10 element 2D array

The data array data type can be configured with the dtype parameter. The following data types are permitted:

python:

int, float

numpy:

int8, int16, int32, int64, uint8, uint16, uint32, uint64, float32, float64

The dtype parameter is passed to the numpy array function and therefore supports all representations of type that numpy does, such as type strings (‘float64’) or type objects (np.float64).

The array can be populated at initialisation using the data parameter. This should be an array, or sequence interpretable as a numpy array, of the same shape as the array dimensions. The data will be converted to the data type specified for the array.

A array description may be provided. Though it is optional, it is highly recommended. The description string must never be used for storing additional metadata, it is intended for human consumption only. The description is a python string and therefore supports UTF8 characters.

Parameters:	shape – A tuple defining the dimensions of the array. data – Initial data to populate the data array with (default=None). dtype – The data type for the data array (default=np.float64). description – A string describing the array (default=’An array.’).

SUMMARY_CLASS¶: alias of ArraySummary

classmethod from_dict(d)¶

Instances the object from a dictionary representation.

Parameters:	d – Dictionary containing a serialised object.
Returns:	An object instance.

summary()¶

Returns a summary of the Array object.

Returns:	A ArraySummary object.

to_dict()¶

Returns a dictionary representation of the object.

Returns:	A data object dictionary.

Summary Object:

class sal.dataclass.ArraySummary(shape, description=None)¶

The summary object for Array.

See the Array class for more information.

classmethod from_dict(d)¶

Instances the object from a dictionary representation.

Parameters:	d – Dictionary containing a serialised object.
Returns:	An object instance.

to_dict()¶

Returns a dictionary representation of the object.

Returns:	A data object dictionary.

Signal Class¶

The signal class is built from a main Signal object that contains sub-objects. The sub-objects define the signal dimensions, errors and masks.

Full Object:

class sal.dataclass.Signal(dimensions, data=None, dtype=None, error=None, mask=None, units=None, description=None)¶

A SAL data class representing an N-dimensional signal.

This data class represents an N-dimensional signal such as a time series or profile. A Signal object holds an N-dimensional array of data, the shape of which is defined by a collection of Dimension objects. The data array and dimensions may each be given Error objects to describe the uncertainty in their data. An additional Mask may be supplied to provide additional metadata for each point in the data array.

Dimension objects describe a single axis of the data array. There are a number of different types of dimension classes that may be used to describe an axis. Dimension objects provide a method to store data for each position along the axis, typically an array or function for calculating the values. For more information see the documentation for the Dimension classes.

Similar to Dimension classes there are a range of different Error classes that may be used to describe the uncertainty in the Signal data and Dimension data. For more information see the documentation for the Error classes.

A data Mask object may be provided for a signal. These classes allow users to add additional data associated with each data point in the Signal data array. For example a Mask object may be used to describe which data points contain a feature of interest or are untrusted due to a diagnostic being saturated.

The minimal requirements to create a signal object is a list of Dimension objects. This will create an Signal object with an empty data array using the default data type. For example:

s = Signal([
    CalculatedDimension(length=1000, start=0.0, step=0.1, units='s', temporal=True, description='Timebase.')
    CalculatedDimension(length=25, start=2.8, step=0.1, units='m', temporal=False, description='Radius.')
])

This will create a Signal with an empty data array of shape (1000, 25). The rest of the signal will assume default values.

The data array shape must not be changed once the Signal is created as this will make the data array inconsistent with the stated dimensions. This will lead to the object being rejected by the SAL server.

Dimensions flagged as temporal (e.g. time-bases) must occur first in the list of dimensions. Lists that do not conform to this requirement will result in an exception being raised.

The data array data type can be configured with the dtype parameter. The following data types are permitted:

python:

int, float

numpy:

int8, int16, int32, int64, uint8, uint16, uint32, uint64, float32, float64

The dtype parameter is passed to the numpy array function and therefore supports all representations of type that numpy does, such as type strings (‘float64’) or type objects (np.float64).

The signal data array can be populated at initialisation using the data parameter. This should be an array, or sequence interpretable as a numpy array, of the same shape as the signal dimensions. The data will be converted to the data type specified for the signal.

If an error and/or Mask object are required, these may be passed via the error and mask parameters respectively. Both objects must have shapes compatible with the signal data array shape.

The data units for the signal may be specified via the units parameter. This must be a python string and should contain the shortened form of the relevant units system (e.g. SI units: m, mT, us). By default, the units string is ‘au’ meaning ‘arbitrary units’. Symbols are supported via UTF-8 support in Python, for example ‘Ω’ is the UTF8 code for the Greek capital omega symbol.

A signal description may be provided. Though it is optional, it is highly recommended. A good description of the signal will place the signal in context and identify any nuances of the data that are not obvious by looking at the data alone. The description string must never be used for storing additional metadata, it is intended for human consumption only. The description is a python string and therefore supports UTF8 characters, as per the units string.

The following example code will create a Signal object with full uncertainties on the signal data and dimension data. Note that this example is written with full verbosity, in practice real code will be more compact:

s = Signal(
    dimensions=[
        CalculatedDimension(
            length=5,
            start=0.0,
            step=0.1,
            error=ConstantError(
                lower=1e-6,
                upper=1e-6,
                relative=False,
                description='Timebase uncertainty.'
            ),
            units='s',
            temporal=True,
            description='Timebase.'
        ),
        ArrayDimension(
            data=np.array([1.5, 2.5]),
            dtype=np.float32,
            error=ConstantError(
                lower=0.01,
                upper=0.01,
                relative=False,
                description='Radius uncertainty.'
            ),
            units='m',
            temporal=False,
            description='Radius.')
    ],
    data=np.array([[-2.0, -1.3], [0.1, 0.7], [3.5, -1.0], [-0.8, 0.4], [-5.6, -8.9]]),
    dtype=np.float32,
    error=ConstantError(
        lower=0.1,
        upper=0.1,
        relative=True,
        description='Field magnitude uncertainty.'
    ),
    mask=None,
    units='mT',
    description='Magnetic field magnitude measured at two radial positions vs time.'
)

Parameters:

dimensions – A list of Dimension objects.
data – Initial data to populate the data array with (default=None).
dtype – The data type for the data array (default=np.float64).
error – An Error object or None (default=None)
mask – A Mask object or None (default=None)
units – A string describing the data units (default=’au’).
description – A string describing the signal (default=’A signal.’).

SUMMARY_CLASS¶: alias of SignalSummary

classmethod from_dict(d)¶

Instances the object from a dictionary representation.

Parameters:	d – Dictionary containing a serialised object.
Returns:	An object instance.

summary()¶

Returns a summary of the Signal object.

Returns:	A SignalSummary object.

to_dict()¶

Returns a dictionary representation of the object.

Returns:	A data object dictionary.

Summary Object:

class sal.dataclass.SignalSummary(dimensions, error=None, mask=None, units=None, description=None)¶

The summary object for Signal.

This object contains a subset of the data held by Signal. The SignalSummary is identical to Signal except that the data array is not present and the Dimension, Error and Mask objects are replaced by their equivalent summary objects.

See the Signal class for more information.

Parameters:	dimensions – A list of DimensionSummary objects. error – An ErrorSummary object or None (default=None). mask – A MaskSummary object or None (default=None). units – A string describing the data units (default=’au’). description – A string describing the signal (default=’A signal.’).

classmethod from_dict(d)¶

Instances the object from a dictionary representation.

Parameters:	d – Dictionary containing a serialised object.
Returns:	An object instance.

to_dict()¶

Returns a dictionary representation of the object.

Returns:	A data object dictionary.

Signal Dimensions¶

Dimensions are defined with one or more of the following dimension classes.

Full Objects:

class sal.dataclass.CalculatedDimension(length, start, step, units=None, error=None, temporal=False, description=None)¶

A dimension defined by a start point, length and step.

A calculated dimensions is defined by a length, start value and step value. The value of the dimension coordinate increases by the value step for each point along the dimension, starting at a defined start value.

This class is ideal for representing timebases or coordinate dimensions where the dimension is derived from regularly sampled data e.g. an oscilloscope timebase.

An error object may be provided to describe the uncertainty in the dimension values.

If the dimension is a timebase, the temporal flag should be set to True.

Units and description strings may be supplied.

In addition to provided in the input parameters as class attributes, the class provides an ‘end’ attribute that is the calculated end value of the array. A ‘data’ attribute returns the value at each point along the dimensions as a numpy array.

Parameters:

length – The length of the dimension.
start – The start value.
step – The increment value.
units – A string describing the data units (default=’au’).
error – An Error object or None (default=None).
temporal – True is the dimension represent time, False otherwise (default=False).
description – A string describing the signal (default=’A signal.’).

SUMMARY_CLASS¶: alias of CalculatedDimensionSummary

classmethod from_dict(d)¶

Instances the class from a dictionary representation.

Parameters:	d – Dictionary containing a serialised object.
Returns:	An object instance.

summary()¶

Returns a summary of the data object.

Returns:	A DataSummary object.

to_dict()¶

Returns a dictionary representation of the data object.

Returns:	A data object dictionary.

class sal.dataclass.ArrayDimension(data, dtype=None, units=None, error=None, temporal=False, description=None)¶

A dimension defined by an array of values.

An array dimension is defined by a 1 dimensional array containing the axis values for each point along the dimension. The array length defines the length of the dimension.

The datatype of the array may be overridden using the dtype parameter. The permitted datatypes are identical to those listed for Signal.

An error object may be provided to describe the uncertainty in the dimension values.

If the dimension is a timebase, the temporal flag should be set to True.

Units and description strings may be supplied.

Parameters:	data – Array of axis values. dtype – The data type for the data array (default=np.float64). units – A string describing the data units (default=’au’). error – An Error object or None (default=None). temporal – True is the dimension represent time, False otherwise (default=False). description – A string describing the signal (default=’A signal.’).

SUMMARY_CLASS¶: alias of ArrayDimensionSummary

classmethod from_dict(d)¶

Instances the class from a dictionary representation.

Parameters:	d – Dictionary containing a serialised object.
Returns:	An object instance.

summary()¶

Returns a summary of the data object.

Returns:	A DataSummary object.

to_dict()¶

Returns a dictionary representation of the data object.

Returns:	A data object dictionary.

Summary Objects:

class sal.dataclass.CalculatedDimensionSummary(length, units=None, error=None, temporal=False, description=None)¶

The calculated dimension summary class.

Parameters:	length – The length of the dimension. error – An ErrorSummary object or None (default=None) units – A string describing the data units (default=’au’). temporal – True if the dimension is a timebase, False otherwise. description – A string describing the signal (default=’A signal.’).

class sal.dataclass.ArrayDimensionSummary(length, units=None, error=None, temporal=False, description=None)¶

The array dimension summary class.

Parameters:	length – The length of the dimension. error – An ErrorSummary object or None (default=None) units – A string describing the data units (default=’au’). temporal – True if the dimension is a timebase, False otherwise. description – A string describing the signal (default=’A signal.’).

Signal Errors¶

Signal data and dimension errors are defined using one of the following error classes.

Full Objects:

class sal.dataclass.ConstantError(lower, upper, relative=False, description=None)¶

A signal error that is constant over the data range.

The upper and lower uncertainties can be defined independently to support asymmetric uncertainties. Errors may be specified as absolute or relative.

The lower and upper error bars are defined independently and apply to the entire range of data to which this error class is applied. The errors values must be correspond to 1 standard deviation.

By default the errors are absolute (relative=False). If relative is set to True, the lower and upper errors are treated as relative errors e.g. lower = 0.1 corresponds to a 10% relative error.

Parameters:	lower – The lower uncertainty. upper – The upper uncertainty. relative – True if the error is relative, False if absolute (default=False). description – A text description of the error.

SUMMARY_CLASS¶: alias of ConstantErrorSummary

classmethod from_dict(d)¶

Instances the class from a dictionary representation.

Parameters:	d – Dictionary containing a serialised object.
Returns:	An object instance.

shape_compatible(shape)¶

Checks the error data dimensions are compatible.

Parameters:	shape – A tuple containing array dimensions.
Returns:	True if compatible, False otherwise.

summary()¶

Returns a summary of the data object.

Returns:	A DataSummary object.

to_dict()¶

Returns a dictionary representation of the data object.

Returns:	A data object dictionary.

class sal.dataclass.SymmetricArrayError(data, dtype=None, description=None)¶

A signal error that varies over the data range.

The error is symmetrical with both upper and lower uncertainties defined by a single value at each point.

The dimensions of the error are defined by the shape of the data supplied. The shape must match the shape of the object to which the error is being attached, otherwise an exception will be raised.

The errors values in the array must be correspond to 1 standard deviation and, as error magnitudes, must be only positive values.

The datatype of the array may be overridden using the dtype parameter. The permitted datatypes are identical to those listed for Signal.

Parameters:	data – Array holding the error values. dtype – The data type for the data array (default=np.float64). description – A text description of the error.

SUMMARY_CLASS¶: alias of SymmetricArrayErrorSummary

classmethod from_dict(d)¶

Instances the class from a dictionary representation.

Parameters:	d – Dictionary containing a serialised object.
Returns:	An object instance.

shape_compatible(shape)¶

Checks the error data dimensions are compatible.

Parameters:	shape – A tuple containing array dimensions.
Returns:	True if compatible, False otherwise.

summary()¶

Returns a summary of the data object.

Returns:	A DataSummary object.

to_dict()¶

Returns a dictionary representation of the data object.

Returns:	A data object dictionary.

class sal.dataclass.AsymmetricArrayError(lower, upper, dtype=None, description=None)¶

A signal error that varies over the data range.

The error is asymmetrical with independent upper and lower uncertainties defined by separate data arrays.

The dimensions of the error are defined by the shape of the data supplied. The shape must match the shape of the object to which the error is being attached, otherwise an exception will be raised.

The lower and upper errors are magnitudes and must contain only positive values. The errors values in the array must be correspond to 1 standard deviation.

The datatype of the arrays may be overridden using the dtype parameter. The permitted datatypes are identical to those listed for Signal.

Parameters:	lower – Array holding the lower error values. upper – Array holding the upper error values. dtype – The data type for the data array (default=np.float64). description – A text description of the error.

SUMMARY_CLASS¶: alias of AsymmetricArrayErrorSummary

classmethod from_dict(d)¶

Instances the class from a dictionary representation.

Parameters:	d – Dictionary containing a serialised object.
Returns:	An object instance.

shape_compatible(shape)¶

Checks the error data dimensions are compatible.

Parameters:	shape – A tuple containing array dimensions.
Returns:	True if compatible, False otherwise.

summary()¶

Returns a summary of the data object.

Returns:	A DataSummary object.

to_dict()¶

Returns a dictionary representation of the data object.

Returns:	A data object dictionary.

Summary Objects:

class sal.dataclass.ConstantErrorSummary(description)¶: The constant error summary class.

class sal.dataclass.SymmetricArrayErrorSummary(description)¶: The symmetric array error summary class.

class sal.dataclass.AsymmetricArrayErrorSummary(description)¶: The asymmetric array error summary class.

Signal Masks¶

Signal masks (for example quality indicators for the signal timepoints) are defined using one of the following classes.

Full Objects:

class sal.dataclass.ScalarStatus(status, key, description=None)¶

SUMMARY_CLASS¶: alias of ScalarStatusSummary

classmethod from_dict(d)¶

Instances the class from a dictionary representation.

Parameters:	d – Dictionary containing a serialised object.
Returns:	An object instance.

summary()¶

Returns a summary of the data object.

Returns:	A DataSummary object.

to_dict()¶

Returns a dictionary representation of the data object.

Returns:	A data object dictionary.

class sal.dataclass.ArrayStatus(status, key, description=None)¶

SUMMARY_CLASS¶: alias of ArrayStatusSummary

classmethod from_dict(d)¶

Instances the class from a dictionary representation.

Parameters:	d – Dictionary containing a serialised object.
Returns:	An object instance.

summary()¶

Returns a summary of the data object.

Returns:	A DataSummary object.

to_dict()¶

Returns a dictionary representation of the data object.

Returns:	A data object dictionary.

Summary Objects:

class sal.dataclass.ScalarStatusSummary(description)¶

class sal.dataclass.ArrayStatusSummary(description)¶