Skip to content

iscan

ies_pi_predict.iscan

fill_gaps 

fill_gaps(
    building_url: str,
    auth_token: str,
    input_channels: list[str],
    output_channel: str,
    prediction_channel: str,
    predict_start: datetime,
    predict_end: datetime,
    min_training_days=default_min_training_days,
    max_training_days=default_max_training_days,
    min_factor=default_min_factor,
    date_format=default_date_format,
    algorhythms=default_algorhythms,
    random_state: int | None = None,
    datasource_name=default_datasource_name,
    threshold_best=default_threshold_best,
    threshold_mid=default_threshold_mid,
) -> tuple[pd.DataFrame, str, float, float]

fill_gaps uses machine learning to fill gaps in iSCAN data.

It fetches data from iSCAN for the given input and output channels, for a period of time determined by the predict_start and predict_end. The data may be older to train the machine learning models. It uses different algorhythms to see which is the best match for the data. It uploads the predicted data to the specified channel in iSCAN using a datasource. It creates the channel and datasource if they don't exist. It creates a metadata note on the specified channel in iSCAN containing info about the prediction, such as score and rmse. It uses threshold_best and threshold_mid to gauge the quality of the prediction. It returns a Pandas Dataframe containing the data fetched from iSCAN and the predicted data, and some info about the prediction, such as score and rmse.

Parameters:

Name Type Description Default
building_url str

The iSCAN url for the building.

 required
auth_token str

The iSCAN authorization token.

 required
input_channels list[str]

A list of channel DisplayNames to serve as input.

 required
output_channel str

the output channel containing gaps to be filled.

 required
prediction_channel str

the channel where the predicted data will be saved.

 required
predict_start datetime

The start date for prediction. Note that iSCAN only supports full days as input, so the time will be set to 00:00

 required
predict_end datetime

The end datetime for prediction. Note that iSCAN only supports full days as input, so the time will be set to 23:59.

 required
min_training_days int

The minimum number of training days to consider. Defaults to config.default_min_training_days.

 default_min_training_days
max_training_days int

The maximum number of training days to consider. Defaults to config.default_max_training_days.

 default_max_training_days
min_factor float

The multiplying factor of the period of time. Defaults to config.default_min_factor.

 default_min_factor
date_format str

The date_format to use with iSCAN. Defaults to config.default_date_format.

 default_date_format
algorhythms list[ies_pi_predict]

The list of algorhythm to use.. Defaults to config.default_algorhythms.

 default_algorhythms
random_state int | None

The random state, used for testing and debugging. Defaults to None.

 None
datasource_name str

The name of the datasource. Defaults to config.default_datasource_name.

 default_datasource_name
threshold_best float

The threshold for success. Defaults to config.default_threshold_best.

 default_threshold_best
threshold_mid float

The threshold for warning. Defaults to config.default_threshold_mid.

 default_threshold_mid

Raises:

Type Description
ApiError

If something went wrong connecting to iSCAN api.

Returns:

Type Description
tuple[DataFrame, str, float, float]

tuple[pd.DataFrame, ies_pi_predict.Algorhythm, float, float]: A tuple containing: - a Pandas DataFrame with input, output, and prediction channel - the algorhythm that was used - the score (coefficient of determination) it obtained during training - the RMSE (Root mean square error) it obtained during training
Source code in src/ies_pi_predict/iscan.py 
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
def fill_gaps(building_url: str,
              auth_token: str,
              input_channels: list[str],
              output_channel: str,
              prediction_channel: str,
              predict_start: datetime, 
              predict_end: datetime,
              min_training_days = default_min_training_days,
              max_training_days = default_max_training_days,
              min_factor = default_min_factor,
              date_format = default_date_format,
              algorhythms = default_algorhythms,
              random_state: int | None = None,
              datasource_name = default_datasource_name,
              threshold_best = default_threshold_best,
              threshold_mid = default_threshold_mid,
              ) -> tuple[pd.DataFrame, str, float, float]:
    """
    fill_gaps uses machine learning to fill gaps in iSCAN data.

    It fetches data from iSCAN for the given input and output channels, for a
    period of time determined by the predict_start and predict_end. The data may be
    older to train the machine learning models.
    It uses different algorhythms to see which is the best match for the data.
    It uploads the predicted data to the specified channel in iSCAN using a datasource.
    It creates the channel and datasource if they don't exist.
    It creates a metadata note on the specified channel in iSCAN containing info
    about the prediction, such as score and rmse. It uses threshold_best and 
    threshold_mid to gauge the quality of the prediction.
    It returns a Pandas Dataframe containing the data fetched from iSCAN and the
    predicted data, and some info about the prediction, such as score and rmse.

    Args:
        building_url (str): The iSCAN url for the building.
        auth_token (str): The iSCAN authorization token.
        input_channels (list[str]): A list of channel DisplayNames to serve as input.
        output_channel (str): the output channel containing gaps to be filled.
        prediction_channel (str): the channel where the predicted data will be saved.
        predict_start (datetime): The start date for prediction.
                                  Note that iSCAN only supports full days as input,
                                  so the time will be set to 00:00
        predict_end (datetime): The end datetime for prediction. 
                                Note that iSCAN only supports full days as input, 
                                so the time will be set to 23:59.
        min_training_days (int, optional): The minimum number of training days to consider.
                                           Defaults to config.default_min_training_days.
        max_training_days (int, optional): The maximum number of training days to consider.
                                           Defaults to config.default_max_training_days.
        min_factor (float, optional): The multiplying factor of the period of time. 
                                      Defaults to config.default_min_factor.
        date_format (str, optional): The date_format to use with iSCAN. 
                                     Defaults to config.default_date_format.
        algorhythms (list[ies_pi_predict], optional): The list of algorhythm to use.. 
                                                      Defaults to config.default_algorhythms.
        random_state (int | None, optional): The random state, used for testing and debugging. 
                                             Defaults to None.
        datasource_name (str, optional): The name of the datasource. 
                                         Defaults to config.default_datasource_name.
        threshold_best (float, optional): The threshold for success. 
                                          Defaults to config.default_threshold_best.
        threshold_mid (float, optional): The threshold for warning. 
                                         Defaults to config.default_threshold_mid.

    Raises:
        scan_api.ApiError: If something went wrong connecting to iSCAN api.

    Returns:
        tuple[pd.DataFrame, 
              ies_pi_predict.Algorhythm, 
              float, float]: A tuple containing:
                             - a Pandas DataFrame with input, output, and prediction channel
                             - the algorhythm that was used
                             - the score (coefficient of determination) 
                                it obtained during training
                             - the RMSE (Root mean square error) 
                                it obtained during training
        """
    predict_start = predict_start.replace(hour=0, minute=0)
    predict_end = predict_end.replace(hour=23, minute=59)

    return _iscan_predict(building_url, auth_token, 
                          input_channels, output_channel, prediction_channel,
                          predict_start, predict_end, 
                          min_training_days = min_training_days,
                          max_training_days = max_training_days,
                          min_factor = min_factor,
                          date_format = date_format,
                          algorhythms = algorhythms,
                          random_state = random_state,
                          datasource_name = datasource_name,
                          threshold_best = threshold_best,
                          threshold_mid = threshold_mid)

short_predict 

short_predict(
    building_url: str,
    auth_token: str,
    input_channels: list[str],
    output_channel: str,
    prediction_channel: str,
    horizon_hours: int,
    min_training_days=default_min_training_days,
    max_training_days=default_max_training_days,
    min_factor=default_min_factor,
    date_format=default_date_format,
    algorhythms=default_algorhythms,
    random_state: int | None = None,
    datasource_name=default_datasource_name,
    threshold_best=default_threshold_best,
    threshold_mid=default_threshold_mid,
) -> tuple[pd.DataFrame, str, float, float]

short_predict uses machine learning to predict the next hours in iSCAN data.

It fetches data from iSCAN for the given input and output channels, for a period of time determined by min_training_days and max_training_days. The data is used to train the machine learning models. It uses different algorhythms to see which is the best match for the data. It uploads the predicted data to the specified channel in iSCAN using a datasource. It creates the channel and datasource if they don't exist. It creates a metadata note on the specified channel in iSCAN containing info about the prediction, such as score and rmse. It uses threshold_best and threshold_mid to gauge the quality of the prediction. It returns a Pandas Dataframe containing the predicted data, and some info about the prediction, such as score and rmse.

Parameters:

Name Type Description Default
building_url str

The iSCAN url for the building.

 required
auth_token str

The iSCAN authorization token.

 required
input_channels list[str]

A list of channel DisplayNames to serve as input.

 required
output_channel str

the output channel containing gaps to be filled.

 required
prediction_channel str

the channel where the predicted data will be saved.

 required
horizon_hours int

The number of hours to predict (from the current time)

 required
min_training_days int

The minimum number of training days to consider. Defaults to config.default_min_training_days.

 default_min_training_days
max_training_days int

The maximum number of training days to consider. Defaults to config.default_max_training_days.

 default_max_training_days
min_factor float

The multiplying factor of the period of time. Defaults to config.default_min_factor.

 default_min_factor
date_format str

The date_format to use with iSCAN. Defaults to config.default_date_format.

 default_date_format
algorhythms list[ies_pi_predict]

The list of algorhythm to use.. Defaults to config.default_algorhythms.

 default_algorhythms
random_state int | None

The random state, used for testing and debugging. Defaults to None.

 None
datasource_name str

The name of the datasource. Defaults to config.default_datasource_name.

 default_datasource_name
threshold_best float

The threshold for success. Defaults to config.default_threshold_best.

 default_threshold_best
threshold_mid float

The threshold for warning. Defaults to config.default_threshold_mid.

 default_threshold_mid

Raises:

Type Description
ApiError

If something went wrong connecting to iSCAN api.

Returns:

Type Description
tuple[DataFrame, str, float, float]

tuple[pd.DataFrame, ies_pi_predict.Algorhythm, float, float]: A tuple containing: - a Pandas DataFrame with and prediction channel - the algorhythm that was used - the score (coefficient of determination) it obtained during training - the RMSE (Root mean square error) it obtained during training
Source code in src/ies_pi_predict/iscan.py 
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
def short_predict(building_url: str,
              auth_token: str,
              input_channels: list[str],
              output_channel: str,
              prediction_channel: str,
              horizon_hours: int, 
              min_training_days = default_min_training_days,
              max_training_days = default_max_training_days,
              min_factor = default_min_factor,
              date_format = default_date_format,
              algorhythms = default_algorhythms,
              random_state: int | None = None,
              datasource_name = default_datasource_name,
              threshold_best = default_threshold_best,
              threshold_mid = default_threshold_mid,
              ) -> tuple[pd.DataFrame, str, float, float]:
    """
    short_predict uses machine learning to predict the next hours in iSCAN data.

    It fetches data from iSCAN for the given input and output channels, for a
    period of time determined by min_training_days and max_training_days. 
    The data is used to train the machine learning models.
    It uses different algorhythms to see which is the best match for the data.
    It uploads the predicted data to the specified channel in iSCAN using a datasource.
    It creates the channel and datasource if they don't exist.
    It creates a metadata note on the specified channel in iSCAN containing info
    about the prediction, such as score and rmse. It uses threshold_best and 
    threshold_mid to gauge the quality of the prediction.
    It returns a Pandas Dataframe containing the predicted data, and some info 
    about the prediction, such as score and rmse.

    Args:
        building_url (str): The iSCAN url for the building.
        auth_token (str): The iSCAN authorization token.
        input_channels (list[str]): A list of channel DisplayNames to serve as input.
        output_channel (str): the output channel containing gaps to be filled.
        prediction_channel (str): the channel where the predicted data will be saved.
        horizon_hours (int): The number of hours to predict (from the current time)
        min_training_days (int, optional): The minimum number of training days to consider.
                                           Defaults to config.default_min_training_days.
        max_training_days (int, optional): The maximum number of training days to consider.
                                           Defaults to config.default_max_training_days.
        min_factor (float, optional): The multiplying factor of the period of time. 
                                      Defaults to config.default_min_factor.
        date_format (str, optional): The date_format to use with iSCAN. 
                                     Defaults to config.default_date_format.
        algorhythms (list[ies_pi_predict], optional): The list of algorhythm to use.. 
                                                      Defaults to config.default_algorhythms.
        random_state (int | None, optional): The random state, used for testing and debugging. 
                                             Defaults to None.
        datasource_name (str, optional): The name of the datasource. 
                                         Defaults to config.default_datasource_name.
        threshold_best (float, optional): The threshold for success. 
                                          Defaults to config.default_threshold_best.
        threshold_mid (float, optional): The threshold for warning. 
                                         Defaults to config.default_threshold_mid.

    Raises:
        scan_api.ApiError: If something went wrong connecting to iSCAN api.

    Returns:
        tuple[pd.DataFrame, 
              ies_pi_predict.Algorhythm, 
              float, float]: A tuple containing:
                             - a Pandas DataFrame with and prediction channel
                             - the algorhythm that was used
                             - the score (coefficient of determination) 
                                it obtained during training
                             - the RMSE (Root mean square error) 
                                it obtained during training
        """
    predict_start = datetime.now()
    predict_end = predict_start + timedelta(hours=horizon_hours)

    df, algo, score, rmse = _iscan_predict(building_url, auth_token, 
                          input_channels, output_channel, prediction_channel,
                          predict_start, predict_end, 
                          min_training_days = min_training_days,
                          max_training_days = max_training_days,
                          min_factor = min_factor,
                          date_format = date_format,
                          algorhythms = algorhythms,
                          random_state = random_state,
                          datasource_name = datasource_name,
                          threshold_best = threshold_best,
                          threshold_mid = threshold_mid)
    return df.filter([prediction_channel]), algo, score, rmse