tlc.core.objects.mutable_objects.run

Represents a single execution of a specific process or experiment.

Module Contents

Classes

Class	Description
Run	Represents a single execution of a specific process or experiment.

API

class tlc.core.objects.mutable_objects.run.Run(*, url: tlc.core.url.Url | None = None, created: str | None = None, last_modified: str | None = None, description: str | None = None, metrics: list[dict[str, Any]] | None = None, constants: dict[str, Any] | None = None, status: float | None = None, init_parameters: Any = None)

Bases: tlc.core.objects.mutable_object.MutableObject

Represents a single execution of a specific process or experiment.

A Run object encapsulates details about its setup, execution, metadata, and metrics.

Run objects are mutable, allowing for updates to run attributes as they progress or as additional information becomes available.

Create a Run object.

Parameters:

• description – The description of the run.

• metrics – A list of metrics captured during this run.

• constants – Constant values used during this run.

• status – The status of the run.

copy(run_name: str | None = None, project_name: str | None = None, root_url: tlc.core.url.Url | str | None = None, if_exists: typing.Literal[raise, rename, overwrite] = 'raise', *, destination_url: tlc.core.url.Url | None = None) → tlc.core.objects.mutable_objects.run.Run

Create a copy of this run.

The copy is performed to:

1. A URL derived from the given run_name, project_name, and root_url if given

2. destination_url, if given

3. A generated URL derived from the run’s URL, if none of the above are given

Parameters:

• run_name – The name of the run to create.

• project_name – The name of the project to create the run in.

• root_url – The root URL to create the run in.

• if_exists – What to do if the destination URL already exists.

• destination_url – The URL to copy the run to.

Returns:

The copied run.

property name: str

The name of the run.

add_input_table(input_table: tlc.core.objects.table.Table | tlc.core.url.Url | str) → None

Adds an input table to the run.

This updates the Run object to include the input table in the list of inputs to the Run.

Parameters:

input_table – The input table to add.

add_input_value(input_value: dict[str, Any]) → None

Adds a value to the inputs of the run.

Parameters:

input_value – The value to add.

add_output_value(output_value: dict[str, Any]) → None

Adds a value to the outputs of the run.

Parameters:

output_value – The value to add.

set_parameters(parameters: dict[str, Any]) → None

Set the parameters of the run.

Parameters:

parameters – The parameters to set.

set_description(description: str) → None

Set the description of the run.

Parameters:

description – The description to set.

static from_url(url: tlc.core.url.Url | str) → tlc.core.objects.mutable_objects.run.Run

Creates a Run instance from the URL of an existing Run.

Parameters:

url – The URL to the Run object.

Returns:

The Run object.

static from_names(run_name: str | None = None, project_name: str | None = None, root_url: tlc.core.url.Url | str | None = None) → tlc.core.objects.mutable_objects.run.Run

Creates a Run instance from the names specifying the URL of an existing Run.

Parameters:

• run_name – The name of the run.

• project_name – The name of the project.

• root_url – The root url to use instead of the default root url.

Returns:

The Run at the resulting url.

property metrics_tables: list[tlc.core.objects.table.Table]

Returns a list of the metrics tables for this run.

property bulk_data_url: tlc.core.url.Url

Returns the URL of the bulk data for this run.

reduce_embeddings_by_foreign_table_url(foreign_table_url: tlc.core.url.Url | str, delete_source_tables: bool = True, **kwargs: Any) → dict[tlc.core.url.Url, tlc.core.url.Url]

Reduces all metrics tables in a Run using a reducer trained on the embeddings in a specified metrics table.

See tlc.reduce_embeddings_by_foreign_table_url for more information.

Parameters:

• foreign_table_url – The Url of the foreign table to use for reduction.

• delete_source_tables – If True, the source metrics tables will be deleted after reduction.

Returns:

A dictionary mapping the original table URLs to the reduced table URLs.

reduce_embeddings_per_dataset(delete_source_tables: bool = True, **kwargs: Any) → dict[tlc.core.url.Url, tlc.core.url.Url]

Reduces the embeddings for each dataset in this run.

See tlc.reduce_embeddings_per_dataset for more information.

Parameters:

delete_source_tables – If True, the source metrics tables will be deleted after reduction.

Returns:

A dictionary mapping the original table URLs to the reduced table URLs.

update_metrics(metric_infos: list[tlc.core.builtins.types.MetricTableInfo] = []) → None

Add new metrics to the run.

Any metrics that are already present in the run will not be added again.

Parameters:

metric_infos – A list of MetricTableInfo dicts to add to the run.

add_metrics_table(metrics_table: tlc.core.objects.table.Table | tlc.core.url.Url) → None

Add a metrics table to the run.

Parameters:

metrics_table – The metrics table to add.

add_metrics(metrics: dict[str, tlc.core.builtins.types.MetricData], column_schemas: dict[str, tlc.core.schema.Schema] | None = None, foreign_table_url: tlc.core.url.Url | str | None = None, foreign_table_display_name: str = '') → list[tlc.core.builtins.types.MetricTableInfo]

Write the provided metrics to a Table and associate it with the run.

Parameters:

• metrics – The metrics data (dict of column names to column data) to write.

• column_schemas – The schemas for the metrics data.

• foreign_table_url – The URL of the table to associate with the metrics data. If provided, the metrics data will be augmented with extra columns to identify the example ID and the foreign table, if these columns are not already present. If the metrics data does not correspond 1-to-1 with the table, ensure the metrics data includes an “example_id” column.

• foreign_table_display_name – The display name of the foreign table to show in the Dashboard.

Returns:

The written table info.

Raises:

• ValueError – If the number of rows in the metrics data does not match the number of rows in the table, or the input_table_url is not a valid URL.

• FileNotFoundError – If the input_table_url can not be found.

add_metrics_data(metrics: dict[str, tlc.core.builtins.types.MetricData], override_column_schemas: dict[str, tlc.core.schema.Schema] = {}, input_table_url: tlc.core.url.Url | str | None = None, table_writer_base_name: str = 'metrics', stream_name: str = '') → list[tlc.core.builtins.types.MetricTableInfo]

Write the given metrics to a Table and updates the run with the table info.

Parameters:

• metrics – The metrics data (dict of column-names to columns) to write.

• override_column_schemas – A dictionary of schemas to override the default schemas for the columns.

• input_table_url – The URL of the table to associate with the metrics data. If provided, the metrics data will be augmented with extra columns to identify the example ID and the foreign table, if these columns are not already present. If the metrics data does not correspond 1-to-1 with the table, ensure the metrics data includes an “example_id” column.

• table_writer_base_name – The base name of the written tables.

• table_writer_key – A key used to further identify the written tables.

Returns:

The written table infos.

Raises:

• ValueError – If the number of rows in the metrics data does not match the number of rows in the table, or the input_table_url is not a valid URL.

• FileNotFoundError – If the input_table_url can not be found.

set_status_running() → None

Set the status of the run to running.

set_status_collecting() → None

Set the status of the run to collecting.

set_status_post_processing() → None

Set the status of the run to post processing.

set_status_completed() → None

Set the status of the run to completed.

set_status_empty() → None

Set the status of the run to empty.

set_status_paused() → None

Set the status of the run to paused.

set_status_cancelled() → None

Set the status of the run to cancelled.