tlc.client.sample_type#

Implementations of all SampleType classes.

Module Contents#

Classes#

Class

Description

SampleType

The base class for all sample types.

CompositeSampleType

Base class for all composite sample types.

StringKeyDict

A dict with string keys.

HorizontalList

A list of fixed length and structure.

Box

A helper SampleType for making a dict with a single value appear as just the value itself, when provided as a sample.

HorizontalTuple

A tuple of fixed length and structure.

AtomicSampleType

Base class for all atomic sample types.

PILImage

A PIL Image.

SegmentationPILImage

A single-channel PIL-image containing a segmentation mask.

Hidden

A value which should not be present in the sample.

Path

ImagePath

A path to an image file.

TrivialAtomicSampleType

A base class for atomic sample types whose row representation is the same as their sample representation.

Number

Base class for numeric types

Int

A python int.

NumPyInt

A numpy int.

Float

A python float.

Bool

A python bool.

CategoricalLabel

A categorical label.

String

A python string.

NoOpSampleType

The fallback SampleType for atomic schemas.

DimensionalSampleType

Base class for all dimensional sample types.

List

A list of variable length.

Tuple

A tuple of variable length.

NumpyArray

A numpy array of variable length.

BoundingBoxList

SegmentationMask

Functions#

Function

Description

register_sample_type

A decorator for registering a SampleType.

Data#

Data

Description

ST

Generic sample type

RT

Generic row type

API#

tlc.client.sample_type.ST = None#

Generic sample type

tlc.client.sample_type.RT = None#

Generic row type

class tlc.client.sample_type.SampleType(name: str)#

Bases: abc.ABC, typing.Generic[tlc.client.sample_type.ST, tlc.client.sample_type.RT]

The base class for all sample types.

A SampleType defines the type of a single sample. It can be used to create a Schema for a Table, and convert samples between their ML ‘sample’ representation and their Table ‘row’ representation. SampleType objects are structured like trees, with composite types (e.g. lists, tuples, dicts) as internal nodes and atomic types (e.g. ints, floats, strings) as leaves.

SampleType objects can be created in three main ways:

  1. From a Schema object, using SampleType.from_schema(schema).

  2. From a sample, using SampleType.from_sample(sample).

  3. From a ‘structure’, a simple declarative description of the structure of a single sample, using SampleType.from_structure(structure).

If you have custom types that you want to use in your Table, you can create a SampleType for them by subclassing the appropriate subclass of SampleType and registering it with the register_sample_type decorator.

The basic initializer for all SampleType objects.

Parameters:

name – The name of the SampleType. This will be used as the column name in the Table.

sample_types: dict[str, type[tlc.client.sample_type.SampleType]] = None#
sample_type: str = None#
rename(name: str) None#

Rename the SampleType.

Parameters:

name – The new name of the SampleType.

abstract sample_from_row(row: tlc.client.sample_type.RT) tlc.client.sample_type.ST#

Convert a row to a sample using the SampleType.

Parameters:

row – The row to convert.

Returns:

The converted sample.

abstract row_from_sample(sample: tlc.client.sample_type.ST) tlc.client.sample_type.RT#

Convert a sample to a row using the SampleType.

Parameters:

sample – The sample to convert.

Returns:

The converted row.

abstract property schema: tlc.core.schema.Schema#

A Schema object representing the SampleType.

Returns:

The Schema object.

classmethod from_schema(schema: tlc.core.schema.Schema, name: str | None = None) tlc.client.sample_type.SampleType#

Create a SampleType from a Schema.

Parameters:
  • schema – The Schema to create the SampleType from.

  • name – An optional name for the NoOpSampleType fallback.

Returns:

The created SampleType.

classmethod from_structure(structure: tlc.client.sample_type._SampleTypeStructure, name: str = 'value') tlc.client.sample_type.SampleType#

Create a SampleType from a structure.

A structure is a simple declarative description of the structure of a single sample. Instead of initializing SampleType objects for composite sample types, structures can be represented as nested lists, tuples, or dicts containing either SampleType objects, or simply a subclass of SampleType where you don’t care about the names of the columns.

E.g. ((Int, Int), String) is equivalent to:

HorizontalTuple("value",
    [
        HorizontalTuple("value_0", [Int("value_0_0"), Int("value_0_1")]),
        String("value_1")
    ]
)
Parameters:
  • structure – The structure to create the SampleType from.

  • name – The name of the SampleType.

Returns:

The created SampleType.

classmethod from_sample(sample: tlc.client.sample_type.ST, name: str = 'value', all_arrays_are_fixed_size: bool = False) tlc.client.sample_type.SampleType#

Create a SampleType from a sample.

This method is used to create a SampleType when creating a Table from a PyTorch Dataset, and the user has not specified a SampleType or a structure. Since a SampleType is needed to convert a sample to a row, the first sample of the dataset is used as a reference to create the SampleType.

Parameters:
  • sample – The sample to create the SampleType from.

  • name – The name of the SampleType.

  • all_arrays_are_fixed_size – If True, all arrays will be treated as fixed size arrays.

Returns:

The created SampleType.

sample_is_valid(sample: object) bool#

Returns true if the sample matches this SampleType, False otherwise.

Parameters:

sample – The sample to check.

Returns:

True if the sample matches this SampleType, False otherwise.

row_is_valid(row: object) bool#

Returns true if the row matches this SampleType, False otherwise.

Parameters:

row – The row to check.

Returns:

True if the row matches this SampleType, False otherwise.

tlc.client.sample_type.register_sample_type(sample_type: type[tlc.client.sample_type._SampleTypeSubclass]) type[tlc.client.sample_type._SampleTypeSubclass]#

A decorator for registering a SampleType.

Custom sample types must be registered with this decorator in order to be created from a Schema.

Parameters:

sample_type – The SampleType to register.

Returns:

The registered SampleType.

class tlc.client.sample_type.CompositeSampleType(name: str, children: list[tlc.client.sample_type.SampleType])#

Bases: tlc.client.sample_type.SampleType[tlc.client.sample_type.ST, typing.Dict[str, object]], typing.Generic[tlc.client.sample_type.ST]

Base class for all composite sample types.

Composite sample types are sample types that contain other sample types. They are used to represent composite data structures like lists, tuples, and dicts. Composite sample types have the children attribute, which is a list of the sample types that they contain.

Subclasses of CompositeSampleType only need to implement the sample_from_row and row_from_sample methods, which define how the children should be composed into a single sample or row.

The basic initializer for all SampleType objects.

Parameters:

name – The name of the SampleType. This will be used as the column name in the Table.

rename(name: str) None#
abstract sample_from_row(row: dict[str, object]) tlc.client.sample_type.ST#
abstract row_from_sample(sample: tlc.client.sample_type.ST) dict[str, object]#
property schema: tlc.core.schema.Schema#
sample_is_valid(sample: object) bool#
row_is_valid(row: object) bool#
class tlc.client.sample_type.StringKeyDict(name: str, children: list[tlc.client.sample_type.SampleType])#

Bases: tlc.client.sample_type.CompositeSampleType[typing.Dict[str, object]]

A dict with string keys.

The basic initializer for all SampleType objects.

Parameters:

name – The name of the SampleType. This will be used as the column name in the Table.

sample_type = <Multiline-String>#
rename(name: str) None#
sample_from_row(row: dict[str, object]) dict[str, object]#
row_from_sample(sample: dict[str, object]) dict[str, object]#
sample_is_valid(sample: object) bool#
class tlc.client.sample_type.HorizontalList(name: str, children: list[tlc.client.sample_type.SampleType])#

Bases: tlc.client.sample_type.CompositeSampleType[list]

A list of fixed length and structure.

The basic initializer for all SampleType objects.

Parameters:

name – The name of the SampleType. This will be used as the column name in the Table.

sample_type = horizontal_list#
sample_from_row(row: dict[str, object]) list#
row_from_sample(sample: list) dict[str, object]#
class tlc.client.sample_type.Box(child: tlc.client.sample_type._SampleTypeStructure)#

Bases: tlc.client.sample_type.CompositeSampleType[object]

A helper SampleType for making a dict with a single value appear as just the value itself, when provided as a sample.

The basic initializer for all SampleType objects.

Parameters:

name – The name of the SampleType. This will be used as the column name in the Table.

sample_type = box#
sample_from_row(row: dict[str, object]) object#
row_from_sample(sample: object) dict[str, object]#
sample_is_valid(sample: object) bool#
class tlc.client.sample_type.HorizontalTuple(name: str, children: list[tlc.client.sample_type.SampleType])#

Bases: tlc.client.sample_type.CompositeSampleType[tuple]

A tuple of fixed length and structure.

The basic initializer for all SampleType objects.

Parameters:

name – The name of the SampleType. This will be used as the column name in the Table.

sample_type = horizontal_tuple#
sample_from_row(row: dict[str, object]) tuple#
row_from_sample(sample: tuple) dict[str, object]#
class tlc.client.sample_type.AtomicSampleType(name: str)#

Bases: tlc.client.sample_type.SampleType[tlc.client.sample_type.ST, tlc.client.sample_type.RT]

Base class for all atomic sample types.

Atomic sample types are sample types that contain a single value. They are used to represent atomic data structures like ints, floats, strings, and images. Atomic sample types have the value attribute, which is a ScalarValue required to create a Schema for the SampleType.

Subclasses of AtomicSampleType only need to implement the sample_from_row and row_from_sample methods, which define how the value should be converted to and from a row, as well as the value property.

The basic initializer for all SampleType objects.

Parameters:

name – The name of the SampleType. This will be used as the column name in the Table.

abstract sample_from_row(row: tlc.client.sample_type.RT) tlc.client.sample_type.ST#
abstract row_from_sample(sample: tlc.client.sample_type.ST) tlc.client.sample_type.RT#
property schema: tlc.core.schema.Schema#
abstract property value: tlc.core.schema.ScalarValue#

A ScalarValue representing the SampleType.

Returns:

The ScalarValue object.

class tlc.client.sample_type.PILImage(name: str)#

Bases: tlc.client.sample_type.AtomicSampleType[PIL.Image.Image, str]

A PIL Image.

The basic initializer for all SampleType objects.

Parameters:

name – The name of the SampleType. This will be used as the column name in the Table.

sample_type = PILImage#
property value: tlc.core.schema.StringValue#
sample_from_row(row: str) PIL.Image.Image#
row_from_sample(sample: PIL.Image.Image) str#
class tlc.client.sample_type.SegmentationPILImage(name: str, classes: list[str] | dict[int, str] | dict[float, str] | dict[float, tlc.core.schema.MapElement])#

Bases: tlc.client.sample_type.PILImage

A single-channel PIL-image containing a segmentation mask.

The basic initializer for all SampleType objects.

Parameters:

name – The name of the SampleType. This will be used as the column name in the Table.

sample_type = segmentation_PILImage#
property value: tlc.core.schema.SegmentationMaskUrlStringValue#
class tlc.client.sample_type.Hidden(name: str, value: tlc.core.schema.ScalarValue)#

Bases: tlc.client.sample_type.AtomicSampleType[None, object]

A value which should not be present in the sample.

The basic initializer for all SampleType objects.

Parameters:

name – The name of the SampleType. This will be used as the column name in the Table.

sample_type = hidden#
property value: tlc.core.schema.ScalarValue#
sample_from_row(row: object) None#
row_from_sample(sample: object) object#
class tlc.client.sample_type.Path(name: str)#

Bases: tlc.client.sample_type.AtomicSampleType[str, str]

sample_type: str = path#
property value: tlc.core.schema.StringValue#
sample_from_row(row: str) str#
row_from_sample(sample: str) str#
class tlc.client.sample_type.ImagePath(name: str)#

Bases: tlc.client.sample_type.Path

A path to an image file.

The basic initializer for all SampleType objects.

Parameters:

name – The name of the SampleType. This will be used as the column name in the Table.

sample_type = image_path#
property value: tlc.core.schema.StringValue#
class tlc.client.sample_type.TrivialAtomicSampleType(name: str)#

Bases: tlc.client.sample_type.AtomicSampleType[tlc.client.sample_type.ST, tlc.client.sample_type.ST]

A base class for atomic sample types whose row representation is the same as their sample representation.

Subclasses of TrivialAtomicSampleType only need to implement the value property.

The basic initializer for all SampleType objects.

Parameters:

name – The name of the SampleType. This will be used as the column name in the Table.

sample_from_row(row: tlc.client.sample_type.ST) tlc.client.sample_type.ST#
row_from_sample(sample: tlc.client.sample_type.ST) tlc.client.sample_type.ST#
class tlc.client.sample_type.Number(name: str, number_role: str = '')#

Bases: tlc.client.sample_type.TrivialAtomicSampleType[tlc.client.sample_type.ST]

Base class for numeric types

The basic initializer for all SampleType objects.

Parameters:

name – The name of the SampleType. This will be used as the column name in the Table.

class tlc.client.sample_type.Int(name: str, precision: Literal[8, 16, 32, 64] = 32, signed: bool = True, number_role: str = '')#

Bases: tlc.client.sample_type._Int[int]

A python int.

Parameters:
  • precision – The precision of the integer, in bits. Must be one of [8, 16, 32, 64].

  • signed – Whether the value of the integer can be negative.

  • number_role – The number role of the integer. This determines how the integer will be displayed in the Dashboard.

sample_type = int#
class tlc.client.sample_type.NumPyInt(name: str, precision: Literal[8, 16, 32, 64] = 64, signed: bool = True, number_role: str = '')#

Bases: tlc.client.sample_type._Int[numpy.integer]

A numpy int.

Parameters:
  • precision – The precision of the integer, in bits. Must be one of [8, 16, 32, 64].

  • signed – Whether the value of the integer can be negative.

  • number_role – The number role of the integer. This determines how the integer will be displayed in the Dashboard.

sample_type = numpy_int#
sample_is_valid(sample: object) bool#
class tlc.client.sample_type.Float(name: str, precision: Literal[32, 64] = 32, normalized: bool = False, number_role: str = '')#

Bases: tlc.client.sample_type.Number[float]

A python float.

Parameters:
  • precision – The precision of the float, in bits. Must be one of [32, 64].

  • normalized – Whether the value of the float is normalized between 0 and 1.

  • number_role – The number role of the float. This determines how the float will be displayed in the Dashboard.

sample_type = float#
property value: tlc.core.schema.Float32Value | tlc.core.schema.Float64Value#
class tlc.client.sample_type.Bool(name: str)#

Bases: tlc.client.sample_type.TrivialAtomicSampleType[bool]

A python bool.

The basic initializer for all SampleType objects.

Parameters:

name – The name of the SampleType. This will be used as the column name in the Table.

sample_type = bool#
property value: tlc.core.schema.BoolValue#
class tlc.client.sample_type.CategoricalLabel(name: str, classes: list[str] | dict[int, str] | dict[float, str] | dict[float, tlc.core.schema.MapElement])#

Bases: tlc.client.sample_type.TrivialAtomicSampleType[int]

A categorical label.

Categorical labels are represented as ints, with the mapping from ints to class names defined by the classes attribute, a list of strings.

Create a CategoricalLabel.

Parameters:
  • name – The name of the CategoricalLabel.

  • classes – The classes of the CategoricalLabel.

sample_type = categorical_label#
property value: tlc.core.schema.Int32Value#
class tlc.client.sample_type.String(name: str, string_role: str = '')#

Bases: tlc.client.sample_type.TrivialAtomicSampleType[str]

A python string.

Parameters:

string_role – The string role of the string. This determines how the string will be displayed in the Dashboard.

sample_type = string#
property value: tlc.core.schema.StringValue#
class tlc.client.sample_type.NoOpSampleType(name: str, value: tlc.core.schema.ScalarValue)#

Bases: tlc.client.sample_type.TrivialAtomicSampleType[object]

The fallback SampleType for atomic schemas.

The basic initializer for all SampleType objects.

Parameters:

name – The name of the SampleType. This will be used as the column name in the Table.

sample_type = <Multiline-String>#
property value: tlc.core.schema.ScalarValue#
class tlc.client.sample_type.DimensionalSampleType(content: tlc.client.sample_type._SampleTypeStructure)#

Bases: tlc.client.sample_type.SampleType[tlc.client.sample_type.ST, list]

Base class for all dimensional sample types.

Dimensional sample types describe how a sample can be extended along a dimension. They are used to represent composite data structures whose size might vary between samples in a dataset. Dimensional sample types have the content attribute, which is a sample type that describes the structure of the samples along the dimension.

Subclasses of DimensionalSampleType only need to implement the sample_from_row and row_from_sample methods, which define how the content should be composed into a single sample or row.

The basic initializer for all DimensionalSampleType objects.

Parameters:

content – The sample type that describes the structure of the samples along the dimension.

rename(name: str) None#
property schema: tlc.core.schema.Schema#
abstract sample_from_row(row: list) tlc.client.sample_type.ST#
abstract row_from_sample(sample: tlc.client.sample_type.ST) list#
sample_is_valid(sample: object) bool#
row_is_valid(row: object) bool#
class tlc.client.sample_type.List(content: tlc.client.sample_type._SampleTypeStructure)#

Bases: tlc.client.sample_type.DimensionalSampleType[list]

A list of variable length.

The basic initializer for all DimensionalSampleType objects.

Parameters:

content – The sample type that describes the structure of the samples along the dimension.

sample_type = list#
sample_from_row(row: list) list#
row_from_sample(sample: list) list#
class tlc.client.sample_type.Tuple(content: tlc.client.sample_type._SampleTypeStructure)#

Bases: tlc.client.sample_type.DimensionalSampleType[tuple]

A tuple of variable length.

The basic initializer for all DimensionalSampleType objects.

Parameters:

content – The sample type that describes the structure of the samples along the dimension.

sample_type = tuple#
sample_from_row(row: list) tuple#
row_from_sample(sample: tuple) list#
class tlc.client.sample_type.NumpyArray(shape: tuple[int, ...], content: tlc.client.sample_type._SampleTypeStructure)#

Bases: tlc.client.sample_type.DimensionalSampleType[numpy.ndarray]

A numpy array of variable length.

The basic initializer for all NumpyArray objects.

Parameters:
  • shape – The shape of the array.

  • content – The sample type that describes the structure of the samples along the dimension.

sample_type = numpy_array#
property schema: tlc.core.schema.Schema#
sample_from_row(row: list) numpy.ndarray#
row_from_sample(sample: numpy.ndarray) list#
sample_is_valid(sample: object) bool#
static compute_row_shape(row: list) tuple[int, ...]#

Compute the shape of a row in a NumpyArray from the row itself.

Parameters:

row – The row to compute the shape from.

Returns:

The shape of the row.

row_is_valid(row: object) bool#
class tlc.client.sample_type.BoundingBoxList(name: str, format: Literal[xywh, xyxy] = 'xyxy', normalized: bool = False, classes: list[str] | dict[int, str] | dict[float, str] | dict[float, tlc.core.schema.MapElement] = [])#

Bases: tlc.client.sample_type.StringKeyDict

class tlc.client.sample_type.SegmentationMask(name: str, classes: list[str] | dict[int, str] | dict[float, str] | dict[float, tlc.core.schema.MapElement] = [])#

Bases: tlc.client.sample_type.AtomicSampleType[torch.Tensor, str]

sample_type = segmentation_mask#
row_from_sample(sample: torch.Tensor) str#
sample_from_row(row: str) torch.Tensor#
property value: tlc.core.schema.StringValue#