Sampling

Sampling operates on a DatasetQuery. For filtering, sorting, and slicing examples that define the input set for sampling, see Search and Filter.

Provides the user python interface to sampling bound to sample ids.

Sampling

Sampling(dataset_id: UUID, session: Session, input_sample_ids: Iterable[UUID])

Smart sampling interface.

The Sampling class allows to select a subset of samples from a given set of input samples. There are many different strategies to select samples, e.g. diversity based on embeddings or weighting based on numeric metadata. Multiple strategies can be combined to form more complex sampling strategies.

The result of a sampling is stored as a tag on the selected samples in the database. The sampling_result_tag_name must be a unique tag name that is not used yet.

Creation of a Sampling instance.

Creation of an instance of this is easiest via the DatasetQuery class. By using a match() first, the samples to select from can be filtered down.

from lightly_studio.core.dataset_query import ImageSampleField

# Select from all samples in the dataset.
sampling = dataset.query().sampling()

# Select only from samples with width < 256.
query_narrow_images = dataset.query().match(ImageSampleField.width < 256)
sampling_among_narrow_images = query_narrow_images.sampling()

See the DatasetQuery.match() documentation for more information on filtering. By creating the Sampling instance, the query is executed. Further changes to the query do not affect the sampling instance.

Performing single-strategy samplings.

Once a Sampling instance is created, different sampling strategies can be applied to select samples. Single-strategy samplings are performed by calling the respective method on the Sampling instance. All methods take the number of samples to select and a tag name for the sampling result as mandatory arguments.

# Select 100 diverse samples based on embeddings
sampling.diverse(
    n_samples_to_select=100,
    sampling_result_tag_name="diverse sampling",
)
# Select 50 samples weighted by numeric metadata "difficulty"
sampling.metadata_weighting(
    n_samples_to_select=50,
    sampling_result_tag_name="weighted sampling",
    metadata_key="difficulty",
)
# Select 100 samples with balanced annotation classes (e.g. uniform distribution)
sampling.annotation_balancing(
    n_samples_to_select=100,
    sampling_result_tag_name="balanced sampling",
    target_distribution="uniform",
)

Performing multi-strategy samplings.

More complex sampling strategies can be formed by combining multiple sampling strategies. This is done via the multi_strategies() method, which takes a list of sampling strategies as an argument.

from lightly_studio.sampling.sampling_config import (
    EmbeddingDiversityStrategy,
    MetadataWeightingStrategy
)

# Select 75 samples that are diverse and weighted by "difficulty"
sampling.multi_strategies(
    n_samples_to_select=75,
    sampling_result_tag_name="diverse and weighted sampling",
    sampling_strategies=[
        EmbeddingDiversityStrategy(),
        MetadataWeightingStrategy(metadata_key="difficulty"),
    ],
)

Parameters:

Name	Type	Description	Default
dataset_id	UUID	Dataset in which the sampling is performed.	required
session	Session	Database session to resolve sampling dependencies.	required
input_sample_ids	Iterable[UUID]	Candidate sample ids considered for sampling. The iterable is consumed immediately to capture a stable snapshot.	required

annotation_balancing

annotation_balancing(
    n_samples_to_select: int,
    sampling_result_tag_name: str,
    target_distribution: AnnotationClassToTarget | Literal["uniform"] | Literal["input"],
) -> None

Select a subset using annotation class balancing.

Parameters:

Name	Type	Description	Default
n_samples_to_select	int	Number of samples to select.	required
sampling_result_tag_name	str	Tag name for the sampling result.	required
target_distribution	AnnotationClassToTarget | Literal['uniform'] | Literal['input']	Can be 'uniform', 'input', or a dictionary mapping class names to target ratios.	required

diverse

diverse(
    n_samples_to_select: int, sampling_result_tag_name: str, embedding_model_name: str | None = None
) -> None

Select a diverse subset using embeddings.

Parameters:

Name	Type	Description	Default
n_samples_to_select	int	Number of samples to select.	required
sampling_result_tag_name	str	Tag name for the sampling result.	required
embedding_model_name	str | None	Optional embedding model name. If None, uses the only available model or raises if multiple exist.	None

metadata_weighting

metadata_weighting(
    n_samples_to_select: int, sampling_result_tag_name: str, metadata_key: str
) -> None

Select a subset based on numeric metadata weights.

Parameters:

Name	Type	Description	Default
n_samples_to_select	int	Number of samples to select.	required
sampling_result_tag_name	str	Tag name for the sampling result.	required
metadata_key	str	Metadata key used as weights (float or int values).	required

multi_strategies

multi_strategies(
    n_samples_to_select: int,
    sampling_result_tag_name: str,
    sampling_strategies: list[SamplingStrategy],
) -> None

Select a subset based on multiple strategies.

Parameters:

Name	Type	Description	Default
n_samples_to_select	int	Number of samples to select.	required
sampling_result_tag_name	str	Tag name for the sampling result.	required
sampling_strategies	list[SamplingStrategy]	Strategies to compose for sampling.	required