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, use_int_coords=True)[source]

Selects a random point from an interior of a triangle.

Parameters
  • triangle (shapely.geometry.polygon.Polygon) – A triangle polygon.

  • rng (Optional[numpy.random._generator.Generator]) – A random numbers generator. If not provided it will be initialized without a seed.

  • use_int_coords (bool) – A flag deciding if only integer coordinates should be sampled.

Return type

shapely.geometry.point.Point

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

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

Parameters
  • image (numpy.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 (Optional[numpy.random._generator.Generator]) – A random numbers generator. If not provided it will be initialized without a seed.

  • replace (bool) – Whether to 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))[source]

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 (numpy.ndarray) – A 1-dimensional numpy array of row indices of sampled points

  • columns (numpy.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)[source]

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 (numpy.ndarray) – A 2-dimensional numpy array of row indices of all sampled points.

  • column_grid (numpy.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

numpy.ndarray

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

Bases: eolearn.core.eotask.EOTask

A base class for sampling tasks

Parameters
  • features_to_sample (an object supported by FeatureParser) – Features that will be spatially sampled according to given sampling parameters.

  • mask_of_samples ((FeatureType, str) or 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, **kwargs)[source]

Bases: eolearn.ml_tools.sampling.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 (an object supported by FeatureParser) – Features that will be spatially sampled according to given sampling parameters.

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

  • fraction (float or dict(int: float)) – Fraction of points to sample. Can be dictionary mapping values of mask to fractions.

  • exclude_values (list(int)) – Skips points that have these values in sampling_mask

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

  • kwargs – Arguments for BaseSamplingTask

execute(eopatch, *, seed=None, fraction=None)[source]

Execute random spatial sampling of specified features of eopatch

Parameters
  • eopatch (EOPatch) – Input eopatch to be sampled

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

  • fraction (float or dict(int: float) or 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

eolearn.core.eodata.EOPatch

class eolearn.ml_tools.sampling.BlockSamplingTask(features_to_sample, amount, sample_size=(1, 1), replace=False, **kwargs)[source]

Bases: eolearn.ml_tools.sampling.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 (an object supported by FeatureParser) – Features that will be spatially sampled according to given sampling parameters.

  • amount (int or 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) – Whether to sample with replacement. False means each value can only be chosen once.

  • kwargs – Arguments for BaseSamplingTask

execute(eopatch, *, seed=None, amount=None)[source]

Execute a spatial sampling on features from a given EOPatch

Parameters
  • eopatch (eolearn.core.eodata.EOPatch) – Input eopatch to be sampled

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

  • amount (Optional[numbers.Number]) – 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

eolearn.core.eodata.EOPatch

class eolearn.ml_tools.sampling.GridSamplingTask(features_to_sample, sample_size=(1, 1), stride=(1, 1), **kwargs)[source]

Bases: eolearn.ml_tools.sampling.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 (an object supported by FeatureParser) – 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.

  • kwargs – Arguments for BaseSamplingTask

execute(eopatch)[source]

Execute a spatial sampling on features from a given EOPatch

Parameters

eopatch (eolearn.core.eodata.EOPatch) – Input eopatch to be sampled

Returns

An EOPatch with additional spatially sampled features

Return type

eolearn.core.eodata.EOPatch