/[escript]/trunk/doc/inversion/DataSources.tex
ViewVC logotype

Contents of /trunk/doc/inversion/DataSources.tex

Parent Directory Parent Directory | Revision Log Revision Log


Revision 4160 - (show annotations)
Thu Jan 24 00:13:32 2013 UTC (6 years, 6 months ago) by caltinay
File MIME type: application/x-tex
File size: 11376 byte(s)
Moved figures to subdir and added more DataSource doco.

1 \chapter{Data Sources}\label{Chp:ref:data sources}
2
3 At the source of every inversion is data in the form of gravity anomaly or
4 magnetic flux density values for at least a part of the region of interest.
5 These usually come from surveys and are preprocessed to correct for various
6 factors and distortions.
7 This chapter provides an overview of the classes related to data input for
8 inversions.
9
10 \section{Overview}
11 The inversion module comes with a number of classes that can read gridded
12 (raster) data on a 2-dimensional plane from file or provide artificial values
13 for testing purposes. These classes all derive from the abstract
14 \class{DataSource} class and override methods that return information about
15 the data and the values themselves.
16 The \class{DomainBuilder} class is responsible for creating an \escript domain
17 with a suitable grid spacing and spatial extents that include all data sources
18 attached to it (see Figure~\ref{fig:domainBuilder}).
19 %
20 \begin{figure}[ht]
21 \centering\includegraphics{domainbuilder}
22 \caption{\class{DataSource} instances are added to a \class{DomainBuilder}
23 which creates a suitable domain and \Data objects for the inversion}
24 \label{fig:domainBuilder}
25 \end{figure}
26 %
27 Notice that in the figure there are cells in the region of interest that are
28 not covered by any data source instance.
29 Ideally, all data sources used for an inversion have the same spatial resolution
30 and are spatially adjacent so that all cells have a value but this is not a
31 requirement.
32
33
34 \section{Domain Builder}\label{Chp:ref:domain builder}
35 Every inversion requires one \class{DomainBuilder} instance which creates and
36 holds a reference to the \escript domain as well as associated \Data objects for
37 the input data used for the inversion.
38 The class has the following public methods:
39
40 \begin{classdesc}{DomainBuilder}{\optional{dim=3}}
41 Constructor for the domain builder. \member{dim} sets the dimensionality of the
42 target domain and must be 2 or 3. By default a 3-dimensional domain is created.
43 \end{classdesc}
44
45 \begin{methoddesc}[DomainBuilder]{addSource}{source}
46 adds survey data \member{source} (a \class{DataSource} object) to the domain
47 builder. The dimensionality of the data must be less than or equal to the
48 domain dimensionality.
49 \end{methoddesc}
50
51 \begin{methoddesc}[DomainBuilder]{setVerticalExtents}{%
52 \optional{depth=40000.}%
53 \optional{, air_layer=10000.}%
54 \optional{, num_cells=25}}
55 sets the parameters for the vertical dimension of the domain. The parameter
56 \member{depth} specifies the thickness in meters of the subsurface layer
57 ($-x_2^{min}$ in Figure~\ref{fig:cartesianDomain}).
58 The default value of $40$ km is usually appropriate. Similarly, the
59 \member{air_layer} parameter defines the buffer zone thickness above the surface
60 ($x_2^{max}$ in Figure~\ref{fig:cartesianDomain}) which should be a few
61 kilometres to avoid artefacts in the inversion.
62 The number of elements (or cells) in the vertical dimension is set with the
63 \member{num_cells} parameter. Consider the size and resolution of your datasets,
64 the total vertical length (=\member{depth}+\member{air_layer}) and available
65 compute resources when setting this value.
66 \end{methoddesc}
67
68 \begin{methoddesc}[DomainBuilder]{setFractionalPadding}{%
69 \optional{pad_x=\None}%
70 \optional{, pad_y=\None}}
71 sets the amount of padding around the dataset as a fraction of the dataset side
72 lengths.
73 For example, calling \member{setFractionalPadding(0.2, 0.1)} with a data source
74 of size $10 \times 20$ will result in the padded data set size $14 \times 24$
75 (that is $10 \times (1+2 \times 0.2)$ and $20 \times (1+2 \times 0.1)$).
76 By default no padding is applied and \member{pad_y} is ignored for 2-dimensional
77 domains.
78 \end{methoddesc}
79
80 \begin{methoddesc}[DomainBuilder]{setPadding}{%
81 \optional{pad_x=\None}%
82 \optional{, pad_y=\None}}
83 sets the amount of padding around the dataset in absolute length units.
84 The final domain size will be the length in x (in y) of the dataset plus twice
85 the value of \member{pad_x} (\member{pad_y}). The arguments must be non-negative.
86 By default no padding is applied and \member{pad_y} is ignored for 2-dimensional
87 domains.
88 \end{methoddesc}
89
90 \begin{methoddesc}[DomainBuilder]{setElementPadding}{%
91 \optional{pad_x=\None}%
92 \optional{, pad_y=\None}}
93 sets the amount of padding around the dataset in number of elements (cells).
94 When the domain is constructed \member{pad_x} (\member{pad_y}) elements are
95 added on each side of the x- (y-) dimension. The arguments must be non-negative.
96 By default no padding is applied and \member{pad_y} is ignored for 2-dimensional
97 domains.
98 \end{methoddesc}
99
100 \begin{methoddesc}[DomainBuilder]{fixDensityBelow}{%
101 \optional{depth=\None}}
102 defines the depth below which the density anomaly is fixed to zero.
103 This method is only useful for inversions that involve gravity data.
104 \end{methoddesc}
105
106 \begin{methoddesc}[DomainBuilder]{fixSusceptibilityBelow}{%
107 \optional{depth=\None}}
108 defines the depth below which the susceptibility anomaly is fixed to zero.
109 This method is only useful for inversions that involve magnetic data.
110 \end{methoddesc}
111
112 \begin{methoddesc}[DomainBuilder]{getGravitySurveys}{}
113 returns a list of all gravity surveys added to the domain builder. See
114 \member{getSurveys()} for more details.
115 \end{methoddesc}
116
117 \begin{methoddesc}[DomainBuilder]{getMagneticSurveys}{}
118 returns a list of all magnetic surveys added to the domain builder. See
119 \member{getSurveys()} for more details.
120 \end{methoddesc}
121
122 \begin{methoddesc}[DomainBuilder]{getSurveys}{datatype}
123 returns a list of surveys of type \member{datatype} available to this domain
124 builder. In the current implementation each survey is a tuple of two \Data
125 objects, the first containing anomaly values and the second standard error
126 values for the survey.
127 \end{methoddesc}
128
129 \begin{methoddesc}[DomainBuilder]{getDomain}{}
130 returns an \escript domain (see~\cite{ESCRIPT}) suitable for running inversions
131 on the attached data sources.
132 The first time this method is called the target parameters (such as resolution,
133 extents and number of elements) are computed, and the domain is created.
134 Subsequent calls return the same domain instance so calls to
135 \member{setPadding()}, \member{addSource()} and other methods that influence
136 the domain will fail once \member{getDomain()} is called the first time.
137 \end{methoddesc}
138
139 \begin{methoddesc}[DomainBuilder]{setBackgroundMagneticFluxDensity}{B}
140 sets the background magnetic flux density $B=(B_r,B_\theta,B_\phi)$ which is
141 required for magnetic inversions.
142 A implementation of the dipole approximation as described in
143 Equation~\ref{ref:MAG:EQU:5} is provided through the function
144 \member{simpleGeoMagneticFluxDensity} (see Section~\ref{sec:ref:DataSource}).
145 $B_\theta$ is ignored for 2-dimensional magnetic inversions.
146 \end{methoddesc}
147
148 \begin{methoddesc}[DomainBuilder]{getBackgroundMagneticFluxDensity}{}
149 returns the background magnetic flux density $B$ set via
150 \member{setBackgroundMagneticFluxDensity()} in a form suitable for the inversion.
151 There should be no need to call this method directly.
152 \end{methoddesc}
153
154 \begin{methoddesc}[DomainBuilder]{getSetDensityMask}{}
155 returns the density mask \Data object which is non-zero for cells that have a
156 fixed density value, zero otherwise.
157 There should be no need to call this method directly.
158 \end{methoddesc}
159
160 \begin{methoddesc}[DomainBuilder]{getSetSusceptibilityMask}{}
161 returns the susceptibility mask \Data object which is non-zero for cells that
162 have a fixed susceptibility value, zero otherwise.
163 There should be no need to call this method directly.
164 \end{methoddesc}
165
166 \section{\class{DataSource} Class}\label{sec:ref:DataSource}
167
168 Data sources added to a \class{DomainBuilder} must provide an implementation for
169 a few methods as described in the class template \class{DataSource} from
170 the \module{esys.downunder.datasources} module:
171
172 \begin{classdesc}{DataSource}{}
173 Base constructor which initializes members and should therefore be invoked by
174 subclasses. Subclasses may then use the member \member{logger} to print any
175 output.
176 \end{classdesc}
177
178 \begin{methoddesc}[DataSource]{getDataExtents}{}
179 This method should be implemented to return a tuple of tuples
180 ( (x0, y0), (nx, ny), (dx, dy) ), where (x0, y0) denote the UTM coordinates of
181 the data origin, (nx, ny) the number of data points, and (dx, dy) the spacing
182 of data points.
183 \end{methoddesc}
184
185 \begin{methoddesc}[DataSource]{getDataType}{}
186 Subclasses must return \class{DataSource}.\member{GRAVITY} or
187 \class{DataSource}.\member{MAGNETIC} depending on the type of data they provide.
188 \end{methoddesc}
189
190 \begin{methoddesc}[DataSource]{getSurveyData}{domain, origin, NE, spacing}
191 This method is called by the \class{DomainBuilder} to retrieve the actual survey
192 data in the form of \Data objects on the \member{domain}.
193 Data sources are responsible to map or interpolate their data onto the domain
194 which has been constructed to fit the data.
195 The domain \member{origin}, number of elements \member{NE} and element
196 \member{spacing} are provided as tuples or lists to aid with interpolation.
197 \end{methoddesc}
198
199 \begin{methoddesc}[DataSource]{setSubsamplingFactor}{factor}
200 Notifies the data source that data should be subsampled by \member{factor}.
201 This method does not need to be overwritten.
202 See \member{getSubsamplingFactor()} for an explanation.
203 \end{methoddesc}
204
205 \begin{methoddesc}[DataSource]{getSubsamplingFactor}{}
206 Returns the subsampling factor which was set by \member{setSubsamplingFactor()}
207 or $1$ which indicates that no subsampling is requested.
208 Data sources that support subsampling (or interleaving) of their data should use
209 this method to query the subsampling factor before returning surveys via
210 \member{getSurveyData}. If supported, the factor should be applied in all
211 dimensions. For example, a 2-dimensional dataset with 300 x 150 data points
212 should be reduced to 150 x 75 data points when the subsampling factor equals $2$.
213 Subsampling becomes important when the survey data resolution is too fine or
214 when using data with varying resolution in one inversion.
215 Note that data sources may choose to ignore the subsampling factor if they
216 don't support it.
217 \end{methoddesc}
218
219 \vspace{1em}\noindent The \module{esys.downunder.datasources} module contains the following helper
220 functions:
221
222 \begin{funcdesc}{simpleGeoMagneticFluxDensity}{latitude%
223 \optional{, longitude=0.}}
224 returns an approximation of the geomagnetic flux density $B$ as described in
225 Equation~\ref{ref:MAG:EQU:5} for the given \member{latitude}.
226 The \member{longitude} parameter is currently ignored and the return value is
227 the tuple $(B_r, B_{\theta}, 0)$.
228 \end{funcdesc}
229
230 \begin{funcdesc}{LatLonToUTM}{longitude, latitude%
231 \optional{, wkt_string=\None}}
232 converts one or more (longitude,latitude) pairs to the corresponding (x,y)
233 coordinates in the \emph{Universal Transverse Mercator} (UTM) projection.
234 This function requires the \module{pyproj} module for conversion and the
235 \module{gdal} module to parse the \member{wkt_string} parameter if supplied.
236 \end{funcdesc}
237
238 \subsection{ER Mapper Raster Data}
239
240 \subsection{NetCDF Data}
241 An example script how to create a data input file for both gravity and magnetic
242 data using the \netcdf file format~\cite{netcdf} is available in the script
243 \examplefile{create_ncinput.py}.
244 To plot an input file using matplotlib~\cite{matplotlib} see the script \examplefile{show_ncinput.py}.
245
246 \subsection{Synthetic Data}
247

  ViewVC Help
Powered by ViewVC 1.1.26