tag

This module consists of two classes, Tag and VirtualTag, which are used to represent data streams at a treatment facility.

class pype_schema.tag.DownsampleType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Enum to represent common methods of downsampling data.

class pype_schema.tag.OperationMode(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Enum to represent methods of VirtualTag operations.

class pype_schema.tag.Tag(id, units, tag_type, source_unit_id, dest_unit_id, parent_id, totalized=False, contents=None, manufacturer=None, measure_freq=None, report_freq=None, downsample_method=None, calibration=<pype_schema.logbook.Logbook entries:{}>)

Class to represent a SCADA or other data tag

Parameters:

• id (str) – Tag ID

• units (str or Unit) – Units represented as a string or Pint unit. E.g., ‘MGD’ or ‘cubic meters’ or <Unit(‘MGD’)>

• tag_type (TagType) – Type of data saved under the tag. E.g., InfluentFlow or RunTime

• source_unit_id (int or str) – integer representing unit number, or total if a combined data point across all units of the source node

• dest_unit_id (int or str) – integer representing unit number, or total if a combined data point across all units of the destination node. None if the Tag is associated with a Node object instead of a Connection

• parent_id (str) – ID for the parent object (either a Node or Connection)

• totalized (bool) – True if data is totalized. False otherwise

• contents (ContentsType) – Data stream contents. E.g., WasteActivatedSludge or NaturalGas

• manufacturer (str) – Name of the manufacturer for the physical sensor hardware. Default is None

• measure_freq (pint.Quantity) – Measurement frequency of the data with units. None by default

• report_freq (pint.Quantity) – Reporting frequency of the data with units. None by default

• downsample_method (DownsampleType) – None by default, meaning that data is reported on the same frequency as measured

• calibration (Logbook) – A history of sensor calibration.

Variables:

• id (str) – Tag ID

• units (Unit) – Units represented as a Pint unit. E.g., <Unit(‘MGD’)>

• tag_type (TagType) – Type of data saved under the tag. E.g., InfluentFlow or RunTime

• source_unit_id (int or str) – integer representing unit number, or total if a combined data point across all units of the sources node

• dest_unit_id (int or str) – integer representing unit number, or total if a combined data point across all units of the destination node

• parent_id (str) – ID for the parent object (either a Node or Connection)

• totalized (bool) – True if data is totalized. False by default

• contents (ContentsType) – Contents moving through the node

• manufacturer (str) – Name of the manufacturer for the physical sensor hardware. Default is None

• measure_freq (pint.Quantity) – Measurement frequency of the data with units. None by default

• report_freq (pint.Quantity) – Reporting frequency of the data with units. None by default

• downsample_method (DownsampleType) – None by default, meaning that data is reported on the same frequency as measured

• calibration (Logbook) – A history of sensor calibration.

check_type_compatibility(other_type)

Check if the given tag_type is compatible with another

Parameters:

other_type (TagType) – Type of tag to compare against

Returns:

True if compatible, False otherwise

Return type:

bool

class pype_schema.tag.TagType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Enum to represent types of SCADA tags.

class pype_schema.tag.VirtualTag(id, tags, unary_operations=None, binary_operations=None, custom_operations=None, units=None, tag_type=None, parent_id=None, contents=None)

Representation for data that is not in the SCADA system, but is instead a combination of existing tags.

Tags are combined via either custom_operations lambda function string or the unary_operations and binary_operations lists depending on whether mode is Algebraic or Custom.

In Algebraic mode, all unary operations are applied before any binary operations.

Parameters:

• id (str) – VirtualTag ID

• tags (list of Tag) – List of Tag objects to combine

• unary_operations (str or list) – Function to apply when combining tags. If a single string it will be applied to all Tags. Otherwise, the unary_operations must be same length as tags, and functions will be applied in order

• binary_operations (str or list) – Function to apply when combining tags. If a single string it will be applied to all Tags. Otherwise, the binary_operations must be one shorter than tags, and functions will be applied in order

• custom_operations (str) – String a lambda function to apply to all tags, must have number of args equal to number of tags

• tag_type (TagType) – Type of data saved under the tag. E.g., InfluentFlow or RunTime. Default is None, and it will be automatically determined from constituent Tags if they all have the same type.

• parent_id (str) – ID for the parent object (either a Node or Connection)

• contents (ContentsType) – Contents moving through the node. Default is None, and it will be automatically determined from consituent Tag contents

Raises:

• ValueError – When operations lambda function has the wrong number of elements When tag_type is not specified and constituent tags have different types. When contents of the constituent tags are different types.

• UserWarning – When a mix of totalized and detotalized tags are combined When tags have different units

Variables:

• id (str) – Tag ID

• tags (list of Tag) – List of Tag objects to combine

• unary_operations (["noop", "delta", "<<", ">>", "~", "-"]) –

  Unary operations to apply before combining tags.

  ”noop” : null operator, useful when skipping tags in a list of unary operations.

  ”delta” : calculate the difference between the current timestep and previous timestep

  ”<<” : shift all data left one timestep, so that the last time step will be NaN

  ”>>” : shift all data right one timestep, so that the first time step will be NaN

  ”~” : Boolean not

  ”-” : unary negation

  Note that “delta”, “<<”, and “>>” return a timeseries padded with NaN so that it is the same length as input data

• binary_operations (["+", "-", "*", "/"]) – Binary operaitons to apply when combining tags. Supported functions are “+”, “-”, “*”, and “/”. If a single string is passed, it will be applied to all Tags. Otherwise, the binary_operations list must be one shorter than tags, and functions will be applied in order from left to right

• custom_operations (str) – String giving a lambda function to apply to constituent tags

• units (str or Unit) – Units represented as a string or Pint unit. E.g., ‘MGD’ or ‘cubic meters’ or <Unit(‘MGD’)>

• tag_type (TagType) – Type of data saved under the tag. E.g., InfluentFlow or RunTime

• totalized (bool) – True if data is totalized. False otherwise

• parent_id (str) – ID for the parent object (either a Node or Connection)

• contents (ContentsType) – Contents moving through the node

• mode (OperationMode) – Mode of operation. Either Algebraic or Custom. Automatically determined based on values of unary_operations, binary_operations and custom_operations.

calculate_values(data, tag_to_var_map={})

Combine the given data according to the VirtualTag’s operations

Parameters:

• data (list, array, dict, or DataFrame) – a list, numpy array, or pandas DataFrame of data that has the correct dimensions. I.e., the number of columns is one more than binary operations and same length as unary operations

• tag_to_var_map (dict) – dictionary of the form { tag.id : variable_name } for using data files that differ from the original SCADA tag naming system

Returns:

numpy array of combined dataset

Return type:

list, array, or Series

process_binary_ops(data, tag_to_var_map={})

Combine the given data according to the VirtualTag’s binary operations

Parameters:

• data (list, array, dict, or DataFrame) – a list, numpy array, or pandas DataFrame of data that has the correct dimensions. I.e., the number of columns is one more than binary operations and same length as unary operations

• tag_to_var_map (dict) – dictionary of the form { tag.id : variable_name } for using data files that differ from the original SCADA tag naming system

Returns:

numpy array of combined dataset

Return type:

list, array, or Series

process_custom_ops(data, tag_to_var_map={})

Transform the given data according to the VirtualTag’s lambda string

Parameters:

• data (list, array, dict, or DataFrame) – a list, numpy array, or pandas DataFrame of data that has the correct dimensions. I.e., the number of columns is one more than binary operations and same length as unary operations

• tag_to_var_map (dict) – dictionary of the form { tag.id : variable_name } for using data files that differ from the original SCADA tag naming system

Returns:

numpy array of combined dataset

Return type:

list, array, or Series

process_unary_ops(data, tag_to_var_map={})

Transform the given data according to the VirtualTag’s unary operator

Parameters:

• data (list, array, dict, or DataFrame) – a list, numpy array, or pandas DataFrame of data that has the correct dimensions. I.e., the number of columns is one more than binary operations and same length as unary operations

• un_op ([“noop”, “delta”, “<<”, “>>”, “~”, “-“]) –

  Supported operations are:

  “noop” : null operator, useful when skipping tags in a list of unary operations.

  “delta” : calculate the difference between the current timestep and previous timestep

  “<<” : shift all data left one timestep, so that the last time step will be NaN

  “>>” : shift all data right one timestep, so that the first time step will be NaN

  “~” : Boolean not

  “-” : unary negation

  Note that “delta”, “<<”, and “>>” return a timeseries padded with NaN so that it is the same length as input data

• tag_to_var_map (dict) – dictionary of the form { tag.id : variable_name } for using data files that differ from the original SCADA tag naming system

Returns:

numpy array of combined dataset

Return type:

list, array, or Series

pype_schema.tag.check_type_compatibility(tag_type, other_type)

Check if the given tag_type is compatible with another

Parameters:

• tag_type (TagType) – Type of the first tag

• other_type (TagType) – Type of tag to compare against

Returns:

True if compatible, False otherwise

Return type:

bool