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

Revision 4152 - (show 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 \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 \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 \end{funcdesc} 175 176 \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 \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