UFO
PoissonDiskThinningParameters.h
Go to the documentation of this file.
1 /*
2  * (C) Copyright 2019 Met Office UK
3  *
4  * This software is licensed under the terms of the Apache Licence Version 2.0
5  * which can be obtained at http://www.apache.org/licenses/LICENSE-2.0.
6  */
7 
8 #ifndef UFO_FILTERS_POISSONDISKTHINNINGPARAMETERS_H_
9 #define UFO_FILTERS_POISSONDISKTHINNINGPARAMETERS_H_
10 
11 #include <string>
12 #include <utility>
13 
14 #include "eckit/exception/Exceptions.h"
15 #include "oops/util/Duration.h"
16 #include "oops/util/parameters/OptionalParameter.h"
17 #include "oops/util/parameters/Parameter.h"
18 #include "oops/util/parameters/Parameters.h"
19 #include "oops/util/parameters/ParameterTraitsScalarOrMap.h"
21 
22 namespace eckit {
23  class Configuration;
24 }
25 
26 namespace ufo {
27 
30 };
31 
34  static constexpr char enumTypeName[] = "ExclusionVolumeShape";
35  static constexpr util::NamedEnumerator<ExclusionVolumeShape> namedValues[] = {
36  { ExclusionVolumeShape::CYLINDER, "cylinder" },
37  { ExclusionVolumeShape::ELLIPSOID, "ellipsoid" }
38  };
39 };
40 
41 } // namespace ufo
42 
43 namespace oops {
44 
45 template <>
46 struct ParameterTraits<ufo::ExclusionVolumeShape> :
47  public EnumParameterTraits<ufo::ExclusionVolumeShapeParameterTraitsHelper>
48 {};
49 
50 } // namespace oops
51 
52 namespace ufo {
53 
54 /// \brief Options controlling the operation of the PoissonDiskThinning filter.
55 ///
56 /// \note The descriptions of several options refer to the _exclusion volume_, which is a domain
57 /// surrounding the location of each observation. If an observation is retained, then no other
58 /// observations lying in the interior of its exclusion volume may be retained at the same time.
59 class PoissonDiskThinningParameters : public oops::Parameters {
60  OOPS_CONCRETE_PARAMETERS(PoissonDiskThinningParameters, Parameters)
61 
62  public:
63  typedef int Priority;
64 
65  // Exclusion volume
66 
67  /// Size of the exclusion volume in the horizontal direction (in km).
68  ///
69  /// If the priority_variable parameter is not set and hence all observations have the same
70  /// priority, this parameter must be a floating-point constant. Otherwise it may also be a map
71  /// assigning an exclusion volume size to each observation priority. Exclusion volumes of
72  /// lower-priority observations must be at least as large as those of higher-priority ones.
73  /// If this parameter is not set, horizontal position is ignored during thinning.
74  ///
75  /// \note Owing to a bug in the eckit YAML parser, maps need to be written in the JSON style,
76  /// with keys quoted. Example:
77  ///
78  /// min_horizontal_spacing: {"1": 123, "2": 321}
79  ///
80  /// This will not work:
81  ///
82  /// min_horizontal_spacing: {1: 123, 2: 321}
83  ///
84  /// and neither will this:
85  ///
86  /// min_horizontal_spacing:
87  /// 1: 123
88  /// 2: 321
89  ///
90  /// or this:
91  ///
92  /// min_horizontal_spacing:
93  /// "1": 123
94  /// "2": 321
95  oops::OptionalParameter<util::ScalarOrMap<Priority, float>> minHorizontalSpacing{
96  "min_horizontal_spacing", this};
97 
98  /// Size of the exclusion volume in the vertical direction (in Pa).
99  ///
100  /// Like min_horizontal_spacing, this can be either a constant or a map.
101  oops::OptionalParameter<util::ScalarOrMap<Priority, float>> minVerticalSpacing{
102  "min_vertical_spacing", this};
103 
104  /// Size of the exclusion volume in the temporal direction.
105  ///
106  /// Like min_horizontal_spacing, this can be either a constant or a map.
107  oops::OptionalParameter<util::ScalarOrMap<Priority, util::Duration>> minTimeSpacing{
108  "min_time_spacing", this};
109 
110  /// Shape of the exclusion volume surrounding each observation.
111  ///
112  /// Allowed values:
113  /// - \c cylinder: the exclusion volume of an observation taken at latitude lat, longitude lon,
114  /// pressure p and time t is the set of all locations (lat', lon', p', t') for which all of
115  /// the following conditions are met:
116  /// * the geodesic distance between (lat, lon) and (lat', lon') is smaller than
117  /// min_horizontal_spacing
118  /// * |p - p'| < min_vertical_spacing
119  /// * |t - t'| < min_time_spacing.
120  /// - \c ellipsoid: the exclusion volume of an observation taken at latitude lat, longitude lon,
121  /// pressure p and time t is the set of all locations (lat', lon', p', t') for which
122  /// the following condition is met:
123  /// * geodesic_distance((lat, lon), (lat', lon'))^2 / min_horizontal_spacing^2 +
124  /// (p - p')^2 / min_vertical_spacing^2 + (t - t')^2 / min_time_spacing^2 < 1.
125  oops::Parameter<ExclusionVolumeShape> exclusionVolumeShape{"exclusion_volume_shape",
127 
128  // Observation categories
129 
130  /// Variable storing integer-valued IDs associated with observations. Observations belonging
131  /// to different categories are thinned separately.
132  oops::OptionalParameter<Variable> categoryVariable{"category_variable", this};
133 
134  // Selection of observations to retain
135 
136  /// Variable storing observation priorities. An observation will not be retained if it lies
137  /// within the exclusion volume of an observation with a higher priority.
138  ///
139  /// As noted in the documentation of min_horizontal_spacing, the exclusion volume size must be a
140  /// (weakly) monotonically decreasing function of observation priority, i.e. the exclusion volumes
141  /// of all observations with the same priority must have the same size, and the exclusion volumes
142  /// of lower-priority observations must be at least as large as those of higher-priority ones.
143  ///
144  /// If this parameter is not set, all observations are assumed to have equal priority.
145  oops::OptionalParameter<Variable> priorityVariable{"priority_variable", this};
146 
147  /// If true, observations will be randomly shuffled before being inspected as candidates
148  /// for retaining.
149  ///
150  /// \note It is recommended to leave shuffling enabled in production code, since the performance
151  /// of the spatial point index (kd-tree) used in the filter's implementation may be degraded if
152  /// observation locations are ordered largely monotonically (and random shuffling essentially
153  /// prevents that from happening).
154  oops::Parameter<bool> shuffle{"shuffle", true, this};
155 
156  /// Seed with which to initialize the random number generator used to shuffle the observations
157  /// if \p shuffle is set to true.
158  ///
159  /// If omitted, a seed will be generated based on the current (calendar) time.
160  oops::OptionalParameter<int> randomSeed{"random_seed", this};
161 };
162 
163 } // namespace ufo
164 
165 #endif // UFO_FILTERS_POISSONDISKTHINNINGPARAMETERS_H_
ufo::ExclusionVolumeShapeParameterTraitsHelper::namedValues
static constexpr util::NamedEnumerator< ExclusionVolumeShape > namedValues[]
Definition: PoissonDiskThinningParameters.h:35
oops
Definition: GaussianThinningParameters.h:42
ufo::PoissonDiskThinningParameters::exclusionVolumeShape
oops::Parameter< ExclusionVolumeShape > exclusionVolumeShape
Definition: PoissonDiskThinningParameters.h:125
ufo::PoissonDiskThinningParameters::randomSeed
oops::OptionalParameter< int > randomSeed
Definition: PoissonDiskThinningParameters.h:160
ufo::ExclusionVolumeShapeParameterTraitsHelper::EnumType
ExclusionVolumeShape EnumType
Definition: PoissonDiskThinningParameters.h:33
ufo::PoissonDiskThinningParameters::minVerticalSpacing
oops::OptionalParameter< util::ScalarOrMap< Priority, float > > minVerticalSpacing
Definition: PoissonDiskThinningParameters.h:101
ufo::ExclusionVolumeShape::ELLIPSOID
@ ELLIPSOID
ufo::PoissonDiskThinningParameters::shuffle
oops::Parameter< bool > shuffle
Definition: PoissonDiskThinningParameters.h:154
ufo::PoissonDiskThinningParameters::categoryVariable
oops::OptionalParameter< Variable > categoryVariable
Definition: PoissonDiskThinningParameters.h:132
ufo::PoissonDiskThinningParameters::minHorizontalSpacing
oops::OptionalParameter< util::ScalarOrMap< Priority, float > > minHorizontalSpacing
Definition: PoissonDiskThinningParameters.h:95
ufo::ExclusionVolumeShapeParameterTraitsHelper
Definition: PoissonDiskThinningParameters.h:32
ufo
Definition: RunCRTM.h:27
ufo::PoissonDiskThinningParameters::Priority
int Priority
Definition: PoissonDiskThinningParameters.h:63
eckit
Forward declarations.
Definition: ObsAtmSfcInterp.h:20
ufo::ExclusionVolumeShapeParameterTraitsHelper::enumTypeName
static constexpr char enumTypeName[]
Definition: PoissonDiskThinningParameters.h:34
ufo::ExclusionVolumeShape
ExclusionVolumeShape
Definition: PoissonDiskThinningParameters.h:28
ufo::PoissonDiskThinningParameters
Options controlling the operation of the PoissonDiskThinning filter.
Definition: PoissonDiskThinningParameters.h:59
ufo::PoissonDiskThinningParameters::minTimeSpacing
oops::OptionalParameter< util::ScalarOrMap< Priority, util::Duration > > minTimeSpacing
Definition: PoissonDiskThinningParameters.h:107
ufo::ExclusionVolumeShape::CYLINDER
@ CYLINDER
ufo::PoissonDiskThinningParameters::priorityVariable
oops::OptionalParameter< Variable > priorityVariable
Definition: PoissonDiskThinningParameters.h:145
ParameterTraitsVariable.h