MultiImageSamplingRate - Multi-image sampling rate estimation¶
Compute sampling rate for an input set of images.
Detailed description¶
The application computes sampling rates for a set of input images. Before calling this application, each pair of image and training vectors has to be analysed with the application PolygonClassStatistics. The statistics file is then used to compute the sampling rates for each class in each image. Several types of sampling are implemented. Each one is a combination of a mono-image strategy and a multi-image mode. The mono-image strategies are :
- smallest (default) : select the same number of sample in each class so that the smallest one is fully sampled.
- constant : select the same number of samples N in each class (with N below or equal to the size of the smallest class).
- byclass : set the required number for each class manually, with an input CSV file (first column is class name, second one is the required samples number).
- The multi-image modes (mim) are proportional, equal and custom. The custom mode lets the users choose the distribution of samples among the images. The different behaviours are described below. Ti(c) and Ni(c) refers resp. to the total number and needed number of samples in image i for class c. Let’s call L the total number of images.
- strategy = all
- Same behaviour for all modes : take all samples
- strategy = constant : let’s call M the global number of samples required per class. For each image i and each class c:
- if mim = proportional, then Ni( c ) = M * Ti( c ) / sum_k( Tk(c) )
- if mim = equal , then Ni( c ) = M / L
- if mim = custom , then Ni( c ) = Mi where Mi is the custom requested number of samples for image i
- strategy = byClass : let’s call M(c) the global number of samples for class c). For each image i and each class c:
- if mim = proportional, then Ni( c ) = M(c) * Ti( c ) / sum_k( Tk(c) )
- if mim = equal , then Ni( c ) = M(c) / L
- if mim = custom , then Ni( c ) = Mi(c) where Mi(c) is the custom requested number of samples for image i and class c
- strategy = percent : For each image i and each class c:
- if mim = proportional, then Ni( c ) = p * Ti( c ) where p is the global percentage of samples
- if mim = equal , then Ni( c ) = p * sum_k(Tk(c)]/L where p is the global percentage of samples
- if mim = custom , then Ni( c ) = p(i) * Ti(c) where p(i) is the percentage of samples for image i. c
- strategy = total : For each image i and each class c:
- if mim = proportional, then Ni( c ) = total * (sum_k(Ti(k))/sum_kl(Tl(k))) * (Ti(c)/sum_k(Ti(k))) where total is the total number of samples specified.
- if mim = equal , then Ni( c ) = (total / L) * (Ti(c)/sum_k(Ti(k))) where total is the total number of samples specified.
- if mim = custom , then Ni( c ) = total(i) * (Ti(c)/sum_k(Ti(k))) where total(i) is the total number of samples specified for image i.
- strategy = smallest class
- if mim = proportional, then the smallest class size (computed globally) is used for the strategy constant+proportional.
- if mim = equal , then the smallest class size (computed globally) is used for the strategy constant+equal.
- if mim = custom , then the smallest class is computed and used for each image separately.
- strategy = all
Parameters¶
This section describes in details the parameters available for this application. Table [1] presents a summary of these parameters and the parameters keys to be used in command-line and programming languages. Application key is MultiImageSamplingRate .
| [1] | Table: Parameters table for Multi-image sampling rate estimation. |
| Parameter Key | Parameter Name | Parameter Type |
|---|---|---|
| il | Input statistics | Input File name list |
| out | Output sampling rates | Output File name |
| strategy | Sampling strategy | Choices |
| strategy byclass | Set samples count for each class | Choice |
| strategy constant | Set the same samples counts for all classes | Choice |
| strategy smallest | Set same number of samples for all classes, with the smallest class fully sampled | Choice |
| strategy percent | Use a percentage of the samples available for each class | Choice |
| strategy total | Set the total number of samples to generate, and use class proportions. | Choice |
| strategy all | Take all samples | Choice |
| strategy.byclass.in | Number of samples by class | Input File name list |
| strategy.constant.nb | Number of samples for all classes | String |
| strategy.percent.p | The percentage(s) to use | String |
| strategy.total.v | The number of samples to generate | String |
| mim | Multi-Image Mode | Choices |
| mim proportional | Proportional | Choice |
| mim equal | equal | Choice |
| mim custom | Custom | Choice |
| inxml | Load otb application from xml file | XML input parameters file |
| outxml | Save otb application to xml file | XML output parameters file |
Input statistics: List of statistics files for each input image.
Output sampling rates: Output filename storing sampling rates (CSV format with class name, required samples, total samples, and rate). The given filename will be used with a suffix to indicate the corresponding input index (for instance: rates.csv will give rates_1.csv, rates_2.csv, ...).
Sampling strategy Available choices are:
- Set samples count for each class: Set samples count for each class.
- Number of samples by class: Number of samples by class (CSV format with class name in 1st column and required samples in the 2nd).In the case of the custom multi-image mode, several inputs may be given for each image.
- Set the same samples counts for all classes: Set the same samples counts for all classes.
- Number of samples for all classes: Number of samples for all classes.In the case of the custom multi-image mode, several values can be given for each image.
- Set same number of samples for all classes, with the smallest class fully sampled: Set same number of samples for all classes, with the smallest class fully sampled.
- Use a percentage of the samples available for each class: Use a percentage of the samples available for each class.
- The percentage(s) to use: The percentage(s) to use In the case of the custom multi-image mode, several values can be given for each image.
- Set the total number of samples to generate, and use class proportions.: Set the total number of samples to generate, and use class proportions.
- The number of samples to generate: The number of samples to generateIn the case of the custom multi-image mode, several values can be given for each image.
- Take all samples: Take all samples.
Multi-Image Mode Available choices are:
- Proportional: Split proportionally the required number of samples.
- equal: Split equally the required number of samples.
- Custom: Split the required number of samples following user choice.
Load otb application from xml file: Load otb application from xml file.
Save otb application to xml file: Save otb application to xml file.
Example¶
To run this example in command-line, use the following:
otbcli_MultiImageSamplingRate -il stats_1.xml stats_2.xml -out rates.csv -strategy smallest -mim proportional
To run this example from Python, use the following code snippet:
#!/usr/bin/python
# Import the otb applications package
import otbApplication
# The following line creates an instance of the MultiImageSamplingRate application
MultiImageSamplingRate = otbApplication.Registry.CreateApplication("MultiImageSamplingRate")
# The following lines set all the application parameters:
MultiImageSamplingRate.SetParameterString("out", "rates.csv")
MultiImageSamplingRate.SetParameterString("strategy","smallest")
MultiImageSamplingRate.SetParameterString("mim","proportional")
# The following line execute the application
MultiImageSamplingRate.ExecuteAndWriteOutput()
Limitations¶
None
Authors¶
This application has been written by OTB-Team.