Experiments Client Methods#
This page lists all relevant methods for Dioptra Experiments that are available via the Python Client.
Contents
Requirements#
Install Dioptra - an installation and deployment of Dioptra must be available
Set Up the Python Client - the Python client must be configured and initialized
Experiments - CRUD Methods#
After importing and initializing the client, these methods for creating, reading updating and deleting (CRUD) experiments can be executed via client.experiments.METHOD_NAME().
Create Experiment#
- ExperimentsCollectionClient.create(group_id: int, name: str, description: str | None = None, entrypoints: list[int] | None = None) dioptra.client.experiments.T[source]#
Creates an experiment.
- Parameters
group_id – The id of the group that will own the experiment.
name – The name of the new experiment.
description – The description of the new experiment. Optional, defaults to None.
entrypoints – A list of entrypoint ids to associate with the new experiment. Optional, defaults to None.
- Returns
The response from the Dioptra API.
Get Experiments#
- ExperimentsCollectionClient.get(group_id: int | None = None, index: int = 0, page_length: int = 10, sort_by: str | None = None, descending: bool | None = None, search: str | None = None) dioptra.client.experiments.T[source]#
Get a list of experiments.
- Parameters
group_id – The group id the experiments belong to. If None, return experiments from all groups that the user has access to. Optional, defaults to None.
index – The paging index. Optional, defaults to 0.
page_length – The maximum number of experiments to return in the paged response. Optional, defaults to 10.
sort_by – The field to use to sort the returned list. Optional, defaults to None.
descending – Sort the returned list in descending order. Optional, defaults to None.
search – Search for experiments using the Dioptra API’s query language. Optional, defaults to None.
- Returns
The response from the Dioptra API.
Modify Experiment#
- ExperimentsCollectionClient.modify_by_id(experiment_id: str | int, name: str, description: str | None, entrypoints: list[int] | None) dioptra.client.experiments.T[source]#
Modify the experiment matching the provided id.
- Parameters
experiment_id – The experiment id, an integer.
name – The new name of the experiment.
description – The new description of the experiment. To remove the description, pass None.
entrypoints – A new list of entrypoint ids to associate with the experiment. To remove all associated entrypoints, pass an empty list or None.
- Returns
The response from the Dioptra API.
Delete Experiment#
Experiments - Other Methods#
Get Metrics for Jobs in Experiment#
- ExperimentsCollectionClient.get_metrics_by_id(experiment_id: str | int, index: int = 0, page_length: int = 10, sort_by: str | None = None, descending: bool | None = None, search: str | None = None) dioptra.client.experiments.T[source]#
Get the metrics for the jobs in this experiment.
Each returned metric value is either a float or a string representing the special values of NaN, Infinity, or -Infinity. NaN values are represented as the string “nan”, positive infinity as “inf”, and negative infinity as “-inf”. To convert these string values back to their corresponding float representations in Python, wrap the returned value with
float().
- Parameters
experiment_id – The experiment id, an integer.
index – The paging index. Optional, defaults to 0.
page_length – The maximum number of experiments to return in the paged response. Optional, defaults to 10.
sort_by – The field to use to sort the returned list. Optional, defaults to None.
descending – Sort the returned list in descending order. Optional, defaults to None.
search – Search for jobs using the Dioptra API’s query language. Optional, defaults to None.
- Returns
The response from the Dioptra API.
Entrypoint Attachment - Methods#
These methods exist within the class ExperimentEntrypointsSubCollectionClient, and can are accessed via the entrypoints property of the Experiment Client (which points to ExperimentEntrypointsSubCollectionClient)
Example - Attach Entrypoints to Experiment
Attach Entrypoints to Experiment
client.experiments.entrypoints.create(experiment_id=1, entrypoint_ids=[2,3])
Add Entrypoint to Experiment#
- ExperimentEntrypointsSubCollectionClient.create(experiment_id: str | int, entrypoint_ids: list[int]) dioptra.client.experiments.T[source]#
Adds one or more entrypoints to the experiment.
If an entrypoint id matches an entrypoint that is already attached to the experiment, then the experiment will update the entrypoint to the latest version.
- Parameters
experiment_id – The experiment id, an integer.
entrypoint_ids – A list of entrypoint ids that will be registered to the experiment.
- Returns
The response from the Dioptra API.
Get Entrypoints for Experiment#
Replace Attached Entrypoints#
- ExperimentEntrypointsSubCollectionClient.modify_by_id(experiment_id: str | int, entrypoint_ids: list[int]) dioptra.client.experiments.T[source]#
Replaces the experiment’s full list of entrypoints.
If an entrypoint id matches an entrypoint that is already attached to the experiment, then the experiment will update the entrypoint to the latest version. If an empty list is provided, then all entrypoints will be removed from the experiment.
- Parameters
experiment_id – The experiment id, an integer.
entrypoint_ids – A list of entrypoint ids that will replace the current list of experiment entrypoints.
- Returns
The response from the Dioptra API.
Delete All Attached Entrypoints#
Delete One Entrypoint by ID#
- ExperimentEntrypointsSubCollectionClient.delete_by_id(experiment_id: str | int, entrypoint_id: str | int) dioptra.client.experiments.T[source]#
Remove an entrypoint from the experiment.
- Parameters
experiment_id – The experiment id, an integer.
entrypoint_id – The id for the entrypoint that will be removed.
- Returns
The response from the Dioptra API.
Job Execution - Methods#
These methods exist within the class ExperimentJobsSubCollectionClient, and can are accessed via the jobs property of the Experiment Client (which points to ExperimentJobsSubCollectionClient)
Example - Run an Entrypoint as a Job within an Experiment
Run Entrypoint as a Job
client.experiments.jobs.create(experiment_id=1, entrypoint_id=[2], queue_id=10,)
Get All Jobs#
- ExperimentJobsSubCollectionClient.get(experiment_id: str | int, index: int = 0, page_length: int = 10, sort_by: str | None = None, descending: bool | None = None, search: str | None = None) dioptra.client.experiments.T[source]#
Get an experiment’s jobs.
- Parameters
experiment_id – The experiment id, an integer.
index – The paging index. Optional, defaults to 0.
page_length – The maximum number of jobs to return in the paged response. Optional, defaults to 10.
sort_by – The field to use to sort the returned list. Optional, defaults to None.
descending – Sort the returned list in descending order. Optional, defaults to None.
search – Search for models using the Dioptra API’s query language. Optional, defaults to None.
- Returns
The response from the Dioptra API.
Get One Job by ID#
Get Job Status by ID#
- ExperimentJobsSubCollectionClient.get_status(experiment_id: str | int, job_id: str | int) dioptra.client.experiments.T[source]#
Gets the status for an experiment’s job.
- Parameters
experiment_id – The experiment id, an integer.
job_id – The job id, an integer.
- Returns
The response from the Dioptra API.
Create a Job#
- ExperimentJobsSubCollectionClient.create(experiment_id: str | int, entrypoint_id: int, queue_id: int, entrypoint_snapshot_id: int | None = None, values: dict[str, Any] | None = None, artifact_values: dict[str, Any] | None = None, timeout: str | None = None, description: str | None = None) dioptra.client.experiments.T[source]#
Creates a job for an experiment.
- Parameters
experiment_id – The experiment id, an integer.
entrypoint_id – The id for the entrypoint that the job will run.
queue_id – The id for the queue that will execute the job.
entrypoint_snapshot_id – The id for a snapshot associated with the entrypoint. If specified, the snapshotted version of the entrypoint will be used to run the job. If not specified, the job will use the latest version of the entrypoint. Defaults to None.
values – A dictionary of keyword arguments to pass to the entrypoint that parameterize the job. Default to None.
artifact_values – A dictionary of artifact input names associated with a value that is also a dictionary that contains the keys “id” and “snapshotId” whose values are the artifact resource id and the artifact resource snapshot id respectively. Defaults to None.
timeout – The maximum alloted time for a job before it times out and is stopped. If omitted, the job timeout will use the default set in the API.
description – The description for the job. Optional, defaults to None.
- Returns
The response from the Dioptra API.
Set Job Status by ID#
- ExperimentJobsSubCollectionClient.set_status(experiment_id: str | int, job_id: str | int, status: str) dioptra.client.experiments.T[source]#
Sets the status for an experiment’s job.
Primarily used for testing or to reset a job that has failed, whose cause has been remedied, in order to re-run the job,
- Parameters
experiment_id – The experiment id, an integer.
job_id – The job id, an integer.
status – The new status for the job. The allowed values are: queued, started, deferred, finished, failed.
- Returns
The response from the Dioptra API.
Delete a Job by ID#
- ExperimentJobsSubCollectionClient.delete_by_id(experiment_id: str | int, job_id: str | int) dioptra.client.experiments.T[source]#
Delete a job from the experiment.
- Parameters
experiment_id – The experiment id, an integer.
job_id – The id for the job that will be deleted.
- Returns
The response from the Dioptra API.
Snapshots of Experiment - Methods#
Methods belonging to the SnapshotsSubCollectionClient can are accessed via the snapshots property of the Experiment Client (which points to SnapshotsSubCollectionClient)
Example - Get Snapshots for an Experiment
Get Snapshots for Experiment
client.experiments.snapshots.get(1)
See available methods for the SnapshotsSubCollectionClient: