PIconnect.Asset module#

Mirror of the OSISoft.AF.Asset namespace.

class PIconnect.Asset.AFAttribute(attribute: AFAttribute)#

Bases: DataContainer

Representation of an AF attribute.

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 children: dict[str, Self]#

Return a dictionary of the direct child attributes of the current attribute.

property current_value: Any#

Return the current value of the attribute.

property data_reference: AFDataReference#

Return the data reference of the attribute.

property description: str#

Return the description of the attribute.

property element: AFBaseElement#

Return the element to which the attribute belongs.

property name: str#

Return the name of the attribute.

property parent: Self | None#

Return the parent attribute of the current attribute, or None if it has none.

property path: str#

Return the path of the attribute.

property stepped_data: bool#

Return True if the attribute is a stepped data type.

property units_of_measurement: str#

Return the units of measurement of the attribute.

class PIconnect.Asset.AFAttributeList(elements: MutableSequence[NamedItemType])#

Bases: DataContainerCollection[AFAttribute]

A list of AF attributes.

append(value: NamedItemType) → None#

Append a new item to the end of the list.

clear() → None -- remove all items from S#
count(value) → integer -- return number of occurrences of value#
extend(values: Iterable[NamedItemType]) → None#

Extend the list with a new iterable of items.

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.

index(value[, start[, stop]]) → integer -- return first index of value.#

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index: int, value: NamedItemType) → None#

Insert a new item at the given index.

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

pop([index]) → item -- remove and return item at index (default last).#

Raise IndexError if list is empty or index is out of range.

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

remove(value)#

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()#

S.reverse() – reverse IN PLACE

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.

class PIconnect.Asset.AFDataReference(data_reference: AFDataReference)#

Bases: object

Reference to the data source of an AF attribute.

property attribute: AFAttribute#

Return the attribute associated with the data reference.

data_reference: AFDataReference#
property name: str#

Return the name of the data reference.

property pi_point: PIPoint | None#

Return the PI Point associated with the data reference, if any.

class PIconnect.Asset.AFElement(element: ElementType)#

Bases: AFBaseElement[AFElement]

Container for PI AF elements in the database.

descendant(path: str) → Self#

Return a descendant of the current element from an exact path.

property attributes: dict[str, AFAttribute]#

Return a dictionary of the attributes of the current element.

property categories: AFCategories#

Return the categories of the current element.

property children: dict[str, Self]#

Return a dictionary of the direct child elements of the current element.

property description: str#

Return the description of the current element.

property name: str#

Return the name of the current element.

property parent: Self | None#

Return the parent element of the current element, or None if it has none.

property path: str#

Return the path of the current element.

version = '0.1.0'#
class PIconnect.Asset.AFElementList(elements: MutableSequence[NamedItemType])#

Bases: NamedItemList[AFElement]

Container for a list of PIAFElement objects.

append(value: NamedItemType) → None#

Append a new item to the end of the list.

clear() → None -- remove all items from S#
count(value) → integer -- return number of occurrences of value#
extend(values: Iterable[NamedItemType]) → None#

Extend the list with a new iterable of items.

index(value[, start[, stop]]) → integer -- return first index of value.#

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index: int, value: NamedItemType) → None#

Insert a new item at the given index.

pop([index]) → item -- remove and return item at index (default last).#

Raise IndexError if list is empty or index is out of range.

remove(value)#

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()#

S.reverse() – reverse IN PLACE

On this page

This Page