Model and File-format description in reST

docs/index.rst

@@ -10,20 +10,7 @@ It can be applied to all cubic-spline based geomagnetic field models stored in t
    package_documentation
    command_line_interface
 
-File format
------------
-However, care has to be taken that two header lines of the model files are formatted correctly and the list of spline knot point epochs starts only in line 3.
-The first header line has to contain start and end epoch of the model as the first two numbers, any further information in that line is ignored.
-The second header line has to start with three integers, which are the maximum spherical harmonic degree, a dummy that actually is not used, and the number of splines.
-
-.. code-block:: none
-   :linenos:
-
-   1590 1990 Trailing text is ignored
-   14  0  163
-     1582.5000000000    1585.0000000000    1587.5000000000
-   ...
-
+.. include:: ../pymagglobal/dat/README.rst
 
 License
 -------

pymagglobal/dat/README.md

-# Format description
-
-The format that is used by pymagglobal is the same as the gufm1 model and the CALSxk models. The model files are structured as follows:
-
-* The first line consits of the interval for which the model is valid, followed by several model parameters
-* The second line contains three integers: the maximal spherical harmonic degree, a meaningless number and the number of splines
-* Then follows a block of years, specifying the knots for the cubic B-splines and a block of coefficients, containing first all coefficients for the first knot, then all for the second etc.
-
-The code is somewhat flexible with linebreaks. Only the linebreak after the first line is really necessary. If you have trouble parsing your own files, feel free to [contact](mailto:arthus@gfz-potsdam.de) one of the authors.
-
-# Included models
-
-pymagglobal comes with several models pre-included. Below is a description of those models.
-
-| Model | Interval | Reference | Short description |
-| ----- | -------- | --------- | ----------------- |
-| gufm1 | 1590 – 1990 AD | Jackson, A., A. R. T. Jonkers and M. R. Walker (2000): Four centuries of geomagnetic secular variation from historical records. Phil. Trans. R. Soc. Lond. A 358, 957–990 | Based on historical and modern data |
-| arhimag1k | 1000 – 2000 AD | R. Senftleben (2020) Earth’s magnetic field over the last 1000 years. PhD thesis, University of Potsdam | Combining archeomagnetic, volcanic and historical data |
-| pfm9k.1a | 7000 BC – 1900 AD | Nilsson, A., R. Holme, M. Korte, N. Suttie and M. Hill (2014): Reconstructing Holocene geomagnetic field variation: new methods, models and implications. Geophys. J. Int., 198, 229-248 | Based on archeomagnetic, volcanic and sediment data; Sediment timescales adjusted to best fit |
-| HFM.OL1.A1 | 8000 BC – 1990 AD | Panovska, S., M. Korte, C. Finlay and C. Constable (2015): Limitations in paleomagnetic data and modelling techniques and their impact on Holocene geomagnetic field models. Geophys. J. Int., 202, 402-418. | Based on archeomagnetic, volcanic and sediment data; Data outlier treatment and strength of temporal and spatial regularization somewhat different from the CALSxk models |
-| CALS10k.2 | 8000 BC – 1990 AD | Constable, C., M. Korte and S. Panovska (2016): Persistent high paleosecular variation activity in Southern hemisphere for at least 10 000 years. Earth Planet. Sci. Lett.,453,78-86. | Based on archeomagnetic, volcanic and sediment data; Recent centuries constrained to agree in general with gufm1 |
-| ARCH10k.1 | 8000 BC – 1990 AD | same as CALS10k.2 | Based only on archeomagnetic and volcanic data; Sparse data coverage for early millennia; Recent centuries constrained to agree in general with gufm1 |
-| LSMOD.2 | 49.5 – 29.5 ka | Korte, M., M. C. Brown, S. Panovska and I. Wardinski (2019): Robust characteristics of the Laschamp and Mono Lake geomagnetic excursions: results from global field models. Frontiers in Earth Sciences, 7:86, doi:10.3389/feart.2019.00086 | Based on sediment and volcanic data; Closely adjacent sediment records stacked for regional consistency; Small correction to a sediment record location compared to LSMOD.1; use the `--longterm` flag, to pass dates as ka  |
-| GGF100k | 100 – 0 ka | Panovska, S., C. G. Constable and M. Korte (2018): Extending global continuous geomagnetic field reconstructions on timescales beyond human civilization. Geochem. Geophys. Geosys., 19, 4757-4772. doi:10.1029/2018GC007966 | Based on sediment, volcanic and archeomagnetic data; Temporally stronger smoothed (by temporal regularization) compared to the dedicated Laschamp excursion models; use the `--longterm` flag, to pass dates as ka |

pymagglobal/dat/README.rst

+File format description
+-----------------------
+
+The format that is used by pymagglobal is the same as the ``gufm1`` model and the ``CALSxk`` models.
+Care has to be taken that two header lines of the model files are formatted correctly and the list of spline knot point epochs starts only in line 3.
+The model files are structured as follows:
+
+* The first line has to provide two numeric values:
+  Start and end of the epoch for which the model is valid.
+  Any trailing text is ignored.
+* The second line contains three integers:
+  The maximal spherical harmonic degree, an unused number and the number of splines.
+* Then follows a block of years, specifying the knots for the cubic B-splines and a block of coefficients, containing first all coefficients for the first knot, then all for the second etc.
+
+.. code-block:: none
+   :linenos:
+
+   1590 1990 Trailing text is ignored
+   14  0  163
+     1582.5000000000    1585.0000000000    1587.5000000000 ...
+
+The code is somewhat flexible with line breaks.
+Only the line break after the first line is really necessary.
+If you have trouble parsing your own files, feel free to `contact <mailto:arthus@gfz-potsdam.de>`_ one of the authors.
+
+Included models
+---------------
+
+pymagglobal comes with several models pre-included. Below is a description of those models.
+
+========== ================= ========= =================
+Model      Interval          Reference Short description
+========== ================= ========= =================
+gufm1      1590 – 1990 AD    [Jack00]_ Based on historical and modern data
+arhimag1k  1000 – 2000 AD    [Senf20]_ Combining archeomagnetic, volcanic and historical data
+pfm9k.1a   7000 BC – 1900 AD [Nils14]_ Based on archeomagnetic, volcanic and sediment data; Sediment timescales adjusted to best fit
+HFM.OL1.A1 8000 BC – 1990 AD [Pano15]_ Based on archeomagnetic, volcanic and sediment data; Data outlier treatment and strength of temporal and spatial regularization somewhat different from the ``CALSxk`` models
+CALS10k.2  8000 BC – 1990 AD [Cons16]_ Based on archeomagnetic, volcanic and sediment data; Recent centuries constrained to agree in general with gufm1
+ARCH10k.1  8000 BC – 1990 AD [Cons16]_ Based only on archeomagnetic and volcanic data; Sparse data coverage for early millennia; Recent centuries constrained to agree in general with ``gufm1``
+LSMOD.2    49.5 – 29.5 ka    [Kort19]_ Based on sediment and volcanic data; Closely adjacent sediment records stacked for regional consistency; Small correction to a sediment record location compared to ``LSMOD.1``; use the ``--longterm`` flag, to pass dates as ka
+GGF100k    100 – 0 ka        [Pano18]_ Based on sediment, volcanic and archeomagnetic data; Temporally stronger smoothed (by temporal regularization) compared to the dedicated Laschamp excursion models; use the ``--longterm`` flag, to pass dates as ka
+========== ================= ========= =================
+
+.. rubric:: References
+
+.. [Jack00] Jackson, A., A. R. T. Jonkers and M. R. Walker (2000): Four centuries of geomagnetic secular variation from historical records. Phil. Trans. R. Soc. Lond. A 358, 957–990
+.. [Senf20] Senftleben, R. (2020): Earth’s magnetic field over the last 1000 years. PhD thesis, University of Potsdam
+.. [Nils14] Nilsson, A., R. Holme, M. Korte, N. Suttie and M. Hill (2014): Reconstructing Holocene geomagnetic field variation: new methods, models and implications. Geophys. J. Int., 198, 229-248
+.. [Pano15] Panovska, S., M. Korte, C. Finlay and C. Constable (2015): Limitations in paleomagnetic data and modelling techniques and their impact on Holocene geomagnetic field models. Geophys. J. Int., 202, 402-418.
+.. [Cons16] Constable, C., M. Korte and S. Panovska (2016): Persistent high paleosecular variation activity in Southern hemisphere for at least 10 000 years. Earth Planet. Sci. Lett.,453,78-86.
+.. [Kort19] Korte, M., M. C. Brown, S. Panovska and I. Wardinski (2019): Robust characteristics of the Laschamp and Mono Lake geomagnetic excursions: results from global field models. Frontiers in Earth Sciences, 7:86, doi:10.3389/feart.2019.00086
+.. [Pano18] Panovska, S., C. G. Constable and M. Korte (2018): Extending global continuous geomagnetic field reconstructions on timescales beyond human civilization. Geochem. Geophys. Geosys., 19, 4757-4772. doi:10.1029/2018GC007966