001/*
002 *    GeoAPI - Java interfaces for OGC/ISO standards
003 *    Copyright © 2022-2023 Open Geospatial Consortium, Inc.
004 *    http://www.geoapi.org
005 *
006 *    Licensed under the Apache License, Version 2.0 (the "License");
007 *    you may not use this file except in compliance with the License.
008 *    You may obtain a copy of the License at
009 *
010 *        http://www.apache.org/licenses/LICENSE-2.0
011 *
012 *    Unless required by applicable law or agreed to in writing, software
013 *    distributed under the License is distributed on an "AS IS" BASIS,
014 *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 *    See the License for the specific language governing permissions and
016 *    limitations under the License.
017 */
018package org.opengis.metadata.quality;
019
020import javax.measure.Quantity;
021import org.opengis.util.InternationalString;
022import org.opengis.util.TypeName;
023import org.opengis.annotation.UML;
024
025import static org.opengis.annotation.Obligation.*;
026import static org.opengis.annotation.Specification.*;
027
028
029/**
030 * Data quality basic measure.
031 * This concept is used to avoid the repetitive definition of the same concept.
032 * For example, many data quality measures are dealing with the concept of counting errors.
033 * Basic measures are used for the creation of data quality measures that share these commonalities.
034 *
035 * <h2>Standardized values</h2>
036 * Two principle categories of data quality basic measures are listed in ISO 19157 annex.
037 * The counting-related data quality basic measures are based on the concept of counting errors or correct items.
038 * The uncertainty-related data quality basic measures are based on the concept of modeling the uncertainty of
039 * measurements with statistical methods. The following table provides a non-exhaustive summary;
040 * see ISO 19157 for more complete descriptions and formulas.
041 * All identifiers should be in "ISO 19157" namespace.
042 *
043 * <table class="ogc">
044 *   <caption>Standardized basic measures derived from ISO 19157</caption>
045 *   <tr>
046 *     <th>{@linkplain #getName() Name}</th>
047 *     <th>{@linkplain #getDefinition() definition}</th>
048 *     <th>{@linkplain #getValueType() Value type}</th>
049 *   </tr><tr>
050 *     <td>Error indicator</td>
051 *     <td>Indicator that an item is in error</td>
052 *     <td>Boolean</td>
053 *   </tr><tr>
054 *     <td>Correctness indicator</td>
055 *     <td>Indicator that an item is correct</td>
056 *     <td>Boolean</td>
057 *   </tr><tr>
058 *     <td>Error count</td>
059 *     <td>Total number of items that are subject to an error of a specified type</td>
060 *     <td>Integer</td>
061 *   </tr><tr>
062 *     <td>Error rate</td>
063 *     <td>Number of the erroneous items with respect to the total number of items that should have been present</td>
064 *     <td>Real</td>
065 *   </tr><tr>
066 *     <td>Correct items rate</td>
067 *     <td>Number of the correct items with respect to the total number of items that should have been present</td>
068 *     <td>Real</td>
069 *   </tr><tr>
070 *     <td>LE50</td>
071 *     <td>Value uncertainty at 50% significance level</td>
072 *     <td>{@link Quantity}</td>
073 *   </tr><tr>
074 *     <td>LE68.3</td>
075 *     <td>Value uncertainty at 68.3% significance level</td>
076 *     <td>{@link Quantity}</td>
077 *   </tr><tr>
078 *     <td>LE90</td>
079 *     <td>Value uncertainty at 90% significance level</td>
080 *     <td>{@link Quantity}</td>
081 *   </tr><tr>
082 *     <td>LE95</td>
083 *     <td>Value uncertainty at 95% significance level</td>
084 *     <td>{@link Quantity}</td>
085 *   </tr><tr>
086 *     <td>LE99</td>
087 *     <td>Value uncertainty at 99% significance level</td>
088 *     <td>{@link Quantity}</td>
089 *   </tr><tr>
090 *     <td>LE99.8</td>
091 *     <td>Value uncertainty at 99.8% significance level</td>
092 *     <td>{@link Quantity}</td>
093 *   </tr><tr>
094 *     <td>LE50(r)</td>
095 *     <td>Like LE50 where the standard deviation is estimated from redundant measurements</td>
096 *     <td>{@link Quantity}</td>
097 *   </tr><tr>
098 *     <td>LE68.3(r)</td>
099 *     <td>Like LE68.3 where the standard deviation is estimated from redundant measurements</td>
100 *     <td>{@link Quantity}</td>
101 *   </tr><tr>
102 *     <td>LE90(r)</td>
103 *     <td>Like LE90 where the standard deviation is estimated from redundant measurements</td>
104 *     <td>{@link Quantity}</td>
105 *   </tr><tr>
106 *     <td>LE95(r)</td>
107 *     <td>Like LE95 where the standard deviation is estimated from redundant measurements</td>
108 *     <td>{@link Quantity}</td>
109 *   </tr><tr>
110 *     <td>LE99(r)</td>
111 *     <td>Like LE99 where the standard deviation is estimated from redundant measurements</td>
112 *     <td>{@link Quantity}</td>
113 *   </tr><tr>
114 *     <td>LE99.8(r)</td>
115 *     <td>Like LE99.8 where the standard deviation is estimated from redundant measurements</td>
116 *     <td>{@link Quantity}</td>
117 *   </tr><tr>
118 *     <td>CE39.4</td>
119 *     <td>Circular error at 39.4% significant level</td>
120 *     <td>{@link Quantity}</td>
121 *   </tr><tr>
122 *     <td>CE50</td>
123 *     <td>Circular error at 50% significant level</td>
124 *     <td>{@link Quantity}</td>
125 *   </tr><tr>
126 *     <td>CE90</td>
127 *     <td>Circular error at 90% significant level</td>
128 *     <td>{@link Quantity}</td>
129 *   </tr><tr>
130 *     <td>CE95</td>
131 *     <td>Circular error at 95% significant level</td>
132 *     <td>{@link Quantity}</td>
133 *   </tr><tr>
134 *     <td>CE99.8</td>
135 *     <td>Circular error at 99.8% significant level</td>
136 *     <td>{@link Quantity}</td>
137 *   </tr><tr>
138 *     <td>SEP</td>
139 *     <td>Spherical error probable</td>
140 *     <td>{@link Quantity}</td>
141 *   </tr><tr>
142 *     <td>MRSE</td>
143 *     <td>Mean radial spherical error</td>
144 *     <td>{@link Quantity}</td>
145 *   </tr><tr>
146 *     <td></td>
147 *     <td>90% spherical accuracy standard</td>
148 *     <td>{@link Quantity}</td>
149 *   </tr><tr>
150 *     <td></td>
151 *     <td>99% spherical accuracy standard</td>
152 *     <td>{@link Quantity}</td>
153 *   </tr>
154 * </table>
155 *
156 * <p><b>Note:</b> rates can either be presented as percentage or as a ratio. The value unit in the
157 * quantitative result can be used to specify that the result is presented in percentage or as a ratio.</p>
158 *
159 * @author  Alexis Gaillard (Geomatys)
160 * @author  Martin Desruisseaux (Geomatys)
161 * @version 3.1
162 * @since   3.1
163 */
164@UML(identifier="DQM_BasicMeasure", specification=ISO_19157)
165public interface BasicMeasure {
166    /**
167     * Name of the data quality basic measure applied to the data.
168     *
169     * @return name of the data quality basic measure.
170     *
171     * @see Measure#getName()
172     */
173    @UML(identifier="name", obligation=MANDATORY, specification=ISO_19157)
174    InternationalString getName();
175
176    /**
177     * Definition of the data quality basic measure.
178     *
179     * @return definition of the data quality basic measure.
180     *
181     * @see Measure#getDefinition()
182     */
183    @UML(identifier="definition", obligation=MANDATORY, specification=ISO_19157)
184    InternationalString getDefinition();
185
186    /**
187     * Illustration of the use of a data quality measure.
188     *
189     * @return usage example, or {@code null} if none.
190     *
191     * @see Measure#getExamples()
192     */
193    @UML(identifier="example", obligation=OPTIONAL, specification=ISO_19157)
194    default Description getExample() {
195        return null;
196    }
197
198    /**
199     * Value type for the result of the basic measure.
200     *
201     * @return value type of the result for the basic measure.
202     *
203     * @see Measure#getValueType()
204     */
205    @UML(identifier="valueType", obligation=MANDATORY, specification=ISO_19157)
206    TypeName getValueType();
207}