README.md 5.83 KB
Newer Older
Maximilian Schanner's avatar
Maximilian Schanner committed
1
2
3
# CORBASS

### CORrelation Based Archeomagnetic SnapShot model
4
5
6
# License
GNU General Public License, Version 3, 29 June 2007

Maximilian Schanner's avatar
Maximilian Schanner committed
7
Copyright (C) 2019 Helmholtz Centre Potsdam GFZ, German Research Centre for Geosciences, Potsdam, Germany
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

CORBASS is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

CORBASS is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

# Citation
Stefan Mauerberger's avatar
Stefan Mauerberger committed
23
24
25
> Schanner, Maximilian Arthus and Mauerberger, Stefan (2019)
> CORBASS: CORrelation Based Archeomagnetic SnapShot model. V. 1.0.
> GFZ Data Services. http://doi.org/10.5880/GFZ.2.3.2019.008
26
27
28

[![DOI](https://img.shields.io/badge/DOI-10.5880%2FGFZ.2.3.2019.008-blue.svg)](http://doi.org/10.5880/GFZ.2.3.2019.008)

Maximilian Schanner's avatar
Maximilian Schanner committed
29
# Documentation
Maximilian Schanner's avatar
Maximilian Schanner committed
30
The `CORBASS` model is described in [Mauerberger et al. (2020)](https://academic.oup.com/gji/article-abstract/223/1/648/5870664). In  a way this
Maximilian Schanner's avatar
Maximilian Schanner committed
31
32
repository can be seen as supplementary material to this publication. Below this
section we give installation instructions.
Maximilian Schanner's avatar
Maximilian Schanner committed
33
34
35
36
37

From an algorithmic point of view, `CORBASS` can be simplified in the following
flowchart:
```mermaid
graph LR;
38
  ParameterFile-->Exploration-->Integration-->Evaluation;
Maximilian Schanner's avatar
Maximilian Schanner committed
39
40
```

Stefan Mauerberger's avatar
Stefan Mauerberger committed
41
42
`CORBASS` uses parameter files, which include among other things a link to
datasets, in a format similar to the [GEOMAGIA](http://geomagia.gfz-potsdam.de/)
Maximilian Schanner's avatar
Maximilian Schanner committed
43
output. Thus a first step is to create such a file for your data. You can find
Maximilian Schanner's avatar
Maximilian Schanner committed
44
an [example](examples/Example_Parfile.py)
Maximilian Schanner's avatar
Maximilian Schanner committed
45
in the [*examples* section].
Maximilian Schanner's avatar
Maximilian Schanner committed
46

Maximilian Schanner's avatar
Maximilian Schanner committed
47
Once you have a parameter file, the recommended way to run `CORBASS` is to use
Maximilian Schanner's avatar
Maximilian Schanner committed
48

Maximilian Schanner's avatar
Maximilian Schanner committed
49
```console
Stefan Mauerberger's avatar
Stefan Mauerberger committed
50
(CORBASS)$ python run.py <path/to/parfile.py>
Maximilian Schanner's avatar
Maximilian Schanner committed
51
```
Maximilian Schanner's avatar
Maximilian Schanner committed
52

Maximilian Schanner's avatar
Maximilian Schanner committed
53
This way the `CORBASS` posterior model coefficients, the NEZ- and DIF-field models
Maximilian Schanner's avatar
Maximilian Schanner committed
54
55
56
and down component and intensity at the CMB are calculated and provided as `.txt`
files. The output location is specified in the parameter file.

Maximilian Schanner's avatar
Maximilian Schanner committed
57
Under the hood, `CORBASS` first explores the model parameter space by using the
Stefan Mauerberger's avatar
Stefan Mauerberger committed
58
`exploration` module. This way the region of interest, i.e. where the
Maximilian Schanner's avatar
Maximilian Schanner committed
59
probability mass is concentrated, is found and can be accessed by the
60
61
`integration` module. The output can then be used to calculate further results,
using the `evaluation` module.
Maximilian Schanner's avatar
Maximilian Schanner committed
62

Maximilian Schanner's avatar
typo    
Maximilian Schanner committed
63
If you want to use the individual modules, you can find Jupyter notebooks for
Maximilian Schanner's avatar
Typo    
Maximilian Schanner committed
64
each module in the [*examples* section].
Maximilian Schanner's avatar
Maximilian Schanner committed
65

66
[*examples* section]: examples
Maximilian Schanner's avatar
Maximilian Schanner committed
67

Maximilian Schanner's avatar
Maximilian Schanner committed
68
# Installation
69

70
> **Note**: CORBASS is superceeded by [CORBAM](https://git.gfz-potsdam.de/sec23/korte/corbam/).
71

Stefan Mauerberger's avatar
Stefan Mauerberger committed
72
0. Clone the repository
73
74
75
76
   ```console
    $ git clone https://gitext.gfz-potsdam.de/arthus/corbass.git
   ```
   In the following `<corbass>` refers to the path you cloned the `CORBASS` repository into.
Maximilian Schanner's avatar
Maximilian Schanner committed
77
78

1. Download and install [Miniconda](https://conda.io/miniconda.html) for Python 3.
Stefan Mauerberger's avatar
Stefan Mauerberger committed
79
   By default, the installation directory `<conda>` is `~/miniconda3/`.
Maximilian Schanner's avatar
Maximilian Schanner committed
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
   If you let conda modify your `bash.rc`, `<conda>/bin/conda` may be replaced by
   `conda`.

2. Build and install [FieldTools]

   1. Install `conda-build` (to base)
   ```console
   $ <conda>/bin/conda install conda-build
   ```

   2. Navigate to `<corbass>` and build [FieldTools]
   ```console
   $ <conda>/bin/conda build FieldTools
   ```

3. Create the virtual environment `CORBASS`
   ```console
   $ <conda>/bin/conda env create -f corbass.yml
   ```

4. Activate the virtual environment
   ```console
   $ source <conda>/bin/activate CORBASS
   ```

Stefan Mauerberger's avatar
Stefan Mauerberger committed
105
   Careful with tcshell, you have to use activate.csh.
Maximilian Schanner's avatar
Maximilian Schanner committed
106
   When you are done, deactivate the environment by
Maximilian Schanner's avatar
Maximilian Schanner committed
107
   ```console
Maximilian Schanner's avatar
Typo    
Maximilian Schanner committed
108
   (CORBASS)$ conda deactivate
Maximilian Schanner's avatar
Maximilian Schanner committed
109
110
111
112
113
114
115
116
117
118
119
120
121

   ```

5. Install optional packages, for example
   ```console
   (CORBASS)$ conda install ipython jupyter notebook
   ```

6. If [corbass.yml](corbass.yml) changes, you are recommended to update your environment:
   ```console
   $ <conda>/bin/conda env update -f corbass.yml
   ```

Stefan Mauerberger's avatar
Stefan Mauerberger committed
122
[FieldTools]: https://doi.org/10.5880/fidgeo.2019.033
Maximilian Schanner's avatar
Maximilian Schanner committed
123

Maximilian Schanner's avatar
Maximilian Schanner committed
124
# Contact
Stefan Mauerberger's avatar
Stefan Mauerberger committed
125
126
127
128
* [Maximilian Schanner](mailto:arthus@gfz-potsdam.de)
Helmholtz Centre Potsdam German Research Centre for Geoscienes GFZ
Section 2.3: Geomagnetism
Telegrafenberg
Maximilian Schanner's avatar
Maximilian Schanner committed
129
130
14473 Potsdam, Germany

Stefan Mauerberger's avatar
Stefan Mauerberger committed
131
132
133
134
135
* [Stefan Mauerberger](mailto:mauerber@uni-potsdam.de)
Institut of mathematics
University of Potsdam
Campus Golm, Haus 9
Karl-Liebknecht-Str. 24-25
Maximilian Schanner's avatar
Maximilian Schanner committed
136
14476 Potsdam OT Golm, Germany
Maximilian Schanner's avatar
Maximilian Schanner committed
137
138
139
140

# References
`CORBASS` uses `numpy`, `scipy`, `pandas`, `matplotlib` and `cartopy`:

Stefan Mauerberger's avatar
Stefan Mauerberger committed
141
142
143
144
145
146
147
148
149
150
[\[scipy\]](https://www.scipy.org/) Pauli Virtanen, Ralf Gommers, Travis E. Oliphant, Matt Haberland,
Tyler Reddy, David Cournapeau, Evgeni Burovski, Pearu Peterson,
Warren Weckesser, Jonathan Bright, Stéfan J. van der Walt, Matthew Brett,
Joshua Wilson, K. Jarrod Millman, Nikolay Mayorov, Andrew R. J. Nelson,
Eric Jones, Robert Kern, Eric Larson, CJ Carey, İlhan Polat, Yu Feng,
Eric W. Moore, Jake VanderPlas, Denis Laxalde, Josef Perktold, Robert Cimrman,
Ian Henriksen, E.A. Quintero, Charles R Harris, Anne M. Archibald,
Antônio H. Ribeiro, Fabian Pedregosa, Paul van Mulbregt,
and SciPy 1.0 Contributors (2020)
"SciPy 1.0: Fundamental Algorithms for Scientific Computing in Python".
Maximilian Schanner's avatar
Maximilian Schanner committed
151
152
Nature Methods, in press.

Stefan Mauerberger's avatar
Stefan Mauerberger committed
153
154
[\[pandas\]](https://pandas.pydata.org/)  Wes McKinney (2010)
"Data structures for statistical computing in python",
Maximilian Schanner's avatar
Maximilian Schanner committed
155
156
Proceedings of the 9th Python in Science Conference, Volume 445

Stefan Mauerberger's avatar
Stefan Mauerberger committed
157
158
[\[matplotlib\]](https://matplotlib.org/)  J. D. Hunter (2007)
"Matplotlib: A 2D Graphics Environment",
Maximilian Schanner's avatar
Maximilian Schanner committed
159
160
Computing in Science & Engineering, vol. 9, no. 3, pp. 90-95

Stefan Mauerberger's avatar
Stefan Mauerberger committed
161
162
[\[cartopy\]](https://scitools.org.uk/cartopy) Met Office (2015)
"Cartopy: a cartographic python library with a Matplotlib interface"