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)[source]
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)[source]
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) – 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 (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)[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 (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)[source]
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)[source]
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) – Whether to 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)[source]
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:
- class eolearn.ml_tools.sampling.BlockSamplingTask(features_to_sample, amount, sample_size=(1, 1), replace=False, mask_of_samples=None)[source]
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) – Whether to 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)[source]
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:
- class eolearn.ml_tools.sampling.GridSamplingTask(features_to_sample, sample_size=(1, 1), stride=(1, 1), mask_of_samples=None)[source]
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.