Documentation

# kortical.api.advanced.model

# Models

Models are represented with the following json format:

model_json = {
   "id":35,
   "name": "house_prices",
   "prefix": "houseprices",
   "score_type": "mean_absolute_error",
   "status": "Running",
   "train_worker_group": "default",
   "active": "true",
   "default_component_version": 3,
   "default_component_version_id": 2664,
   "created": {
      "__class__":"datetime",
      "__value__":"2023-04-27T09:46:17.365782Z"
   },
   "score": 4.297260019911306,
   "required_train_kore_count": 0,
   "default_train_kore_count": 3,
   "training_state": "Idle",
   "is_explaining": "false",
   "training_started_by": "None",
   "train_worker_group_name": "default",
   "created_by": "owen.saldanha@kortical.com"
}

#

# list_models

No inputs

Returns

  • [model_json, ...] - A list of dictionaries, representing each model.
from kortical.api.advanced import model

models = model.list_models()

#

# select_model

This function selects an model. This is required before operations that only make sense when executed on an model (e.g. model publishing).

Inputs

  • model_name_or_id - The name or ID of the model to select.

Returns

  • None
from kortical.api.advanced import model

model.select_model('titanic')

#

# create_model

Inputs

  • model_name - The name of your new model.

Returns

  • model_json - A dictionary containing information about the created model.
from kortical.api.advanced import model

model_json = model.create_model('titanic')

#

# get_model

Inputs

  • model_name_or_id - The name or ID of the model you want.

Returns

  • model_json - A dictionary containing information about the model.
from kortical.api.advanced import model

model_json = model.get_model('house_prices')

#

# delete_unpublished_versions

This function deletes all unpublished versions for the specified model.

Inputs

  • model_name_or_id - The name or ID of the model.

Returns

  • None
from kortical.api.advanced import model

model.delete_unpublished_versions('titanic')

#

# activate_model

This function activates a model.

Inputs

  • model_name_or_id - The name or ID of the model you want.

Returns

  • None
from kortical.api.advanced import model

model.activate_model(15)

#

# deactivate_model

This function deactivates a model. Since there is a limit on the number of active models, use this to temporarily disable existing models so you can create new ones.

Inputs

  • model_name_or_id - The name or ID of the model you want.

Returns

  • None
from kortical.api.advanced import model

model.deactivate_model(15)

#

# delete_model

This function deletes a model and its versions; this can only be done if the model is not deployed to any Kortical projects.

Inputs

  • model_name_or_id - The name or ID of the model to delete.

Returns

  • None
from kortical.api.advanced import model

model.delete_model('titanic')

# Model versions

Model versions are represented with the following json format:

model_version_json = {
   "id": 2681,
   "name": "house_prices",
   "type": "model",
   "created": {
      "__class__": "datetime",
      "__value__": "2023-04-27T10:06:20.563373Z"
   },
   "component_id": 35,
   "version": "None",
   "model_type": "lightgbm",
   "score": 1.2487746743559001e+42,
   "score_type": "mean_absolute_error",
   "_is_max": "false",
   "created_by": "owen.saldanha@kortical.com"
}

#

# list_model_versions

Inputs

  • model_name_or_id - The name or ID of the model for which you want to list versions.
  • include_created_by (= False) - As part of the model version json, returns the email of the user that created it.

Returns

  • [model_version_json, ...] - A list of dictionaries, representing the versions of the specified model.
from kortical.api.advanced import model

model.list_model_versions('house_prices')

#

# get_model_version

Inputs

  • model_name_or_id - The name or ID of the model you want.
  • version_name_or_id - The name or ID of the model version you want.

Returns

  • model_version_json - A dictionary containing information about the model version.
from kortical.api.advanced import model

model.get_model_version('house_prices', 'v2')

#

# set_default_model_version

Inputs

  • model_name_or_id - The name or ID of the model you want.
  • version_name_or_id - The name or ID of the model version you want to set as a default.

Returns

  • model_version_json - A dictionary containing information about the model version.
from kortical.api.advanced import model

model.set_default_model_version('house_prices', 2605)

#

# delete_model_version

Inputs

  • model_name_or_id - The name or ID of the model you want.
  • version_name_or_id - The name or ID of the model version you want to delete.

Returns

  • response - A dictionary indicated a successful response, {'result': 'success'}.
from kortical.api.advanced import model

model.delete_model_version('house_prices', 18)

# Training models

# train_start

This function will start a training run on the specified model.

Inputs

  • model_name_or_id - The name or ID of the model for which you want to start training.
  • data_id - The ID of the dataset to use for the training run.
  • code - The model code to use for the training run.

Returns

  • train_id - The ID of the training run in the platform.
from kortical.api.advanced import model

model_code = """
- ml_solution:
  - data_set:
    - target_column: Survived
    - problem_type: classification
  - features:
    - categorical:
      - Sex
      - Embarked
      etc...
"""
train_id = model.train_start('titanic', data_id=4, code=model_code)

# train_stop

This function stops any on-going training for the specified model.

Inputs

  • model_name_or_id - The name or ID of the model for which you want to stop training.

Returns

  • None
from kortical.api.advanced import model

model.train_stop('titanic')

# train_status

This function returns the status of an in-progress training run for the specified model.

Inputs

  • model_name_or_id - The name or ID of the model for which you want the status.
  • number_of_models (= 10) - The number of model versions to return information for.

Returns

  • dict - A dictionary containing information about the training run on the specified model.
from kortical.api.advanced import model

train_info = model.train_status(model_name_or_id=2)

If training is ongoing, the dictionary contains the top n number of models which is specified with the number_of_models parameter. This is an example of the output dictionary.

{
  'result': 'success',
  'is_training': True,  # Indicates that this model is training
  'train_started': {  # model trained timestamp
    '__class__': 'datetime',
    '__value__': '2021-05-06T13:20:01.722930Z'
  },
  'num_models_trained': 23,  # Number of models trained so far.
  'num_train_workers': 3,  # Number of train workers in use by this model.
  'evaluation_metric': 'area_under_roc_curve',  # The evaluation metric being used for this train.
  'number_of_models_since_best_score': 17,  # Number of models since the last best score.
  'top_models': [  # This list contains the top models, ordered by the evaluation metric.
    {              # There are various keys and metrics associated with the model.
      'id': 147,
      'description': None,
      'data_id': 16,
      'score': 0.8690238826643719,
      'error': 0.02340396430411129,
      'model_type': 'lightgbm',
      'train_mean_squared_error': 0.17620650953984288,
      'train_mean_absolute_error': 0.17620650953984288,
      'train_r2': 0.2549611734253666,
      'train_explained_variance': 0.26672631791987556,
      'train_accuracy': 0.8237934904601572,
      'train_log_loss': 0.4126270912123344,
      'train_f1_score': 0.7535321821036107,
      'train_area_under_roc_curve': 0.8933946889080625,
      'train_mean_average_precision': 0.8933946889080625,
      'validation_mean_squared_error': 0.1904488681407277,
      'validation_mean_absolute_error': 0.1904488681407277,
      'validation_r2': 0.19461191266262304,
      'validation_explained_variance': 0.20923839672244338,
      'validation_accuracy': 0.8095511318592723,
      'validation_log_loss': 0.4499087551959913,
      'validation_f1_score': 0.734011352224425,
      'validation_area_under_roc_curve': 0.8578696460574644,
      'validation_mean_average_precision': 0.8578696460574644,
      'test_mean_squared_error': 0.1807909604519774,
      'test_mean_absolute_error': 0.1807909604519774,
      'test_r2': 0.2358337830545063,
      'test_explained_variance': 0.24446842957366444,
      'test_accuracy': 0.8192090395480226,
      'test_log_loss': 0.4283579495494196,
      'test_f1_score': 0.7500000000000001,
      'test_area_under_roc_curve': 0.8812736103615757,
      'test_mean_average_precision': 0.8812736103615757,
      'gray_mean_squared_error': 0.18571318947727697,
      'gray_mean_absolute_error': 0.18571318947727697,
      'gray_r2': 0.21352360525995945,
      'gray_explained_variance': 0.2256122579333558,
      'gray_accuracy': 0.814286810522723,
      'gray_log_loss': 0.43959778959672174,
      'gray_f1_score': 0.7417500392545212,
      'gray_area_under_roc_curve': 0.8690238826643719,
      'gray_mean_average_precision': 0.8690238826643719,
      'hide': False,
      'published': None,
      'deployment_id': None,
    }
  ]
}

Note

The metrics that start with gray_ e.g. gray_mean_squared_error, gray_accuracy, are actually the best 'blended scores' that the platform has calculated for this model. These scores take into account the level of divergence between the test and validation sets. These are the scores that are displayed in the platform UI.

# wait_for_training

This function waits for a training run to finish based on two stopping conditions:

  • The number of models produced where there is no further improvement.
  • The time elapsed.

Inputs

  • model_name_or_id - The name or ID of the model where a training run is taking place.
  • max_models_with_no_score_change (= 50) - Stopping criterion 1; if the model score does not improve for a specified number of iterations, training is stopped.
  • max_minutes_to_train (= None) - Stopping criterion 2; if the training time has exceeded a specific duration, training is stopped.
  • target_score (= None) - Stopping criterion 3; if a model version with the desired score is found, training is stopped.

Returns

  • dict - A dictionary containing information about the training run on the specified model.
from kortical.api.advanced import model

train_info = model.wait_for_training('titanic', max_models_with_no_score_change=20, max_minutes_to_train=60)

The returned dictionary has an identical structure to the output of model.train_status.

# set_num_train_workers

This function updates the number of train workers the model's training run should have.

Inputs

  • model_name_or_id - The name or ID of the model where the number of workers should be modified.
  • number_of_train_workers - What the new number of workers should be.

Returns

  • None
from kortical.api.advanced import model

# Reduce train workers from the typical value of 3
model.set_num_train_workers('titanic', number_of_train_workers=2)

← kortical.api.advanced.app →