Trial

class smexperiments.trial.Trial(sagemaker_boto_client, **kwargs)

Bases: smexperiments._base_types.Record

An execution of a data-science workflow with an experiment.

Consists of a list of trial component objects, which document individual activities within the workflow.

Examples

from smexperiments import trial, experiment, tracker

my_experiment = experiment.Experiment.create(experiment_name='AutoML')
my_trial = trial.Trial.create('AutoML')

# use `with` statement to ensure `my_tracker.close()` is called
with tracker.Tracker.create() as my_tracker:
    # log hyper parameter of learning rate
    my_tracker.log_parameter('learning_rate', 0.01)

    # associate the trial component with the trial
    my_trial.add_trial_component(my_tracker)

# list trial components within a trial
for trial_component in my_trial.list_trial_components():
    print(trial_component)

# cleanup trial
my_trial.remove_trial_component(my_tracker)
my_trial.delete()
Parameters:
  • trial_name (str) – The name of the trial.
  • experiment_name (str) – The name of the trial’s experiment.
  • tags (List[dict[str, str]]) – A list of tags to associate with the trial.
trial_name = None
experiment_name = None
tags = None
MAX_DELETE_ALL_ATTEMPTS = 3
save()

Save the state of this Trial to SageMaker.

Returns:Update trial response.
Return type:dict
delete()

Delete this Trial from SageMaker.

Requires that this Trial contains no TrialComponents. Individual TrialComponents can be removed by calling remove_trial_component().

Returns:
dict: Delete trial response.
classmethod load(trial_name, sagemaker_boto_client=None)

Load an existing trial and return a Trial object.

Parameters:
  • trial_name – (str): Name of the Trial.
  • 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 Trial object
Return type:

smexperiments.trial.Trial
classmethod create(experiment_name, trial_name=None, sagemaker_boto_client=None, trial_components=None, tags=None)

Create a new trial and return a Trial object.

Parameters:
  • experiment_name – (str): Name of the experiment to create this trial in.
  • trial_name – (str, optional): Name of the Trial. If not specified, an auto-generated name will be used.
  • sagemaker_boto_client (SageMaker.Client, optional) – Boto3 client for SageMaker. If not supplied, a default boto3 client will be created and used.
  • trial_components (list) – A list of trial component names, trial components, or trial component trackers.
  • tags (List[dict[str, str]]) – A list of tags to associate with the trial.
Returns:

A SageMaker Trial object
Return type:

smexperiments.trial.Trial
classmethod list(experiment_name=None, trial_component_name=None, created_before=None, created_after=None, sort_by=None, sort_order=None, sagemaker_boto_client=None)

List all trials matching the specified criteria.

Parameters:
  • experiment_name (str, optional) – Name of the experiment. If specified, only trials in the experiment will be returned.
  • trial_component_name (str, optional) – Name of the trial component. If specified, only trials with this trial component name will be returned.
  • 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’.
  • sagemaker_boto_client (SageMaker.Client, optional) – Boto3 client for SageMaker. If not supplied, a default boto3 client will be created and used.
Returns:

An iterator over trials

matching the specified criteria.
Return type:

collections.Iterator[smexperiments.trial.TrialSummary]
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]
add_trial_component(tc)

Add the specified trial component to this Trial.

A trial component may belong to many trials and a trial may have many trial components.

Parameters:
  • tc (str or Tracker or TrialComponent or TrialComponentSummary) – The trial component to
  • Can be one of a Tracker instance, a TrialComponent instance, or a string containing (add.) –
  • name of the trial component to add. (the) –
remove_trial_component(tc)

Remove the specified trial component from this trial.

Parameters:
  • tc (str or Tracker or TrialComponent or TrialComponentSummary) – The trial component to
  • Can be one of a Tracker instance, a TrialComponent instance, or a string (remove.) –
  • the name of the trial component to remove. (containing) –
list_trial_components(created_before=None, created_after=None, sort_by=None, sort_order=None, max_results=None, next_token=None)

List trial components in this trial 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’.
  • max_results (int, optional) – maximum number of trial components to retrieve
  • next_token (str, optional) – token for next page of results
Returns:

An iterator over

trials matching the criteria.
Return type:

collections.Iterator[smexperiments.api_types.TrialComponentSummary]
delete_all(action)

Force to delete the trial and associated trial components under.

Parameters:action (str) – pass in string ‘–force’ to confirm delete the trial and all associated trial components.