Module `v1`

Functions

def float_list_to_csv_string(float_list)
def packed_floats(data): Validate data and convert to a packed float buffer
def validate_dims(data): Validate that data is non-empty and one of the following: scalar value, list-like or list-of-lists-like where all sublists have equal length. Return 0, 1 or 2 as inferred number of array dimensions

Classes

class AmberCloudError (code, message)

Raised upon any non-200 response from the Amber cloud

Ancestors

boonamber.util.ambererror.AmberCloudError
builtins.Exception
builtins.BaseException

class AmberUserError (message)

Raised to indicate an error in SDK usage

Ancestors

boonamber.util.ambererror.AmberUserError
builtins.Exception
builtins.BaseException

class AmberV1Client (license_id='default', license_file='~/.Amber.license', verify=True, cert=None, timeout=300)

Main client which interfaces with the Amber cloud. Amber account credentials are discovered within a .Amber.license file located in the home directory, or optionally overridden using environment variables.

Args

license_id : str: license identifier label found within .Amber.license file
license_file : str: path to .Amber.license file
verify: Boolean, controls whether we verify the server’s TLS certificate
cert : bool: if String, path to ssl client cert file (.pem). If Tuple, (‘cert’, ‘key’) pair.

Environment

AMBER_LICENSE_FILE: sets license_file path

AMBER_LICENSE_ID: sets license_id

AMBER_USERNAME: overrides the username as found in .Amber.license file

AMBER_PASSWORD: overrides the password as found in .Amber.license file

AMBER_SERVER: overrides the server as found in .Amber.license file

AMBER_OAUTH_SERVER: overrides the oauth server as found in .Amber.license file

AMBER_SSL_CERT: path to ssl client cert file (.pem)

AMBER_SSL_VERIFY: Either a boolean, in which case it controls whether we verify the server’s TLS certificate, or a string, in which case it must be a path to a CA bundle to use

Raises

AmberUserError: if error supplying authentication credentials

Subclasses

boonamber.AmberClient
AmberV1Client

Methods

def configure_fusion(self, sensor_id, feature_count=5, features=None)

Configure an Amber instance for sensor fusion

Args

sensor_id : str: sensor identifier
feature_count : int: number of features or data streams to fuse together
features : list: optional list of per feature settings overriding feature_count. Allows direct setting of feature labels and rules for submitting the fusion vector: [ { 'label': string, 'submitRule': string (one of: 'submit', 'nosubmit') }, … ]

Returns

A list of features as configured

Raises

AmberUserError: if client is not authenticated or supplies invalid data
AmberCloudError: if Amber cloud gives non-200 response.

def configure_sensor(self, sensor_id, feature_count=1, streaming_window_size=25, samples_to_buffer=10000, anomaly_history_window=10000, learning_rate_numerator=10, learning_rate_denominator=10000, learning_max_clusters=1000, learning_max_samples=1000000, features=None, override_pv=None)

Configure an amber sensor instance

Args

sensor_id : str: sensor identifier
feature_count : int: number of features (dimensionality of each data sample)
streaming_window_size : int: streaming window size (number of samples)
samples_to_buffer : int: number of samples to load before autotuning
anomaly_history_window : int: number of samples to use for AH calculation
learning_rate_numerator : int: sensor "graduates" (i.e. transitions from learning to monitoring mode) if fewer than learning_rate_numerator new clusters are opened in the last learning_rate_denominator samples
learning_rate_denominator : int: see learning_rate_numerator
learning_max_clusters : int: sensor graduates if this many clusters are created
learning_max_samples : int: sensor graduates if this many samples are processed
features : list: optional list of per feature settings (minVal, maxVal, and label)
override_pv : float: force percent variation to specific value

Returns

A dictionary containing:

{
    'feature_count': int,
    'streaming_window_size': int,
    'samples_to_buffer': int
    'anomaly_history_window': int,
    'learning_rate_numerator': int,
    'learning_rate_denominator': int,
    'learning_max_clusters': int,
    'learning_max_samples': int,
    'features': [
        {
            'minVal': float,
            'maxVal': float,
            'label': string,
            'weight': float,
            'submitRule': string
        },
        ...
    ]
}

Raises

AmberUserError: if client is not authenticated or supplies invalid options
AmberCloudError: if Amber cloud gives non-200 response

def create_sensor(self, label='')

Create a new sensor instance

Args

label : str: label to assign to created sensor

Returns

A string containing the sensor_id that was created

Raises

AmberUserError: if client is not authenticated
AmberCloudError: if Amber cloud gives non-200 response

def delete_sensor(self, sensor_id)

Delete an amber sensor instance

Args

sensor_id : str: sensor identifier

Raises

AmberUserError: if client is not authenticated
AmberCloudError: if Amber cloud gives non-200 response

def enable_learning(self, sensor_id, learning_rate_numerator=None, learning_rate_denominator=None, learning_max_clusters=None, learning_max_samples=None)

Enable learning for a sensor thats in monitoring state

Args

sensor_id : str: sensor identifier
learning_rate_numerator : int: number of new clusters created as a max before turning off learning
learning_rate_denominator : int: number of recent inferences to count the number of new clusters over
learning_max_clusters : int: maximum number of clusters allowed to be created
learning_max_samples : int: maximum number of samples to process in learning

Returns

{ 'learning_rate_numerator': int, 'learning_rate_denominator': int, 'learning_max_clusters': int, 'learning_max_samples': int }

Raises

AmberUserError: if client is not authenticated or supplies invalid data
AmberCloudError: if Amber cloud gives non-200 response

def get_config(self, sensor_id)

Get current sensor configuration

Args

sensor_id : str: sensor identifier

Returns

A dictionary containing the current sensor configuration:

{
    'featureCount': int,
    'streamingWindowSize': int,
    'samplesToBuffer': int,
    'anomalyHistoryWindow': int,
    'learningRateNumerator': int,
    'learningRateDenominator': int,
    'learningMaxClusters': int,
    'learningMaxSamples': int,
    'percentVariation': float,
    'features':
    [
        {
            'min': float,
            'max': float
        }
    ]
}

'featureCount': number of features (dimensionality of each data sample)
'streamingWindowSize': streaming window size (number of samples)
'samplesToBuffer': number of samples to load before autotuning
'anomalyHistoryWindow': number of samples to calculate normal anomaly variation
'learningRateNumerator': sensor "graduates" (i.e. transitions from
    learning to monitoring mode) if fewer than learning_rate_numerator
    new clusters are opened in the last learning_rate_denominator samples
'learningRateDenominator': see learning_rate_numerator
'learningMaxClusters': sensor graduates if this many clusters are created
'learningMaxSamples': sensor graduates if this many samples are processed
'percentVariation': percent variation parameter discovered by autotuning
'features': min/max values per feature discovered by autotuning

Raises

AmberUserError: if client is not authenticated
AmberCloudError: if Amber cloud gives non-200 response

def get_pretrain_state(self, sensor_id)

Gets the state of sensor that is being pretrained

Args

sensor_id : str: sensor identifier

Returns

{ 'state': str }

'state': current state of the sensor. One of: "Pretraining": pretraining is in progress "Pretrained": pretraining has completed "Error": error has occurred

Raises

AmberUserError: if client is not authenticated or supplies invalid data
AmberCloudError: if Amber cloud gives non-200 response

def get_root_cause(self, sensor_id, id_list=None, pattern_list=None)

Get root cause

Args

sensor_id : str: sensor identifier
id_list : list: list of IDs to return the root cause for
pattern_list : list: list of pattern vectors to calculate the root cause against the model

Returns

A list containing the root cause for each pattern/id provided for a sensor:

[float]

Raises

AmberUserError: if client is not authenticated
AmberCloudError: if Amber cloud gives non-200 response

def get_sensor(self, sensor_id)

Get info about a sensor

Args

sensor_id : str: sensor identifier

Returns

A dictionary containing sensor information:

{
    'label': str,
    'sensorId': str,
    'tenantId': str,
    'usageInfo': {
        putSensor {
            'callsTotal': int
            'callsThisPeriod': int
            'lastCalled': str
        },
        getSensor {
            'callsTotal': int
            'callsThisPeriod': int
            'lastCalled': str
        },
        getConfig {
            'callsTotal': int
            'callsThisPeriod': int
            'lastCalled': str
        },
        postStream {
            'callsTotal': int
            'callsThisPeriod': int
            'lastCalled': int
            'samplesTotal': int
            'samplesThisPeriod': int
        }
        getStatus {
            'callsTotal': int
            'callsThisPeriod': int
            'lastCalled': str
        }
    }
}

'label' (str): sensor label
'sensorId' (str): sensor identifier
'tenantId' (str): username of associated Amber account
'callsTotal': total number of calls to this endpoint
'callsThisPeriod': calls this billing period to this endpoint
'lastCalled': ISO formatted time of last call to this endpoint
'samplesTotal': total number of samples processed
'samplesThisPeriod': number of samples processed this billing period

Raises

AmberUserError: if client is not authenticated
AmberCloudError: if Amber cloud gives non-200 response

def get_status(self, sensor_id)

Get sensor status

Args

sensor_id : str: sensor identifier

Returns

A dictionary containing the clustering status for a sensor:

{
    'pca' [(int,int,int)],
    'clusterGrowth' [int],
    'clusterSizes' [int],
    'anomalyIndexes' [int],
    'frequencyIndexes' [int],
    'distanceIndexes' [int],
    'totalInferences' [int],
    'numClusters' [int],
}

'pca': list of length-3 vectors representing cluster centroids
    with dimensionality reduced to 3 principal components. List length
    is one plus the maximum cluster ID, with element 0 corresponding
    to the "zero" cluster, element 1 corresponding to cluster ID 1, etc.
'clusterGrowth': sample index at which each new cluster was created.
    Elements for this and other list results are ordered as in 'pca'.
'clusterSizes': number of samples in each cluster
'anomalyIndexes': anomaly index associated with each cluster
'frequencyIndexes': frequency index associated with each cluster
'distanceIndexes': distance index associated with each cluster
'totalInferences': total number of inferences performed so far
'numClusters': number of clusters created so far (includes zero cluster)

Raises

AmberUserError: if client is not authenticated
AmberCloudError: if Amber cloud gives non-200 response

def get_summary(self, sensor_id)

Get summary information for a sensor

Returns

json summary information

Raises

AmberCloudError: if Amber cloud gives non-200 response

def get_version(self)

Get version information for Amber

Returns

json version information

Raises

AmberCloudError: if Amber cloud gives non-200 response

def list_sensors(self)

List all sensor instances currently associated with Amber account

Returns

A dictionary mapping sensor IDs to corresponding labels

Raises

AmberUserError: if client is not authenticated
AmberCloudError: if Amber cloud gives non-200 response

def post_outage(self, sensor_id)

def pretrain_sensor(self, sensor_id, data, autotune_config=True, block=True)

Pretrain a sensor with historical data

Args

sensor_id : str: sensor identifier
data : array-like: data to be inferenced. Must be non-empty, entirely numeric and one of the following: scalar value, list-like or list-of-lists-like where all sublists have equal length.
autotune_config : bool: if True, the sensor will be reconfigured based on the training data provided so that the sensor will be in monitoring once the data is through. If False, the sensor uses the already configured values to train the sensor.
block : bool: if True, will block until pretraining is complete. Otherwise, will return immediately; in this case pretraining status can be checked using get_pretrain_state endpoint.

Returns

{ 'state': str }

'state': current state of the sensor. "Pretraining": pretraining is in progress

Raises

AmberUserError: if client is not authenticated or supplies invalid data
AmberCloudError: if Amber cloud gives non-200 response

def pretrain_sensor_xl(self, sensor_id, data, autotune_config=True, block=True, chunk_size=4000000)

Pretrain a sensor with extra large sets of historical data.

Args

sensor_id : str: sensor identifier
data : array-like: data to be inferenced. Must be non-empty, entirely numeric and one of the following: scalar value, list-like or list-of-lists-like where all sublists have equal length.
autotune_config : bool: if True, the sensor will be reconfigured based on the training data provided so that the sensor will be in monitoring once the data is through. If False, the sensor uses the already configured values to train the sensor.
block : bool: if True, will block until pretraining is complete. Otherwise, will return immediately; in this case pretraining status can be checked using get_pretrain_state endpoint.

Returns

{ 'state': str }

'state': current state of the sensor. "Pretraining": pretraining is in progress

Raises

AmberUserError: if client is not authenticated or supplies invalid data
AmberCloudError: if Amber cloud gives non-200 response

def stream_fusion(self, sensor_id, vector, submit=None)

Stream data to a fusion-configured sensor

Args

sensor_id : str: sensor identifier
vector : list of dict: list of one or more dictionaries, each giving an updated value for one of the sensor fusion features: [ { "label": str, "value": float, }, … ]
submit : bool or None: whether to submit the fusion vector after this update. If None, whether to submit will be determined by the per-feature submit rules.

Returns

When no analytics were generated: A Dict containing current sample vector { "vector": "sample, sample, sample, …", }
When analytics were generated: A Dict containing both the current sample vector and results { "vector": "sample, sample, sample, …", "results": { 'state': str, 'message': str, 'progress': int, 'clusterCount': int, 'retryCount': int, 'streamingWindowSize': int, 'totalInferences': int, 'lastModified': 'int', 'lastModifiedDelta': 'int', 'ID': [int], 'SI': [int], 'AD': [int], 'AH': [int], 'AM': [float], 'AW': [int], 'NI': [int], 'NS': [int], 'NW': [float], 'OM': [float] } }

Raises

AmberUserError: if client is not authenticated or supplies invalid data
AmberCloudError: if Amber cloud gives non-200 response.

def stream_sensor(self, sensor_id, data, save_image=True)

Stream data to an amber sensor and return the inference result

Args

sensor_id : str: sensor identifier
data : array-like: data to be inferenced. Must be non-empty, entirely numeric and one of the following: scalar value, list-like or list-of-lists-like where all sublists have equal length.
save_image : bool: whether to save the image after calculation

Returns

A dictionary containing inferencing results:

{
    'state': str,
    'message': str,
    'progress': int,
    'clusterCount': int,
    'retryCount': int,
    'streamingWindowSize': int,
    'totalInferences': int,
    'lastModified': 'int',
    'lastModifiedDelta': 'int',
    'ID': [int],
    'SI': [int],
    'AD': [int],
    'AH': [int],
    'AM': [float],
    'AW': [int],
    'NI': [int],
    'NS': [int],
    'NW': [float],
    'OM': [float]
}

'state': current state of the sensor. One of:
    "Buffering": gathering initial sensor data
    "Autotuning": autotuning configuration in progress
    "Learning": sensor is active and learning
    "Monitoring": sensor is active but monitoring only (learning disabled)
    "Error": fatal error has occurred
'message': accompanying message for current sensor state
'progress' progress as a percentage value (applicable for "Buffering" and "Autotuning" states)
'clusterCount' number of clusters created so far
'retryCount' number of times autotuning was re-attempted to tune streamingWindowSize
'streamingWindowSize': streaming window size of sensor (may differ from value
    given at configuration if window size was adjusted during autotune)
'totalInferences': number of inferences since configuration
'lastModified': current Unix timestamp when the call was made
'lastModifiedDelta': number of seconds since the last stream call
'ID': list of cluster IDs. The values in this list correspond one-to-one
    with input samples, indicating the cluster to which each input pattern
    was assigned.
'SI': smoothed anomaly index. The values in this list correspond
    one-for-one with input samples and range between 0 and 1000. Values
    closer to 0 represent input patterns which are ordinary given the data
    seen so far on this sensor. Values closer to 1000 represent novel patterns
    which are anomalous with respect to data seen before.
'RI': raw anomaly index. These values are the SI values without any smoothing.
'AD': list of binary anomaly detection values. These correspond one-to-one
    with input samples and are produced by thresholding the smoothed anomaly
    index (SI). The threshold is determined automatically from the SI values.
    A value of 0 indicates that the SI has not exceeded the anomaly detection
    threshold. A value of 1 indicates it has, signaling an anomaly at the
    corresponding input sample.
'AH': list of anomaly history values. These values are a moving-window sum of
    the AD value, giving the number of anomaly detections (1's) present in the
    AD signal over a "recent history" window whose length is the buffer size.
'AM': list of "Amber Metric" values. These are floating point values between
    0.0 and 1.0 indicating the extent to which each corresponding AH value
    shows an unusually high number of anomalies in recent history. The values
    are derived statistically from a Poisson model, with values close to 0.0
    signaling a lower, and values close to 1.0 signaling a higher, frequency
    of anomalies than usual.
'AW': list of "Amber Warning Level" values. This index is produced by thresholding
    the Amber Metric (AM) and takes on the values 0, 1 or 2 representing a discrete
    "warning level" for an asset based on the frequency of anomalies within recent
    history. 0 = normal, 1 = asset changing, 2 = asset critical. The default
    thresholds for the two warning levels are the standard statistical values
    of 0.95 (outlier, asset changing) and 0.997 (extreme outlier, asset critical).
'NI': list of "Novelty Index" values. These are values that show how different a new
    cluster actually is from the model. If the cluster is already in the model, it
    returns a 0. New clusters return an RI type value ranging from 0 to 1000 based on
    the L2 distance it is from the model's clusters.
'NS': list of "Smoothed Novelty Index" values. This is just a weighted average of the
    new NI and the previous NI. These values range from 0 to 1000..
'NW': list of "Novelty Warning Level" values. This is just a scaled version of the NS
    values that now range from 0 to 2 to give a warning level for the asset.
'OM': list of operational mode values that are a sliding average of the cluster IDs
    to give a basic representation of the different states

Raises

AmberUserError: if client is not authenticated or supplies invalid data
AmberCloudError: if Amber cloud gives non-200 response

def update_label(self, sensor_id, label)

Update the label of a sensor instance

Args

sensor_id : str: sensor identifier
label : str: new label to assign to sensor

Returns

A string containing the new label assigned to sensor

Raises

AmberUserError: if client is not authenticated
AmberCloudError: if Amber cloud gives non-200 response