Circular Average Function

get(connection, parameters_dict)

A function that receives a dataframe of raw tag data and computes the circular mean for samples in a range, returning the results.

Parameters:

Name	Type	Description	Default
connection	object	Connection chosen by the user (Databricks SQL Connect, PYODBC SQL Connect, TURBODBC SQL Connect)	required
parameters_dict	dict	A dictionary of parameters (see Attributes table below)	required

Attributes:

Name	Type	Description
business_unit	str	Business unit
region	str	Region
asset	str	Asset
data_security_level	str	Level of data security
data_type	str	Type of the data (float, integer, double, string)
tag_names	list	List of tagname or tagnames
start_date	str	Start date (Either a utc date in the format YYYY-MM-DD or a utc datetime in the format YYYY-MM-DDTHH:MM:SS or specify the timezone offset in the format YYYY-MM-DDTHH:MM:SS+zz:zz)
end_date	str	End date (Either a utc date in the format YYYY-MM-DD or a utc datetime in the format YYYY-MM-DDTHH:MM:SS or specify the timezone offset in the format YYYY-MM-DDTHH:MM:SS+zz:zz)
time_interval_rate	str	The time interval rate (numeric input)
time_interval_unit	str	The time interval unit (second, minute, day, hour)
lower_bound	int	Lower boundary for the sample range
upper_bound	int	Upper boundary for the sample range
include_bad_data	bool	Include "Bad" data points with True or remove "Bad" data points with False
pivot	bool	Pivot the data on timestamp column with True or do not pivot the data with False
display_uom	optional bool	Display the unit of measure with True or False. Does not apply to pivoted tables. Defaults to False
limit	optional int	The number of rows to be returned
offset	optional int	The number of rows to skip before returning rows
case_insensitivity_tag_search	optional bool	Search for tags using case insensitivity with True or case sensitivity with False

Returns:

Name	Type	Description
DataFrame	DataFrame	A dataframe containing the circular averages.

Warning

Setting case_insensitivity_tag_search to True will result in a longer query time.

Note

display_uom True will not work in conjunction with pivot set to True.

Source code in src/sdk/python/rtdip_sdk/queries/time_series/circular_average.py

def get(connection: object, parameters_dict: dict) -> pd.DataFrame:
    """
    A function that receives a dataframe of raw tag data and computes the circular mean for samples in a range, returning the results.

    Args:
        connection: Connection chosen by the user (Databricks SQL Connect, PYODBC SQL Connect, TURBODBC SQL Connect)
        parameters_dict (dict): A dictionary of parameters (see Attributes table below)

    Attributes:
        business_unit (str): Business unit
        region (str): Region
        asset (str): Asset
        data_security_level (str): Level of data security
        data_type (str): Type of the data (float, integer, double, string)
        tag_names (list): List of tagname or tagnames
        start_date (str): Start date (Either a utc date in the format YYYY-MM-DD or a utc datetime in the format YYYY-MM-DDTHH:MM:SS or specify the timezone offset in the format YYYY-MM-DDTHH:MM:SS+zz:zz)
        end_date (str): End date (Either a utc date in the format YYYY-MM-DD or a utc datetime in the format YYYY-MM-DDTHH:MM:SS or specify the timezone offset in the format YYYY-MM-DDTHH:MM:SS+zz:zz)
        time_interval_rate (str): The time interval rate (numeric input)
        time_interval_unit (str): The time interval unit (second, minute, day, hour)
        lower_bound (int): Lower boundary for the sample range
        upper_bound (int): Upper boundary for the sample range
        include_bad_data (bool): Include "Bad" data points with True or remove "Bad" data points with False
        pivot (bool): Pivot the data on timestamp column with True or do not pivot the data with False
        display_uom (optional bool): Display the unit of measure with True or False. Does not apply to pivoted tables. Defaults to False
        limit (optional int): The number of rows to be returned
        offset (optional int): The number of rows to skip before returning rows
        case_insensitivity_tag_search (optional bool): Search for tags using case insensitivity with True or case sensitivity with False

    Returns:
        DataFrame: A dataframe containing the circular averages.

    !!! warning
        Setting `case_insensitivity_tag_search` to True will result in a longer query time.

    !!! Note
        `display_uom` True will not work in conjunction with `pivot` set to True.
    """
    if isinstance(parameters_dict["tag_names"], list) is False:
        raise ValueError("tag_names must be a list")

    if "pivot" in parameters_dict and "display_uom" in parameters_dict:
        if parameters_dict["pivot"] is True and parameters_dict["display_uom"] is True:
            raise ValueError("pivot True and display_uom True cannot be used together")

    try:
        query = _query_builder(parameters_dict, "circular_average")

        try:
            cursor = connection.cursor()
            cursor.execute(query)
            df = cursor.fetch_all()
            cursor.close()
            connection.close()
            return df
        except Exception as e:
            logging.exception("error returning dataframe")
            raise e

    except Exception as e:
        logging.exception("error with circular average function")
        raise e

Example

 from rtdip_sdk.authentication.azure import DefaultAuth
 from rtdip_sdk.connectors import DatabricksSQLConnection
 from rtdip_sdk.queries import TimeSeriesQueryBuilder

 auth = DefaultAuth().authenticate()
 token = auth.get_token("2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default").token
 connection = DatabricksSQLConnection("{server_hostname}", "{http_path}", token)

 data = (
     TimeSeriesQueryBuilder()
     .connect(connection)
     .source("{tablename_or_path}")
     .circular_average(
         tagname_filter=["{tag_name_1}", "{tag_name_2}"],
         start_date="2023-01-01",
         end_date="2023-01-31",
         time_interval_rate="15",
         time_interval_unit="minute",
         lower_bound="0",
         upper_bound="360",
     )
 )

 print(data)

This example is using DefaultAuth() and DatabricksSQLConnection() to authenticate and connect. You can find other ways to authenticate here. The alternative built in connection methods are either by PYODBCSQLConnection(), TURBODBCSQLConnection() or SparkConnection().

Note

See Samples Repository for full list of examples.

Note

server_hostname and http_path can be found on the SQL Warehouses Page.