Skip to content

Model

airt.client.Model (ProgressStatus)

A class to query the status of the model training, evaluation, and prediction on the remote server.

A Model class is instantiated automatically when the DataSource.train method of the DataSource class is called. Currently, it is the only way to instantiate the Model class.

The model is trained on the connected data and tries to predict a specific event in the future. For the model training and prediction, we assume the input data includes the following:

  • a column identifying a client client_column (person, car, business, etc.),

  • a column specifying a type of event we will try to predict target_column (buy, checkout, etc.),

  • a timestamp column specifying the time of an occurred event.

Along with the above mandatory fields, each row in the data might have additional columns of int, category, float, or datetime type and they will be used to make predictions more accurate.

Finally, we need to know how much ahead we wish to make predictions for. That lead time varies widely from application to application and can be in minutes for a webshop or even several weeks for a banking product such as a loan.

As always, the model training and prediction will happen asynchronously and can take a few hours based on the size of your dataset.

The training status can either be viewed interactively by calling the progress_bar method or non-interactively by calling the is_ready method on the model instance which returns a boolean representing the training completion status.

__init__(self, model_id) special

Constructs a new Model instance

Warning

Do not construct this object directly by calling the constructor, please use DataSource.train() function instead.

Parameters:

Name Type Description Default
model_id int

ID of the model in the airt service

required
Source code in airt/client.py
def __init__(self, model_id: int):
    """Constructs a new `Model` instance

    Warning:
        Do not construct this object directly by calling the constructor, please use
        `DataSource.train()` function instead.

    Args:
        model_id: ID of the model in the airt service
    """
    self.model_id = model_id
    ProgressStatus.__init__(self, relative_url=f"/model/{self.model_id}")

delete(id) staticmethod

Delete a model from airt service

Parameters:

Name Type Description Default
id int

The model id in airt service.

required

Returns:

Type Description
DataFrame

A pandas DataFrame encapsulating the details of the deleted model id.

Exceptions:

Type Description
ConnectionError

If the server address is invalid or not reachable.

An example to delete a model (id=1) from airt service:

Model.delete(id=1)
Source code in airt/client.py
@staticmethod
def delete(id: int) -> pd.DataFrame:
    """Delete a model from airt service

    Args:
        id: The model id in airt service.

    Returns:
        A pandas DataFrame encapsulating the details of the deleted model id.

    Raises:
        ConnectionError: If the server address is invalid or not reachable.

    An example to delete a model (id=1) from airt service:

    ```python
    Model.delete(id=1)
    ```
    """

    models = Client.delete_data(relative_url=f"/model/{id}")

    columns = Model._get_columns()

    models_df = pd.DataFrame(models, index=[0])[columns]

    return add_ready_column(models_df)

details(id) staticmethod

Return details of a model

Parameters:

Name Type Description Default
id int

The id of the model in the airt service.

required

Returns:

Type Description
DataFrame

A pandas dataframe with the details of the model.

Exceptions:

Type Description
ConnectionError

If the server address is invalid or not reachable.

An example to get details of a model (id=1) from airt service:

Model.details(id=1)
Source code in airt/client.py
@staticmethod
def details(id: int) -> pd.DataFrame:
    """Return details of a model

    Args:
        id: The id of the model in the airt service.

    Returns:
        A pandas dataframe with the details of the model.

    Raises:
        ConnectionError: If the server address is invalid or not reachable.

    An example to get details of a model (id=1) from airt service:

    ```python
    Model.details(id=1)
    ```
    """

    details = Client.get_data(relative_url=f"/model/{id}")

    additional_cols = [
        "datasource_id",
        "user_id",
        "client_column",
        "target_column",
        "target",
        "predict_after",
        "timestamp_column",
        "error",
        "disabled",
    ]

    columns = Model._get_columns() + additional_cols

    details_df = pd.DataFrame(details, index=[0])[columns]

    return add_ready_column(details_df)

evaluate(self)

A function to evaluate the performance of the trained model.

This function returns the performance metrics like accuracy, precision, and recall. Currently, the function returns only the above-mentioned metrics and we plan to add more performance metrics in the future.

Returns:

Type Description
DataFrame

A pandas Series that has the performance metrics of the trained model.

Exceptions:

Type Description
ValueError

If the input parameters to the API are invalid.

ConnectionError

If the server address is invalid or not reachable.

Source code in airt/client.py
@patch
def evaluate(self: Model) -> pd.DataFrame:
    """A function to evaluate the performance of the trained model.

    This function returns the performance metrics like accuracy, precision, and recall. Currently,
    the function returns only the above-mentioned metrics and we plan to add more performance metrics in the future.

    Returns:
        A pandas Series that has the performance metrics of the trained model.

    Raises:
        ValueError: If the input parameters to the API are invalid.
        ConnectionError: If the server address is invalid or not reachable.
    """
    model_evaluate = Client.get_data(relative_url=f"/model/{self.model_id}/evaluate")
    return pd.DataFrame(dict(model_evaluate), index=[0]).T.rename(columns={0: "eval"})

is_ready(self) inherited

A function to check if the method's progress is completed.

Returns:

Type Description
bool

True if the progress if completed, else False.

Source code in airt/client.py
def is_ready(self) -> bool:
    """A function to check if the method's progress is completed.

    Returns:
        True if the progress if completed, else False.
    """
    response = Client.get_data(relative_url=self.relative_url)
    return response["completed_steps"] == response["total_steps"]

ls(offset=0, limit=100, disabled=False, completed=False) staticmethod

Display the list of available models in airt service.

Parameters:

Name Type Description Default
offset int

The number of rows to offset at the beginning of the models list from the server.If None, then the default value 0 will be used.

0
limit int

The maximum number of rows to return from the server. If None, then the default value 100 will be used.

100
disabled bool

If set to True, then only the deleted models will be displayed. Else, the default value False will be used to display only the list of active models.

False
completed bool

If set to True, then only the models that are successfully trained in airt server will be displayed. Else, the default value False will be used to display all the models including the ones that are yet to finish training.

False

Returns:

Type Description
DataFrame

A pandas dataframe with the list of available models.

Exceptions:

Type Description
ConnectionError

If the server address is invalid or not reachable.

An example to list the available models:

Model.ls()
Source code in airt/client.py
@staticmethod
def ls(
    offset: int = 0,
    limit: int = 100,
    disabled: bool = False,
    completed: bool = False,
) -> pd.DataFrame:
    """Display the list of available models in airt service.

    Args:
        offset: The number of rows to offset at the beginning of the models
            list from the server.If **None**, then the default value **0** will be used.
        limit: The maximum number of rows to return from the server. If **None**,
            then the default value **100** will be used.
        disabled: If set to **True**, then only the deleted models will be displayed.
            Else, the default value **False** will be used to display only the list
            of active models.
        completed: If set to **True**, then only the models that are successfully trained
            in airt server will be displayed. Else, the default value **False** will be used
            to display all the models including the ones that are yet to finish training.

    Returns:
        A pandas dataframe with the list of available models.

    Raises:
        ConnectionError: If the server address is invalid or not reachable.

    An example to list the available models:

    ```python
    Model.ls()
    ```
    """
    models = Client.get_data(
        relative_url=f"/model/?disabled={disabled}&completed={completed}&offset={offset}&limit={limit}"
    )

    columns = Model._get_columns()

    models_df = generate_df(models, columns)

    return add_ready_column(models_df)

predict(self, data_id=0)

A function that uses the trained model and makes predictions.

As always, this function is asynchronous and can take a few hours based on the size of your dataset. The status of the model prediction can be viewed interactively by calling the progress_bar method available on the returned object. For more information, please check the documentation of DataSource

Parameters:

Name Type Description Default
data_id Optional[int]

The data id for running the predictions. If the value is not passed then the data id used for training will be used for prediction aswell.

0

Returns:

Type Description
Prediction

An instance of the Prediction class. For more information on the methods that are available in the returned object, please check the documentation of the Prediction class

Exceptions:

Type Description
ValueError

If the input parameters to the API are invalid.

ConnectionError

If the server address is invalid or not reachable.

Source code in airt/client.py
@patch
def predict(self: Model, data_id: Optional[int] = 0) -> Prediction:
    """A function that uses the trained model and makes predictions.

    As always, this function is asynchronous and can take a few hours based on the size of your dataset. The status of
    the model prediction can be viewed interactively by calling the `progress_bar` method available on the returned object.
    For more information, please check the documentation of `DataSource`

    Args:
        data_id: The data id for running the predictions. If the value is not passed then the data id used for
            training will be used for prediction aswell.
    Returns:
        An instance of the `Prediction` class. For more information on the methods that are available in
        the returned object, please check the documentation of the `Prediction` class

    Raises:
        ValueError: If the input parameters to the API are invalid.
        ConnectionError: If the server address is invalid or not reachable.
    """

    request_body = dict(data_id=data_id) if data_id else None

    response = Client.post_data(
        relative_url=f"/model/{self.model_id}/predict", data=request_body
    )

    return Prediction(
        prediction_id=response["id"], datasource_id=response["datasource_id"]
    )

progress_bar(self, sleep_for=5, timeout=0) inherited

Blocks execution while waiting for remote action to be completed and displays a progress bar indicating the completion status.

Parameters:

Name Type Description Default
sleep_for Union[int, float]

The time interval in seconds between successive API calls to ping the server for fetching the completed steps.

5
timeout int

The maximum time allowed in seconds for the asynchronous call to complete the process. If the timeout exceeds and the process is yet to complete, then the progress_bar will be terminated.

0

Exceptions:

Type Description
TimeoutError

in case of timeout

Source code in airt/client.py
def progress_bar(self, sleep_for: Union[int, float] = 5, timeout: int = 0):
    """Blocks execution while waiting for remote action to be completed and displays a progress bar indicating the completion status.

    Args:
        sleep_for: The time interval in seconds between successive API calls to ping the server for fetching the completed steps.
        timeout: The maximum time allowed in seconds for the asynchronous call to complete the process. If the timeout
            exceeds and the process is yet to complete, then the progress_bar will be terminated.

    Raises:
        TimeoutError: in case of timeout

    """
    total_steps = Client.get_data(relative_url=self.relative_url)["total_steps"]
    with tqdm(total=total_steps) as pbar:
        started_at = datetime.now()
        while True:
            if (0 < timeout) and (datetime.now() - started_at) > timedelta(
                seconds=timeout
            ):
                raise TimeoutError()

            response = Client.get_data(relative_url=self.relative_url)
            completed_steps = response["completed_steps"]

            pbar.update(completed_steps)

            if completed_steps == total_steps:
                break

            sleep(sleep_for)

wait(self, sleep_for=1, timeout=0) inherited

Blocks execution while waiting for remote action to be completed.

Parameters:

Name Type Description Default
sleep_for Union[int, float]

The time interval in seconds between successive API calls to ping the server for fetching the completed steps.

1
timeout int

The maximum time allowed in seconds for the asynchronous call to complete the process. If the timeout exceeds and the process is yet to complete, then the progress_bar will be terminated.

0

Exceptions:

Type Description
TimeoutError

in case of timeout

Source code in airt/client.py
@patch
def wait(self: ProgressStatus, sleep_for: Union[int, float] = 1, timeout: int = 0):
    """Blocks execution while waiting for remote action to be completed.

    Args:
        sleep_for: The time interval in seconds between successive API calls to ping the server for fetching the completed steps.
        timeout: The maximum time allowed in seconds for the asynchronous call to complete the process. If the timeout
            exceeds and the process is yet to complete, then the progress_bar will be terminated.

    Raises:
        TimeoutError: in case of timeout
    """
    started_at = datetime.now()
    while True:
        if (0 < timeout) and (datetime.now() - started_at) > timedelta(seconds=timeout):
            raise TimeoutError()

        if self.is_ready():
            return

        sleep(sleep_for)
Back to top