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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 4149 - (show annotations)
Mon Jan 21 02:03:31 2013 UTC (6 years, 6 months ago) by caltinay
File MIME type: application/x-tex
File size: 8073 byte(s)
Checkpoint - DomainBuilder documented.

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{Data Source}\label{sec:ref:DataSource}
167
168 \begin{funcdesc}{simpleGeoMagneticFluxDensity}{latitude}
169 \end{funcdesc}
170
171 \subsection{ER Mapper Raster Data}
172
173 \subsection{NetCDF Data}
174 An example script how to create a data input file for both gravity and magnetic
175 data using the \netcdf file format~\cite{netcdf} is available in the script
176 \examplefile{create_ncinput.py}.
177 To plot an input file using matplotlib~\cite{matplotlib} see the script \examplefile{show_ncinput.py}.
178
179 \subsection{Synthetic Data}
180

  ViewVC Help
Powered by ViewVC 1.1.26