PIconnect.Data module#

Data containers#

class PIconnect.Data.DataContainer#

Bases: ABC

Abstract base class for data containers.

filtered_summaries(start_time: str | datetime, end_time: str | datetime, interval: str | timedelta | Timedelta, filter_expression: str, summary_types: SummaryType, calculation_basis: CalculationBasis = CalculationBasis.TIME_WEIGHTED, filter_evaluation: ExpressionSampleType = ExpressionSampleType.EXPRESSION_RECORDED_VALUES, filter_interval: str | timedelta | Timedelta | None = None, time_type: TimestampCalculation = TimestampCalculation.AUTO) → DataFrame#

Return one or more summary values for each interval within a time range.

Parameters:
Returns:

Dataframe with the unique timestamps as row index and the summary name as column name.

Return type:

pandas.DataFrame

interpolated_value(time: str | datetime) → Series#

Return a pd.Series with an interpolated value at the given time.

Parameters:

time (str, datetime) – String containing the date, and possibly time, for which to retrieve the value. This is parsed, using Time.to_af_time().

Returns:

A pd.Series with a single row, with the corresponding time as the index

Return type:

pandas.Series

interpolated_values(start_time: str | datetime, end_time: str | datetime, interval: str | timedelta | Timedelta, filter_expression: str = '') → Series#

Return a pd.Series of interpolated data.

Data is returned between start_time and end_time at a fixed interval. The first two allow for time specification relative to “now” by use of the asterisk.

filter_expression is an optional string to filter the returned values, see the Performance equation documentation for more information.

The AF SDK allows for inclusion of filtered data, with filtered values marked as such. At this point PIconnect does not support this and filtered values are always left out entirely.

Parameters:
Returns:

Timeseries of the values returned by the SDK

Return type:

pandas.Series

recorded_value(time: str | datetime, retrieval_mode: RetrievalMode = RetrievalMode.AUTO) → Series#

Return a pd.Series with the recorded value at or close to the given time.

Parameters:

  • time (str) – String containing the date, and possibly time, for which to retrieve the value. This is parsed, using Time.to_af_time().

  • retrieval_mode (int or RetrievalMode) – Flag determining which value to return if no value available at the exact requested time.

Returns:

A pd.Series with a single row, with the corresponding time as the index.

Return type:

pandas.Series

recorded_values(start_time: str | datetime, end_time: str | datetime, boundary_type: BoundaryType = BoundaryType.INSIDE, filter_expression: str = '')#

Return a pd.Series of recorded data.

Data is returned between the given start_time and end_time, inclusion of the boundaries is determined by the boundary_type attribute. Both start_time and end_time are parsed by AF.Time and allow for time specification relative to “now” by use of the asterisk.

By default the boundary_type is set to ‘inside’, which returns from the first value after start_time to the last value before end_time. The other options are ‘outside’, which returns from the last value before start_time to the first value before end_time, and ‘interpolate’, which interpolates the first value to the given start_time and the last value to the given end_time.

filter_expression is an optional string to filter the returned values, see OSIsoft PI documentation for more information.

The AF SDK allows for inclusion of filtered data, with filtered values marked as such. At this point PIconnect does not support this and filtered values are always left out entirely.

Parameters:

  • start_time (str or datetime) – Containing the date, and possibly time, from which to retrieve the values. This is parsed, together with end_time, using Time.to_af_time_range().

  • end_time (str or datetime) – Containing the date, and possibly time, until which to retrieve values. This is parsed, together with start_time, using Time.to_af_time_range().

  • boundary_type (BoundaryType) – Specification for how to handle values near the specified start and end time. Defaults to BoundaryType.INSIDE.

  • filter_expression (str, optional) – Defaults to ‘’. Query on which data to include in the results. See Filtering values for more information on filter queries.

Returns:

Timeseries of the values returned by the SDK

Return type:

pandas.Series

summaries(start_time: str | datetime, end_time: str | datetime, interval: str | timedelta | Timedelta, summary_types: SummaryType, calculation_basis: CalculationBasis = CalculationBasis.TIME_WEIGHTED, time_type: TimestampCalculation = TimestampCalculation.AUTO) → DataFrame#

Return one or more summary values for each interval within a time range.

Parameters:
Returns:

Dataframe with the unique timestamps as row index and the summary name as column name.

Return type:

pandas.DataFrame

summary(start_time: str | datetime, end_time: str | datetime, summary_types: SummaryType, calculation_basis: CalculationBasis = CalculationBasis.TIME_WEIGHTED, time_type: TimestampCalculation = TimestampCalculation.AUTO) → DataFrame#

Return one or more summary values over a single time range.

Parameters:
Returns:

Dataframe with the unique timestamps as row index and the summary name as column name.

Return type:

pandas.DataFrame

update_value(value: Any, time: str | datetime | None = None, update_mode: UpdateMode = UpdateMode.NO_REPLACE, buffer_mode: BufferMode = BufferMode.BUFFER_IF_POSSIBLE) → None#

Update value for existing PI object.

Parameters:

  • value – value type should be in cohesion with PI object or it will raise PIException: [-10702] STATE Not Found.

  • time (datetime, optional) – It is not possible to set future value, it raises PIException: [-11046] Target Date in Future.

  • value. (You can combine update_mode and time to change already stored)

property current_value: Any#

Return the current value of the attribute.

abstract property name: str#

Return the name of the data container.

abstract property stepped_data: bool#

Return True if the data is stepped, False if it is continuous.

abstract property units_of_measurement: str | None#

Return the units of measurement of the values in the current object.

class PIconnect.Data.DataContainerCollection(elements: MutableSequence[NamedItemType])#

Bases: NamedItemList[DataContainerType]

Container for a collection of data containers.

filtered_summaries(start_time: str | datetime, end_time: str | datetime, interval: str | timedelta | Timedelta, filter_expression: str, summary_types: SummaryType, calculation_basis: CalculationBasis = CalculationBasis.TIME_WEIGHTED, filter_evaluation: ExpressionSampleType = ExpressionSampleType.EXPRESSION_RECORDED_VALUES, filter_interval: str | timedelta | Timedelta | None = None, time_type: TimestampCalculation = TimestampCalculation.AUTO, align: Literal['auto', 'ffill', 'bfill', 'nearest', 'time', False] = False) → DataFrame#

Return one or more summary values for each interval within a time range.

interpolated_value(time: str | datetime, align: Literal['auto', 'ffill', 'bfill', 'nearest', 'time', False] = False) → DataFrame#

Return a pd.DataFrame with an interpolated value at the given time.

Warning

Relative times are evaluated for each element in the collection, resulting in a different time for each element. To overcome this, use a fixed time, for example using the datetime module:

>>> import datetime
>>> time = datetime.datetime.now() - datetime.timedelta(days=1)
>>> collection.interpolated_value(time)
Parameters:

time (str, datetime) – String containing the date, and possibly time, for which to retrieve the value. This is parsed, using Time.to_af_time().

Returns:

A pd.Series with a single row, with the corresponding time as the index

Return type:

pd.Series

interpolated_values(start_time: str | datetime, end_time: str | datetime, interval: str | timedelta | Timedelta, filter_expression: str = '', align: Literal['auto', 'ffill', 'bfill', 'nearest', 'time', False] = False) → DataFrame#

Return a pd.DataFrame of interpolated data.

Data is returned between start_time and end_time at a fixed interval. The first two allow for time specification relative to “now” by use of the asterisk.

filter_expression is an optional string to filter the returned values, see OSIsoft PI documentation for more information.

The AF SDK allows for inclusion of filtered data, with filtered values marked as such. At this point PIconnect does not support this and filtered values are always left out entirely.

Warning

Relative times are evaluated for each element in the collection, resulting in a different time for each element. To overcome this, use a fixed time, for example using the datetime module:

>>> import datetime
>>> time = datetime.datetime.now() - datetime.timedelta(days=1)
>>> collection.interpolated_value(time)
Parameters:

  • start_time (str or datetime) – Containing the date, and possibly time, from which to retrieve the values. This is parsed, together with end_time, using Time.to_af_time_range().

  • end_time (str or datetime) – Containing the date, and possibly time, until which to retrieve values. This is parsed, together with start_time, using Time.to_af_time_range().

  • interval (str, datetime.timedelta or pd.Timedelta) – String containing the interval at which to extract data. This is parsed using Time.to_af_time_span().

  • filter_expression (str, optional) – Defaults to ‘’. Query on which data to include in the results. See Filtering values for more information on filter queries.

Returns:

Timeseries of the values returned by the SDK

Return type:

pd.DataFrame

recorded_value(time: str | datetime, retrieval_mode: RetrievalMode = RetrievalMode.AUTO, align: Literal['auto', 'ffill', 'bfill', 'nearest', 'time', False] = False) → DataFrame#

Return a pd.Series with the recorded value at or close to the given time.

Parameters:

  • time (str) – String containing the date, and possibly time, for which to retrieve the value. This is parsed, using Time.to_af_time().

  • retrieval_mode (int or RetrievalMode) – Flag determining which value to return if no value available at the exact requested time.

Returns:

A pd.Series with a single row, with the corresponding time as the index.

Return type:

pd.Series

recorded_values(start_time: str | datetime, end_time: str | datetime, boundary_type: BoundaryType = BoundaryType.INSIDE, filter_expression: str = '', align: Literal['auto', 'ffill', 'bfill', 'nearest', 'time', False] = False) → DataFrame#

Return a pd.Series of recorded data.

Data is returned between the given start_time and end_time, inclusion of the boundaries is determined by the boundary_type attribute. Both start_time and end_time and allow for time specification relative to “now” by use of the asterisk.

The AF SDK allows for inclusion of filtered data, with filtered values marked as such. At this point PIconnect does not support this and filtered values are always left out entirely.

Parameters:

  • start_time (str or datetime) – Containing the date, and possibly time, from which to retrieve the values. This is parsed, together with end_time, using Time.to_af_time_range().

  • end_time (str or datetime) – Containing the date, and possibly time, until which to retrieve values. This is parsed, together with start_time, using Time.to_af_time_range().

  • boundary_type (BoundaryType) – Specification for how to handle values near the specified start and end time. Defaults to BoundaryType.INSIDE.

  • filter_expression (str, optional) – Defaults to ‘’. Query on which data to include in the results. See Filtering values for more information on filter queries.

Returns:

Timeseries of the values returned by the SDK

Return type:

pd.Series

summaries(start_time: str | datetime, end_time: str | datetime, interval: str | timedelta | Timedelta, summary_types: SummaryType, calculation_basis: CalculationBasis = CalculationBasis.TIME_WEIGHTED, time_type: TimestampCalculation = TimestampCalculation.AUTO, align: Literal['auto', 'ffill', 'bfill', 'nearest', 'time', False] = False) → DataFrame#

Return one or more summary values for each interval within a time range.

Parameters:
Returns:

Dataframe with the unique timestamps as row index and the summary name as column name.

Return type:

pandas.DataFrame

summary(start_time: str | datetime, end_time: str | datetime, summary_types: SummaryType, calculation_basis: CalculationBasis = CalculationBasis.TIME_WEIGHTED, time_type: TimestampCalculation = TimestampCalculation.AUTO, align: Literal['auto', 'ffill', 'bfill', 'nearest', 'time', False] = False) → DataFrame#

Return one or more summary values over a single time range.

Parameters:
Returns:

Dataframe with the unique timestamps as row index and the summary name as column name.

Return type:

pandas.DataFrame

property current_value: Series#

Return the current values of all attributes in the collection.

AF Enumeration Values#

class PIconnect.Data.AFEnumerationValue(value: AFEnumerationValue)#

Bases: object

Representation of an AF enumeration value.

static wrap_enumeration_value(value: AFEnumerationValue) → AFEnumerationValue#
static wrap_enumeration_value(value: T) → T

Wrap the value in an AFEnumerationValue if it is an enumeration value.

property name: str#

Return the name of the enumeration value.

property value: int#

Return the integer value of the enumeration value.

Enumerations#

Data access and manipulation classes.

class PIconnect.Data.BoundaryType(*values)#

Bases: IntEnum

BoundaryType indicates how to handle the boundaries of a time range.

Detailed information is available at AF.Data.AFBoundaryType.

INSIDE = 0#

The first value after the start time and the last value before the end time

INTERPOLATED = 2#

Interpolate values to the specified start and end time

OUTSIDE = 1#

The last value before the start time and the first value after the end time

class PIconnect.Data.BufferMode(*values)#

Bases: IntEnum

Indicates buffering option in updating values, when supported by the Data Reference.

Detailed information is available at AF.Data.AFBufferOption

BUFFER = 2#
BUFFER_IF_POSSIBLE = 1#

Try updating data reference values with buffer. If fails (e.g. data reference AFDataMethods does not support Buffering, or its Buffering system is not available), then try updating directly without buffer.

DO_NOT_BUFFER = 0#

Updating data reference values without buffer.

class PIconnect.Data.CalculationBasis(*values)#

Bases: IntEnum

CalculationBasis indicates how values should be weighted over a time range.

Detailed information is available at AF.Data.AFCalculationBasis.

EVENT_WEIGHTED = 1#

Each event is weighted equally.

EVENT_WEIGHTED_EXCLUDE_EARLIEST = 5#

Each event is weighted equally, except data at the beginning of the interval is excluded.

EVENT_WEIGHTED_EXCLUDE_MOST_RECENT = 4#

Each event is weighted equally, except data at the end of the interval is excluded.

EVENT_WEIGHTED_INCLUDE_BOTH_ENDS = 6#

Each event is weighted equally, data at both boundaries of the interval are explicitly included.

TIME_WEIGHTED = 0#

Each event is weighted according to the time over which it applies.

TIME_WEIGHTED_CONTINUOUS = 2#

Each event is time weighted, but interpolation is always done as if it is continous data.

TIME_WEIGHTED_DISCRETE = 3#

Each event is time weighted, but interpolation is always done as if it is discrete, stepped, data.

class PIconnect.Data.ExpressionSampleType(*values)#

Bases: IntEnum

ExpressionSampleType indicates how expressions are evaluated over a time range.

Detailed information is available at AF.Data.AFSampleType.

EXPRESSION_RECORDED_VALUES = 0#

The expression is evaluated at each archive event.

INTERVAL = 1#

The expression is evaluated at a sampling interval, passed as a separate argument.

class PIconnect.Data.RetrievalMode(*values)#

Bases: IntEnum

RetrievalMode indicates which recorded value should be returned.

Detailed information is available at AF.Data.AFRetrievalMode.

AFTER = 7#

The first after the requested time

AT_OR_AFTER = 2#

At the exact time if available, else the first after the requested time

AT_OR_BEFORE = 1#

At the exact time if available, else the first before the requested time

AUTO = 0#

Autmatic detection

BEFORE = 6#

The first before the requested time

EXACT = 4#

At the exact time if available, else return an error

class PIconnect.Data.SummaryType(*values)#

Bases: IntFlag

SummaryType indicates which types of summary should be calculated.

SummaryType’s are enum.IntFlag’s and can be or’ed together to select multiple summary types. For example:

>>> SummaryType.MINIMUM | SummaryType.MAXIMUM  # Returns minimum and maximum
<SummaryType.MAXIMUM|MINIMUM: 12>

Detailed information is available at AF.Data.AFSummaryTypes.

ALL = 24831#

A convenience to retrieve all summary types

ALL_FOR_NON_NUMERIC = 8320#

A convenience to retrieve all summary types available for non-numeric data

AVERAGE = 2#

Average value over the time span

COUNT = 128#

The sum of the event count (when the calculation is event weighted). The sum of the event time duration (when the calculation is time weighted.)

MAXIMUM = 8#

The maximum value in the time span

MINIMUM = 4#

The minimum value in the time span

NONE = 0#

No summary data

PERCENT_GOOD = 8192#

The percentage of the data with a good value over the time range. Based on time for time weighted calculations, based on event count for event weigthed calculations.

POP_STD_DEV = 64#

The population standard deviation of the values over the time span

RANGE = 16#

The range of the values (max-min) in the time span

STD_DEV = 32#

The sample standard deviation of the values over the time span

TOTAL = 1#

A total over the time span

TOTAL_WITH_UOM = 16384#

The total over the time span, with the unit of measurement that’s associated with the input (or no units if not defined for the input).

class PIconnect.Data.TimestampCalculation(*values)#

Bases: IntEnum

TimestampCalculation defines the timestamp returned for a given summary calculation.

Detailed information is available at AF.Data.AFTimeStampCalculation.

AUTO = 0#

The timestamp is the event time of the minimum or maximum for those summaries or the beginning of the interval otherwise.

EARLIEST_TIME = 1#

The timestamp is always the beginning of the interval.

MOST_RECENT_TIME = 2#

The timestamp is always the end of the interval.

class PIconnect.Data.UpdateMode(*values)#

Bases: IntEnum

Indicates how to treat duplicate values in the archive.

Only used when supported by the Data Reference.

Detailed information is available at AF.Data.AFUpdateOption

INSERT = 1#

Add the value to the archive. Any existing values at the same time are not overwritten.

INSERT_NO_COMPRESSION = 5#

Add the value to the archive without compression. If this value is written to the snapshot, the previous snapshot value will be written to the archive, without regard to compression settings. Note that if a subsequent snapshot value is written without the InsertNoCompression option, the value added with the InsertNoCompression option is still subject to compression.

NO_REPLACE = 2#

Add the value to the archive only if no value exists at the same time. If a value already exists for that time, the passed value is ignored.

REMOVE = 6#

Remove the value from the archive if a value exists at the passed time.

REPLACE = 0#

Add the value to the archive. If any values exist at the same time, will overwrite one of them and set its Substituted flag.

REPLACE_ONLY = 3#

Replace an existing value in the archive at the specified time. If no existing value is found, the passed value is ignored.

On this page

This Page