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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 4152 - (hide annotations)
Tue Jan 22 00:29:03 2013 UTC (6 years, 6 months ago) by caltinay
File MIME type: application/x-tex
File size: 8598 byte(s)
Moved figures to subdirectory.

1 gross 4106 \chapter{Data Sources}\label{Chp:ref:data sources}
2    
3 caltinay 4145 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 caltinay 4149 \section{Overview}
11 caltinay 4145 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 gross 4106
33 caltinay 4145
34 gross 4131 \section{Domain Builder}\label{Chp:ref:domain builder}
35 caltinay 4149 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 gross 4106
40 caltinay 4145 \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 gross 4106
45 caltinay 4145 \begin{methoddesc}[DomainBuilder]{addSource}{source}
46 caltinay 4149 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 caltinay 4145 \end{methoddesc}
50    
51 caltinay 4149 \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 caltinay 4145 \begin{methoddesc}[DomainBuilder]{getDomain}{}
130 caltinay 4149 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 caltinay 4145 \end{methoddesc}
138    
139 caltinay 4149 \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 caltinay 4145
148 caltinay 4149 \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 gross 4106
154 caltinay 4149 \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 caltinay 4145
160 caltinay 4149 \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 caltinay 4152 \begin{funcdesc}{simpleGeoMagneticFluxDensity}{latitude%
169     \optional{, longitude=0.}}
170     returns an approximation of the geomagnetic flux density $B$ as described in
171     Equation~\ref{ref:MAG:EQU:5} for the given \member{latitude}.
172     The \member{longitude} parameter is currently ignored and the return value is
173     the tuple $(B_r, B_{\theta}, 0)$.
174 caltinay 4149 \end{funcdesc}
175    
176 caltinay 4152 \begin{funcdesc}{LatLonToUTM}{longitude, latitude%
177     \optional{, wkt_string=\None}}
178     converts one or more (longitude,latitude) pairs to the corresponding (x,y)
179     coordinates in the \emph{Universal Transverse Mercator} (UTM) projection.
180     \end{funcdesc}
181    
182 caltinay 4149 \subsection{ER Mapper Raster Data}
183    
184     \subsection{NetCDF Data}
185     An example script how to create a data input file for both gravity and magnetic
186     data using the \netcdf file format~\cite{netcdf} is available in the script
187     \examplefile{create_ncinput.py}.
188     To plot an input file using matplotlib~\cite{matplotlib} see the script \examplefile{show_ncinput.py}.
189    
190     \subsection{Synthetic Data}
191    

  ViewVC Help
Powered by ViewVC 1.1.26