`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`	A string representing a 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.
`NumPyFloat`	A numpy 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.
`PythonContainer`	Dimensional sample types whose row representation is a list.
`List`	A list of variable length.
`Tuple`	A tuple of variable length.
`NumpyArray`	A numpy array of variable length.
`Singleton`	A sample type for handling the concept of a pseudo-scalar; a scalar which has a size0 with min=max=1.
`BoundingBoxList`	A COCO-like list of bounding boxes.
`SegmentationMask`	A torch tensor representing a segmentation mask.

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:

From a Schema object, using SampleType.from_schema(schema).
From a sample, using SampleType.from_sample(sample).
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.

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

sample_type: str = None#: A string representing the type of the SampleType. This is used to identify the SampleType in a Schema.

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 = 'value') → 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.

ensure_sample_valid(sample: object) → None#

Raises a ValueError if the sample does not match this SampleType. Does nothing otherwise.

Parameters:: sample – The sample to validate.
Raises:: ValueError – If the sample does not match this SampleType.

ensure_row_valid(row: object) → None#

Raises a ValueError if the row does not match this SampleType. Does nothing otherwise.

Parameters:: row – The row to validate.
Raises:: ValueError – If the row does not match this SampleType.

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.

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#

ensure_sample_valid(sample: object) → None#

ensure_row_valid(row: object) → None#

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.

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]#

ensure_sample_valid(sample: object) → None#

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.

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, hidden_children: list[tlc.client.sample_type._SampleTypeStructure] | None = None)#

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.

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]#

ensure_sample_valid(sample: object) → None#

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.

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.

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.

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.

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, schema: tlc.core.schema.Schema)#

Bases: tlc.client.sample_type.SampleType[object, object]

A value which should not be present in the sample.

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

sample_type = hidden#

property schema: tlc.core.schema.Schema#

sample_from_row(row: object) → NoReturn#

row_from_sample(sample: object) → object#: While the ‘sample view’ of a Hidden sample normally does not exist, this is a useful workaround for writing values with a “hidden” sample type in their schema to a Table using TableWriter

ensure_sample_valid(sample: object) → None#: Hidden values will not be present in the ‘sample view’, but this function never raises in order to allow users to write values with a “hidden” sample type in their schema to a Table using TableWriter.

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

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

A string representing a path.

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

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.

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.

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

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#

ensure_sample_valid(sample: object) → None#

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

Bases: tlc.client.sample_type._Float[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#

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

Bases: tlc.client.sample_type._Float[numpy.floating]

A numpy 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 = numpy_float#

ensure_sample_valid(sample: object) → None#

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

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

A python bool.

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.

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, tlc.client.sample_type.RT]

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#

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#

ensure_sample_valid(sample: object) → None#

ensure_row_valid(row: object) → None#

class tlc.client.sample_type.PythonContainer(content: tlc.client.sample_type._SampleTypeStructure, min_size: int = 0, max_size: int | None = None)#

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

Dimensional sample types whose row representation is a list.

Parameters:

content – The sample type that describes the structure of the samples along the dimension.
min_size – The minimum size of the container.
max_size – The maximum size of the container.

row_from_sample(sample: tlc.client.sample_type._ContainerST) → list#

property schema: tlc.core.schema.Schema#

ensure_sample_valid(sample: object) → None#

ensure_row_valid(row: object) → None#

class tlc.client.sample_type.List(content: tlc.client.sample_type._SampleTypeStructure, min_size: int = 0, max_size: int | None = None)#

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

A list of variable length.

Parameters:

content – The sample type that describes the structure of the samples along the dimension.
min_size – The minimum size of the container.
max_size – The maximum size of the container.

sample_type = list#

sample_from_row(row: list) → list#

class tlc.client.sample_type.Tuple(content: tlc.client.sample_type._SampleTypeStructure, min_size: int = 0, max_size: int | None = None)#

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

A tuple of variable length.

Parameters:

content – The sample type that describes the structure of the samples along the dimension.
min_size – The minimum size of the container.
max_size – The maximum size of the container.

sample_type = tuple#

sample_from_row(row: list) → tuple#

class tlc.client.sample_type.NumpyArray(shape: tuple[int, ...], content: tlc.client.sample_type._SampleTypeStructure)#

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

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#

ensure_sample_valid(sample: object) → None#

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.

ensure_row_valid(row: object) → None#

class tlc.client.sample_type.Singleton(content: tlc.client.sample_type._SampleTypeStructure)#

Bases: tlc.client.sample_type.DimensionalSampleType[object, object]

A sample type for handling the concept of a pseudo-scalar; a scalar which has a size0 with min=max=1.

This value should appear in both its sample and row representations as the scalar itself, rather than a list containing the scalar.

The basic initializer for all DimensionalSampleType objects.

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

sample_type = singleton#

property schema: tlc.core.schema.Schema#

sample_from_row(row: object) → object#

row_from_sample(sample: object) → object#

ensure_sample_valid(sample: object) → None#

ensure_row_valid(row: object) → None#

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

A COCO-like list of bounding boxes.

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

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]

A torch tensor representing a segmentation mask.

The tensor is expected to have shape (H, W) and contain integer values representing the class of each pixel.

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

sample_type = segmentation_mask#

row_from_sample(sample: torch.Tensor) → str#

sample_from_row(row: str) → torch.Tensor#

property value: tlc.core.schema.StringValue#

tlc.client.sample_type#

Module Contents#

Classes#

Functions#

Data#

API#

`tlc.client.sample_type`#