Merge branch 'master' into misc

.gitlab-ci.yml

+pages:
+  stage: deploy
+  script:
+  - python3 setup.py build_sphinx
+  - mv build/sphinx/html public
+  artifacts:
+    paths:
+    - public
+  only:
+  - master

README.md

@@ -40,7 +40,7 @@ along with this program.  If not, see <https://www.gnu.org/licenses/>.
 TODO
 
 ## Documentation
-From the command line, you can use pymagglobal to get various results from the models. For example,
+Check out the extended documention [here](http://arthus.gitext.gfz-potsdam.de/pymagglobal). From the command line, you can use pymagglobal to get various results from the models. For example,
 ```console
 $ pymagglobal dipole gufm1
 ```

docs/command_line_interface.rst

+Command line interface
+======================
+
+The python package `pymagglobal` also offers a utility command
+
+.. argparse::
+    :module: pymagglobal.__main__
+    :func: argument_parser
+    :prog: pymagglobal
+
+.. todo:: Use the epilog to provide `Example of use: ...` followed by th according figure.
+

docs/conf.py

+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+#import os
+#import sys
+#sys.path.insert(0, os.path.abspath('../'))
+
+# -- Project information -----------------------------------------------------
+
+# Sphinx's options are specified by setup.py
+#project = 'pymagglobal'
+#copyright = '2020 Helmholtz Centre Potsdam GFZ, German Research Centre for Geosciences, Potsdam, Germany'
+## The full version, including alpha/beta/rc tags
+#release = '0.0.2'
+# Due to some reason not set by setup.py
+author = 'Schanner, M.A. and Mauerberger, S.'
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ['sphinx.ext.autodoc',
+              'sphinx.ext.napoleon',
+              'sphinx.ext.todo',
+              'sphinx.ext.linkcode',
+              'sphinxarg.ext']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = True
+
+# Add external links to source code
+def linkcode_resolve(domain, info):
+    '''Returns external links to the source of objects'''
+    url = 'https://gitext.gfz-potsdam.de/arthus/pymagglobal'
+    filename = info['module'].replace('.', '/') + '.py'
+    return url + '/-/tree/master/' + filename
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'classic'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']

docs/index.rst

+A python interface for global geomagnetic field models
+======================================================
+
+`pymagglobal` serves the purpose of replacing some Fortran scripts, which are used in the geomagnetism community to evaluate global field models.
+It can be applied to all cubic-spline based geomagnetic field models stored in the same file format as `gufm1` or the `CALSxk` model series.
+
+.. toctree::
+   :maxdepth: 2
+
+   package_documentation
+   command_line_interface
+
+.. include:: ../pymagglobal/dat/README.rst
+
+License
+-------
+GNU General Public License, Version 3, 29 June 2007
+
+Copyright (C) 2020 Helmholtz Centre Potsdam GFZ, German Research Centre for Geosciences, Potsdam, Germany
+
+pymagglobal 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.
+
+pymagglobal 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/>.
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+* :ref:`todo`

docs/package_documentation.rst

+Package Documentation
+=====================
+.. automodule:: pymagglobal
+   :members:
+
+.. todo:: Fix URL for the package i.e. `pymagglobal/__init__.py`
+
+
+Pymagglobal
+***********
+.. automodule:: pymagglobal.pymagglobal
+   :members:
+
+
+Utilities
+*********
+.. automodule:: pymagglobal.utils
+   :members:
+
+
+Argument Parser & Main Program
+******************************
+.. automodule:: pymagglobal.__main__
+   :members:
+
+
+Commands
+********
+.. automodule:: pymagglobal.commands
+   :members:
+

docs/todo.rst

+.. _todo:
+
+ToDo
+====
+
+The following list is automatically created.
+
+ .. todolist::
+

pymagglobal/__init__.py

-'''
-    Copyright (C) 2020 Helmholtz Centre Potsdam GFZ,
-        German Research Centre for Geosciences, Potsdam, Germany
-
-    Cite as:
-    TODO
-
-    This file is part of pymagglobal.
-
-    pymagglobal 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.
-
-    pymagglobal 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 pymagglobal. If not, see <https://www.gnu.org/licenses/>.
+# Copyright (C) 2020 Helmholtz Centre Potsdam GFZ,
+#     German Research Centre for Geosciences, Potsdam, Germany
+#
+# Cite as:
+# TODO
+#
+# This file is part of pymagglobal.
+#
+# pymagglobal 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.
+#
+# pymagglobal 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 pymagglobal. If not, see <https://www.gnu.org/licenses/>.
+'''The package exposes selected attributes of sub-modules ...
+
+.. todo:: Doc-string of the module missing.
 '''
 
 # expose only utilities and core modules

pymagglobal/__main__.py

-'''
-    This is the main module of pymagglobal. It is called when using the command
-    line interface.
-
-    Copyright (C) 2020 Helmholtz Centre Potsdam GFZ,
-        German Research Centre for Geosciences, Potsdam, Germany
-
-    Cite as:
-    TODO
-
-    This file is part of pymagglobal.
-
-    pymagglobal 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.
-
-    pymagglobal 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 pymagglobal. If not, see <https://www.gnu.org/licenses/>.
+# This is the main module of pymagglobal. It is called when using the command
+# line interface.
+#
+# Copyright (C) 2020 Helmholtz Centre Potsdam GFZ,
+#     German Research Centre for Geosciences, Potsdam, Germany
+#
+# Cite as:
+# TODO
+#
+# This file is part of pymagglobal.
+#
+# pymagglobal 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.
+#
+# pymagglobal 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 pymagglobal. If not, see <https://www.gnu.org/licenses/>.
+'''The contents will be executed when the pymagglobal is run with -m switch.
+
+.. todo:: Doc-string of the module missing.
 '''
 
 import sys
@@ -51,10 +53,8 @@ class ListModelsAction(argparse.Action):
         parser.exit()
 
 
-def main():
-    ''' the main command of pymagglobal. it handles command line arguments and
-    calls the respective functions from the commands module.
-    '''
+def argument_parser():
+    '''the argument parser'''
     # the main parsing
     parser = argparse.ArgumentParser(add_help=False)
     parser.add_argument('-h', '--help', action='help',
@@ -104,12 +104,18 @@ def main():
                                     f'not given, use the latest year '
                                     f'possible')
     # the subparser for commands
-    subparsers = parser.add_subparsers(dest='command', required=True)
+    subparsers = parser.add_subparsers(dest='command')#, required=True)
     # parser for the master curve handling
+    # XXX Prototyping with epilogues
+    mst_epilog = '''Example of use: :command:`pymagglobal master 12 12 gufm1`
+
+.. image:: ./pic_master.png '''
     mst_parser = subparsers.add_parser('master', help=f'create a master curve '
                                        f'for a specific location',
                                        parents=[base_parser,
-                                                series_base_parser])
+                                                series_base_parser],
+                                       epilog=mst_epilog)
+
     mst_parser.set_defaults(func=commands.master_curve)
     mst_parser.add_argument('lat', type=float,
                             help=f'the latitude at which to create the master '
@@ -168,6 +174,13 @@ def main():
                         help=f'input path to a model file. may be used to '
                         f'evaluate your own model. if given, this path will '
                         f'be used instead over the included files')
+    return parser
+
+def main():
+    '''the main command of pymagglobal. it handles command line arguments and
+    calls the respective functions from the commands module.
+    '''
+    parser = argument_parser()
     # parse the command line arguments
     args = parser.parse_args()
     # check whether model and input are consistent

pymagglobal/commands.py

-'''
-    This module contains the commands that are used by the main module of
-    pymagglobal.
-
-    Copyright (C) 2020 Helmholtz Centre Potsdam GFZ,
-        German Research Centre for Geosciences, Potsdam, Germany
-
-    Cite as:
-    TODO
-
-    This file is part of pymagglobal.
-
-    pymagglobal 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.
-
-    pymagglobal 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 pymagglobal. If not, see <https://www.gnu.org/licenses/>.
+# This module contains the commands that are used by the main module of
+# pymagglobal.
+#
+# Copyright (C) 2020 Helmholtz Centre Potsdam GFZ,
+#     German Research Centre for Geosciences, Potsdam, Germany
+#
+# Cite as:
+# TODO
+#
+# This file is part of pymagglobal.
+#
+# pymagglobal 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.
+#
+# pymagglobal 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 pymagglobal. If not, see <https://www.gnu.org/licenses/>.
+
+'''Just a bunch of functions ...
+
+.. todo:: Doc-string missing in module.
 '''
 from warnings import warn
 

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

pymagglobal/pymagglobal.py

-'''
-    This is the core module of pymagglobal. It contains the function
-    file2splines, which creates a BSpline object from a coefficient file and
-    funtions that evaluate such an object to calculate different quantities of
-    interest. See the README file in the repository for further information.
-
-    Copyright (C) 2020 Helmholtz Centre Potsdam GFZ,
-        German Research Centre for Geosciences, Potsdam, Germany
-
-    Cite as:
-    TODO
-
-    This file is part of pymagglobal.
-
-    pymagglobal 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.
-
-    pymagglobal 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 pymagglobal. If not, see <https://www.gnu.org/licenses/>.
+# This is the core module of pymagglobal. It contains the function
+# file2splines, which creates a BSpline object from a coefficient file and
+# funtions that evaluate such an object to calculate different quantities of
+# interest. See the README file in the repository for further information.
+#
+# Copyright (C) 2020 Helmholtz Centre Potsdam GFZ,
+#     German Research Centre for Geosciences, Potsdam, Germany
+#
+# Cite as:
+# TODO
+#
+# This file is part of pymagglobal.
+#
+# pymagglobal 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.
+#
+# pymagglobal 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 pymagglobal. If not, see <https://www.gnu.org/licenses/>.
+
+'''The core module of pymmagglobal ...
+
+.. todo:: Doc-string of the module missing.
 '''
 import os
 
@@ -168,13 +171,14 @@ def field(z_at, splines):
 
     Parameters
     ----------
-    z_at : array-like of shape (4, n) in fortran order
+    z_at : array-like of shape (4, n) in Fortran order
         the locations at which to evaluate the splines. should be as expected
         by pyfield, i.e.
-          z_at[0] contains co-latitudes in degrees
-          z_at[1] contains longitudes in degrees
-          z_at[2] contains radii in km
-          z_at[3] contains dates in years
+
+         * z_at[0] contains co-latitudes in degrees
+         * z_at[1] contains longitudes in degrees
+         * z_at[2] contains radii in km
+         * z_at[3] contains dates in years
     splines : scipy.interpolate.BSpline
         the splines specifying the model
 

pymagglobal/utils.py

-'''
-    This module contains utilility routines for pymagglobal.
-
-    Copyright (C) 2020 Helmholtz Centre Potsdam GFZ,
-        German Research Centre for Geosciences, Potsdam, Germany
-
-    Cite as:
-    TODO
-
-    This file is part of pymagglobal.
-
-    pymagglobal 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.
-
-    pymagglobal 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 pymagglobal. If not, see <https://www.gnu.org/licenses/>.
+# This module contains utilility routines for pymagglobal.
+#
+# Copyright (C) 2020 Helmholtz Centre Potsdam GFZ,
+#     German Research Centre for Geosciences, Potsdam, Germany
+#
+# Cite as:
+# TODO
+#
+# This file is part of pymagglobal.
+#
+# pymagglobal 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.
+#
+# pymagglobal 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 pymagglobal. If not, see <https://www.gnu.org/licenses/>.
+'''Utility functions
+
+.. todo:: Doc-string of the module missing.
 '''
 
 import numpy as np
@@ -28,9 +30,11 @@ import numpy as np
 # some names and labels that are used multiple times
 names = {'dif': ['Declination', 'Inclination', 'Intensity'],
          'nez': ['North', 'East', 'Down']}
+"""Doc-string missing ... """
 
 labels = {'dif': [r'D [deg.]', r'I [deg.]', r'F [nT]'],
           'nez': [r'N [nT]', r'E [nT]',  r'Z [nT]']}
+"""Doc-string missing ... """
 
 
 def nicelabel(label):
@@ -42,6 +46,10 @@ def nicelabel(label):
 def nez2dif(n, e, z):
     ''' transform north, east, down field components to declination,
     inclination and intensity
+
+    Example
+    -------
+    >>> nez2dif(1, 1, 1)
     '''
     return np.rad2deg(np.arctan2(e, n)), \
         np.rad2deg(np.arctan2(z, np.sqrt(n**2 + e**2))), \
@@ -49,13 +57,16 @@ def nez2dif(n, e, z):
 
 
 def equi_sph(n, twopi=True):
-    ''' Regularly place points on the surface of the unit sphere. the number of
-    output points may differ from n
+    ''' Regularly place points on the surface of the unit sphere [1]_. the number of
+    output points may differ from n ...
+
+    .. todo:: Return a ndarray rather than using generators.
+              Import equi_sph from pyfield
 
     References
     ----------
-    [1] M. Deserno, "How to generate equidistributed points on the surface of a
-        sphere", Max-Planck-Institut für Polymerforschung, 2004.
+    .. [1] M. Deserno, "How to generate equidistributed points on the surface