User Guides
Python SDK Reference

Experiment

Properties

Methods

update

update(
   name: Optional[str] = None, description: Optional[str] = None,
   base_experiment: Optional['Experiment'] = None,
   base_model_version: Optional['ModelVersion'] = None,
   status: Union[ExperimentStatus, str, None] = None
)

Description

Update this experiment with a given name, description or a base experiment or a base model version.

Examples

my_experiment.update(description="First try Yolov5")

delete

delete()

Description

Delete this experiment.

Examples

my_experiment.delete()

list_artifacts

list_artifacts(
   limit: Optional[int] = None, offset: Optional[int] = None,
   order_by: Optional[List[str]] = None
)

Description

List artifacts stored in the experiment.

Examples

artifacts = my_experiment.list_artifacts()

Returns

A list of artifact objects that you can manipulate

delete_all_artifacts

delete_all_artifacts()

Description

Delete all stored artifacts for experiment

:warning: DANGER ZONE: This will definitely remove the artifacts from our servers

Examples

experiment.delete_all_artifacts()

create_artifact

create_artifact(
   name: str, filename: str, object_name: str, large: bool = False
)

Description

Create an artifact for this experiment.

Examples

self.create_artifact(name="a_file", filename="file.png", object_name="some_file_in_s3.png", large=False)

Arguments

  • name (str) : name of the artifact.

  • filename (str) : filename.

  • object_name (str) : s3 object name.

  • large (bool, optional) : >5Mb or not. Defaults to False.

Returns

An artifact object

store

store(
   name: str, path: Union[str, Path, None] = None, do_zip: bool = False
)

Description

Store an artifact and attach it to the experiment.

Examples

# Zip and store a folder as an artifact for the experiment
# you can choose an arbitrary name or refer to our 'namespace'
# for certain artifacts to have a custom behavior

trained_model_path = "my_experiment/saved_model"
experiment.store("model-latest", trained_model_path, zip=True)

Arguments

  • name (str) : name for the artifact. Defaults to "".

  • path (str or Path) : path to the file or folder. Defaults to None.

  • do_zip (bool, optional) : Whether to compress the file to a zip file. Defaults to False.

Raises

  • FileNotFoundException : No file found at the given path

store_local_artifact

store_local_artifact(
   name: str
)

Description

Store an artifact in platform that is locally stored

This artifact shall have the name: config, checkpoint-data-latest, checkpoint-index-latest or model-latest

It will look for special file into current directory.

Examples

my_experiment.store_local_artifact("model-latest")

Arguments

  • name (str) : Name of the artifact to store

Returns

An Artifact object

get_base_model_version

get_base_model_version()

Description

Retrieve the base model of this experiment.

Examples

model_version = experiment.get_base_model_version()

Returns

A ModelVersion object representing the base model.

get_base_experiment

get_base_experiment()

Description

Retrieve the base experiment of this experiment.

Examples

previous = experiment.get_base_experiment()

Returns

An Experiment object representing the base experiment.

get_artifact

get_artifact(
   name: str
)

Description

Retrieve an artifact information.

Examples

model_artifact = experiment.get_artifact("model-latest")
assert model_artifact.name == "model-latest"
assert model_artifact.object_name == "d67924a0-7757-48ed-bf7a-322b745e917e/saved_model.zip"

Arguments

  • name (str) : Name of the artifact to retrieve

Returns

An Artifact object

list_logs

list_logs(
   limit: Optional[int] = None, offset: Optional[int] = None,
   order_by: Optional[List[str]] = None
)

Description

List everything that has been logged.

List everything that has been logged to an experiment using the .log() method.

Examples

logs = experiment.list_logs()
assert logs[0].type == LogType.Table
assert logs[0].data == {"batch_size":4, "epochs":1000 }

Returns

A list of Log objects

delete_all_logs

delete_all_logs()

Description

Delete everything that has been logged.

Delete everything that has been logged (using .log()) into this experiment method.

Examples

experiment.delete_all_logs()

get_log

get_log(
   name: str
)

Description

Get data for a given log in this experiment

Examples

parameters = experiment.get_log("parameters")
assert log.parameters == { "batch_size":4, "epochs":1000 }

Arguments

  • name (str) : name of the log to retrieve

Returns

A Log object

log

log(
   name: str, data: LogDataType, type: Union[LogType, str], replace: bool = True
)

Description

Record some data in an experiment.

It will create a Log object, that you can manipulate in SDK.
All logs are displayed in experiment view on Picsellia.

If a Log with this name already exists, it will be updated unless parameter replace is set to False.

If it is a LogType LINE and replace is True, then it will append data at the end of stored data.
If you want to replace a line, delete this log and create another one.

Examples

parameters = {
    "batch_size":4,
    "epochs":1000
}
exp.log("parameters", parameters, type=LogType.TABLE)

Arguments

  • name (str) : Name of the log.

  • data (Any) : Data to be saved.

  • type (LogType, optional) : Type of the data to log.
    This will condition how it is displayed in the experiment dashboard. Defaults to None.

  • replace (bool, optional) : If true and log already exists and it is not a line, it will replace log data.
    Defaults to True.

Raises

  • Exception : Impossible to upload the file when logging an image.

log_parameters

log_parameters(
   parameters: dict
)

Description

Record parameters of an experiment into Picsellia.

If parameters were already setup, it will be replaced.

Examples

parameters = {
    "batch_size":4,
    "epochs":1000
}
exp.log_parameters(parameters)

Arguments

  • parameters (Any) : Parameters to be saved.

store_logging_file

store_logging_file(
   path: Union[str, Path]
)

Description

Store a logging file for this experiment.

Examples

experiment.store_logging_file("logs.txt")

Arguments

  • path (str or Path) : path to the file or folder.

Raises

  • FileNotFoundException : No file found at the given path

get_logging_file

get_logging_file()

Description

Retrieve logging file of this experiment.

Examples

logging_file = experiment.get_logging_file()
logging_file.download()

send_logging

send_logging(
   log: Union[str, list], part: str, final: bool = False, special: Union[str, bool,
   list] = False
)

Description

Send a logging experiment to the experiment .

Arguments

  • log (str) : Log content

  • part (str) : Logging Part

  • final (bool, optional) : True if Final line. Defaults to False.

  • special (bool, optional) : True if special log. Defaults to False.

start_logging_chapter

start_logging_chapter(
   name: str
)

Description

Print a log entry to the log .

Arguments

  • name (str) : Chapter name

start_logging_buffer

start_logging_buffer(
   length: int = 1
)

Description

Start logging buffer .

Arguments

  • length (int, optional) : Buffer length. Defaults to 1.

end_logging_buffer

end_logging_buffer()

Description

End the logging buffer .

update_job_status

update_job_status(
   status: Union[JobStatus, str]
)

Description

Update the job status.

Arguments

  • status (JobStatus) : Status to send

publish

publish(
   name: str
)

Description

export_as_model

export_as_model(
   name: str
)

Description

Publish an Experiment as a ModelVersion to your registry.
A Model with given name will be created, and its first version will be the exported experiment

Examples

model_version = experiment.export_as_model("awesome-model")

Arguments

  • name (str) : Target Name for the model in the registry.

Returns

A ModelVersion just created from the experiment

export_in_existing_model

export_in_existing_model(
   existing_model: Model
)

Description

Publish an Experiment as a ModelVersion of given already existing Model

Examples

model_version = experiment.export_in_existing_model("awesome-model")

Arguments

  • existing_model (Model) : Model in the registry were this experiment should be exported.

Returns

A ModelVersion just created from the experiment

launch

launch(
   gpus: int = 1
)

Description

Launch a job on a remote environment with this experiment.

:information-source: The remote environment has to be setup prior launching the experiment.
It defaults to our remote training engine.

Examples

experiment.launch()

Arguments

  • gpus (int, optional) : Number of GPU to use for the training. Defaults to 1.

download_artifacts

download_artifacts(
   with_tree: bool
)

Description

attach_model_version

attach_model_version(
   model_version: ModelVersion, do_attach_base_parameters: bool = True
)

Description

Attach model version to this experiment.
There is only one model version attached to an experiment

Examples

foo_model = client.get_model("foo").get_version(3)
my_experiment.attach_model_version(foo_model)

Arguments

  • model_version ModelVersion : A model version to attach to the experiment.

  • do_attach_base_parameters (bool) : Attach base parameters of model version to experiment. Defaults to True.

attach_dataset

attach_dataset(
   name: str, dataset_version: DatasetVersion
)

Description

Attach a dataset version to this experiment.

Retrieve or create a dataset version and attach it to this experiment.

Examples

foo_dataset = client.get_dataset("foo").get_version("first")
my_experiment.attach_dataset("training", foo_dataset)

Arguments

  • name (str) : Name to label this attached dataset. Use it like a descriptor of the attachment.

  • dataset_version DatasetVersion : A dataset version to attach to the experiment.

detach_dataset

detach_dataset(
   dataset_version: DatasetVersion
)

Description

Detach a dataset version from this experiment.

Examples

foo_dataset = client.get_dataset("foo").get_version("first")
my_experiment.attach_dataset(foo_dataset)
my_experiment.detach_dataset(foo_dataset)

Arguments

  • dataset_version DatasetVersion : A dataset version to attach to the experiment.

list_attached_dataset_versions

list_attached_dataset_versions()

Description

Retrieve all dataset versions attached to this experiment

Examples

datasets = my_experiment.list_attached_dataset_versions()

Returns

A list of DatasetVersion object attached to this experiment

get_dataset

get_dataset(
   name: str
)

Description

Retrieve the dataset version attached to this experiment with given name

Examples

pics = dataset.list_assets()
annotations = dataset.list_annotations()

Returns

A DatasetVersion object attached to this experiment

run_train_test_split_on_dataset

run_train_test_split_on_dataset(
   name: str, prop: float = 0.8, random_seed: Optional[Any] = None
)

Description

Retrieve the dataset version attached to this experiment with given name

Examples

pics = dataset.list_assets()
annotations = dataset.list_annotations()

Returns

A DatasetVersion object attached to this experiment