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