Experiment

class smexperiments.experiment.Experiment(sagemaker_boto_client, **kwargs)

Bases: smexperiments._base_types.Record

An Amazon SageMaker experiment, which is a collection of related trials.

New experiments are created by calling create(). Existing experiments can be reloaded by calling load(). You can add a new trial to an Experiment by calling create_trial(). To remove an experiment and associated trials, trial components by calling delete_all().

Examples

from smexperiments import experiment

my_experiment = experiment.Experiment.create(experiment_name='AutoML')
my_trial = my_experiment.create_trial(trial_name='random-forest')

for exp in experiment.Experiment.list():
    print(exp)
for trial in my_experiment.list_trials():
    print(trial)

my_experiment.delete_all(action="--force")
Parameters:
  • experiment_name (str) – The name of the experiment. The name must be unique within an account.
  • description (str) – A description of the experiment.
  • tags (List[dict[str, str]]) – A list of tags to associate with the experiment.
experiment_name = None
description = None
tags = None
MAX_DELETE_ALL_ATTEMPTS = 3
save()

Save the state of this Experiment to SageMaker.

Returns:Update experiment API response.
Return type:dict
delete()

Delete this Experiment from SageMaker.

Deleting an Experiment requires that each Trial in the Experiment is first deleted.

Returns:Delete experiment API response.
Return type:dict
classmethod load(experiment_name, sagemaker_boto_client=None)

Load an existing experiment and return an Experiment object representing it.

Parameters:
  • experiment_name – (str): Name of the experiment
  • sagemaker_boto_client (SageMaker.Client, optional) – Boto3 client for SageMaker. If not supplied, a default boto3 client will be created and used.
Returns:

A SageMaker Experiment object
Return type:

sagemaker.experiments.experiment.Experiment
classmethod create(experiment_name=None, description=None, tags=None, sagemaker_boto_client=None)

Create a new experiment in SageMaker and return an Experiment object.

Parameters:
  • experiment_name – (str): Name of the experiment. Must be unique. Required.
  • experiment_description – (str, optional): Description of the experiment
  • sagemaker_boto_client (SageMaker.Client, optional) – Boto3 client for SageMaker. If not supplied, a default boto3 client will be created and used.
  • tags (List[dict[str, str]]) – A list of tags to associate with the experiment.
Returns:

A SageMaker Experiment object
Return type:

sagemaker.experiments.experiment.Experiment
classmethod list(created_before=None, created_after=None, sort_by=None, sort_order=None, sagemaker_boto_client=None)

List experiments. Returns experiments in the account matching the specified criteria.

Parameters:
  • created_before – (datetime.datetime, optional): Return experiments created before this instant.
  • created_after – (datetime.datetime, optional): Return experiments created after this instant.
  • sort_by (str, optional) – Which property to sort results by. One of ‘Name’, ‘CreationTime’.
  • sort_order (str, optional) – One of ‘Ascending’, or ‘Descending’.
  • sagemaker_boto_client (SageMaker.Client, optional) – Boto3 client for SageMaker. If not supplied, a default boto3 client will be used.
Returns:

An iterator

over experiment summaries matching the specified criteria.
Return type:

collections.Iterator[sagemaker.experiments.api_types.ExperimentSummary]
classmethod search(search_expression=None, sort_by=None, sort_order=None, max_results=None, sagemaker_boto_client=None)

Search experiments. Returns SearchResults in the account matching the search criteria.

Parameters:
  • search_expression – (dict, optional): A Boolean conditional statement. Resource objects must satisfy this condition to be included in search results. You must provide at least one subexpression, filter, or nested filter.
  • sort_by (str, optional) – The name of the resource property used to sort the SearchResults. The default is LastModifiedTime
  • sort_order (str, optional) – How SearchResults are ordered. Valid values are Ascending or Descending . The default is Descending .
  • max_results (int, optional) – The maximum number of results to return in a SearchResponse.
  • sagemaker_boto_client (SageMaker.Client, optional) – Boto3 client for SageMaker. If not supplied, a default boto3 client will be used.
Returns:

An iterator over search results matching the search criteria.
Return type:

collections.Iterator[SearchResult]
list_trials(created_before=None, created_after=None, sort_by=None, sort_order=None)

List trials in this experiment matching the specified criteria.

Parameters:
  • created_before (datetime.datetime, optional) – Return trials created before this instant.
  • created_after (datetime.datetime, optional) – Return trials created after this instant.
  • sort_by (str, optional) – Which property to sort results by. One of ‘Name’, ‘CreationTime’.
  • sort_order (str, optional) – One of ‘Ascending’, or ‘Descending’.
Returns:

An iterator over

trials matching the criteria.
Return type:

collections.Iterator[sagemaker.experiments.api_types.TrialSummary]
create_trial(trial_name=None, trial_name_prefix='SageMakerTrial')

Create a trial in this experiment.

Since trial names are expected to be unique in an account, trial_name_prefix can be provided instead of trial_name. In this case a unique name will be generated that begins with the specified prefix.

Parameters:
  • trial_name (str) – Name of the trial.
  • trial_name_prefix (str) – Prefix for the trial name if you want SageMaker to auto-generate the trial name.
Returns:

A SageMaker Trial object representing the

created trial.
Return type:

sagemaker.experiments.trial.Trial
delete_all(action)

Force to delete the experiment and associated trials, trial components under the experiment.

Parameters:
  • action (str) – pass in string ‘–force’ to confirm recursively delete all the experiments, trials,
  • trial components. (and) –