eolearn.ml_tools.sampling

Tasks for spatial sampling of points for building training/validation samples for example.

eolearn.ml_tools.sampling.random_point_in_triangle(triangle, rng=None)

Selects a random point from an interior of a triangle.

Parameters:

• triangle (Polygon) – A triangle polygon.

• rng (Generator | None) – A random numbers generator. If not provided it will be initialized without a seed.

Return type:

Point

eolearn.ml_tools.sampling.sample_by_values(image, n_samples_per_value, rng=None, replace=False)

Sample points from image with the amount of samples specified for each value.

Parameters:

• image (ndarray) – A 2-dimensional numpy array

• n_samples_per_value (dict[int, int]) – A dictionary specifying the amount of samples per value. Values that are not in the dictionary will not be sampled.

• rng (Generator | None) – A random numbers generator. If not provided it will be initialized without a seed.

• replace (bool) – Sample with replacement. False means each value can only be chosen once.

Returns:

A pair of numpy arrays first one containing row indices and second one containing column indices of sampled points.

Return type:

tuple[numpy.ndarray, numpy.ndarray]

eolearn.ml_tools.sampling.expand_to_grids(rows, columns, sample_size=(1, 1))

Expands sampled points into blocks and returns a pair of arrays. Each array represents a grid of indices of pixel locations, the first one row indices and the second one column indices. Each array is of shape (N * sample_height, sample_width), where each element represent a row or column index in an original array of dimensions (height, width). The grid arrays can then be used to transform the original array into a sampled array of shape (N * sample_height, sample_width).

Parameters:

• rows (ndarray) – A 1-dimensional numpy array of row indices of sampled points

• columns (ndarray) – A 1-dimensional numpy array of column indices of sampled points

• sample_size (tuple[int, int]) – A size of sampled blocks to which sampled points will be extended. The given input points will be upper left points of created blocks.

Returns:

A pair of 2-dimensional numpy arrays. The first contains a grid of row indices and the second one contains a grid of column indices of all points in sampled blocks

Return type:

tuple[numpy.ndarray, numpy.ndarray]

eolearn.ml_tools.sampling.get_mask_of_samples(image_shape, row_grid, column_grid)

Creates a mask of counts how many times each pixel has been sampled.

Parameters:

• image_shape (tuple[int, int]) – Height and width of a sampled image.

• row_grid (ndarray) – A 2-dimensional numpy array of row indices of all sampled points.

• column_grid (ndarray) – A 2-dimensional numpy array of column indices of all sampled points.

Returns:

An image mask where each pixel is assigned a count of how many times it was sampled.

Return type:

ndarray

class eolearn.ml_tools.sampling.BaseSamplingTask(features_to_sample, *, mask_of_samples=None)

Bases: EOTask

A base class for sampling tasks

Parameters:

• features_to_sample (FeaturesSpecification) – Features that will be spatially sampled according to given sampling parameters.

• mask_of_samples (Feature | None) – An output mask timeless feature of counts how many times each pixel has been sampled.

class eolearn.ml_tools.sampling.FractionSamplingTask(features_to_sample, sampling_feature, fraction, exclude_values=None, replace=False, mask_of_samples=None)

Bases: BaseSamplingTask

The main task for pixel-based sampling that samples a fraction of viable points determined by a mask feature.

The task aims to preserve the value distribution of the mask feature in the samples. Values can be excluded and the process can also be fine-tuned by passing a dictionary of fractions for each value of the mask feature.

Parameters:

• features_to_sample (FeaturesSpecification) – Features that will be spatially sampled according to given sampling parameters.

• sampling_feature (Feature) – A timeless mask feature according to which points will be sampled.

• fraction (_FractionType) – Fraction of points to sample. Can be dictionary mapping values of mask to fractions.

• exclude_values (list[int] | None) – Skips points that have these values in sampling_mask

• replace (bool) – Sample with replacement. False means each value can only be chosen once.

• mask_of_samples (Feature | None) – An output mask timeless feature of counts how many times each pixel has been sampled.

execute(eopatch, *, seed=None, fraction=None)

Execute random spatial sampling of specified features of eopatch

Parameters:

• eopatch (EOPatch) – Input eopatch to be sampled

• seed (int | None) – Setting seed of random sampling. If None a random seed will be used.

• fraction (float | Dict[int, float] | None) – Override the sampling fraction of the task. If None the value from task initialization will be used.

Returns:

An EOPatch with additional spatially sampled features

Return type:

EOPatch

class eolearn.ml_tools.sampling.BlockSamplingTask(features_to_sample, amount, sample_size=(1, 1), replace=False, mask_of_samples=None)

Bases: BaseSamplingTask

A task to randomly sample pixels or blocks of any size.

The task has no option to add data validity masks, because when sampling a fixed amount of objects it can cause uneven distribution density across different eopatches. For any purposes that require fine-tuning use FractionSamplingTask instead.

Parameters:

• features_to_sample (FeaturesSpecification) – Features that will be spatially sampled according to given sampling parameters.

• amount (float) – The number of points to sample if integer valued and the fraction of all points if float

• sample_size (tuple[int, int]) – A tuple describing a size of sampled blocks. The size is defined as a tuple of number of rows and number of columns.

• replace (bool) – Sample with replacement. False means each value can only be chosen once.

• mask_of_samples (Feature | None) – An output mask timeless feature of counts how many times each pixel has been sampled.

execute(eopatch, *, seed=None, amount=None)

Execute a spatial sampling on features from a given EOPatch

Parameters:

• eopatch (EOPatch) – Input eopatch to be sampled

• seed (int | None) – Setting seed of random sampling. If None a random seed will be used.

• amount (float | None) – A number of points to sample if integer valued and a fraction of all points if float. If None the value from task initialization will be used.

Returns:

An EOPatch with additional spatially sampled features

Return type:

EOPatch

class eolearn.ml_tools.sampling.GridSamplingTask(features_to_sample, sample_size=(1, 1), stride=(1, 1), mask_of_samples=None)

Bases: BaseSamplingTask

A task to sample blocks of a given size in a regular grid.

This task doesn’t use any randomness and always produces the same results.

Parameters:

• features_to_sample (FeaturesSpecification) – Features that will be spatially sampled according to given sampling parameters.

• sample_size (tuple[int, int]) – A tuple describing a size of sampled blocks. The size is defined as a tuple of number of rows and number of columns.

• stride (tuple[int, int]) – A tuple describing a distance between upper left corners of two consecutive sampled blocks. The first number is the vertical distance and the second number the horizontal distance. If stride in smaller than sample_size in any dimensions then sampled blocks will overlap.

• mask_of_samples (Feature | None) – An output mask timeless feature of counts how many times each pixel has been sampled.

execute(eopatch)

Execute a spatial sampling on features from a given EOPatch

Parameters:

eopatch (EOPatch) – Input eopatch to be sampled

Returns:

An EOPatch with additional spatially sampled features

Return type:

EOPatch