Updated a lot of docstrings

incremented PyPI version to 0.3.1
brmather · Jun 20, 2019 · 46973c9 · 46973c9
1 parent 77248a0
commit 46973c9
Show file tree

Hide file tree

Showing 13 changed files with 481 additions and 782 deletions.
diff --git a/MANIFEST.in b/MANIFEST.in
@@ -5,7 +5,6 @@ include COPYING
 include COPYING.LESSER
 include setup.cfg
 include src/*
-include __init__.py
 recursive-include pycurious/*.py
 recursive-include pycurious/*.ipynb
 include tests/*.py
diff --git a/README.md b/README.md
@@ -5,7 +5,7 @@
 [![DOI](https://zenodo.org/badge/123281222.svg)](https://zenodo.org/badge/latestdoi/123281222)
 [![Build Status](https://travis-ci.org/brmather/pycurious.svg?branch=master)](https://travis-ci.org/brmather/pycurious)
 
-Magnetic data is one of the most common geophysics datasets available on the surface of the Earth. Curie depth is the depth at which rocks lose their magnetism. The most prevalent magnetic mineral is magnetite, which has a Curie point of 580C, thus the Curie depth is often interpreted as the 580C isotherm.
+Magnetic data is one of the most common geophysics datasets available on the surface of the Earth. Curie depth is the depth at which rocks lose their magnetism. The most prevalent magnetic mineral is magnetite, which has a Curie point of 580°C, thus the Curie depth is often interpreted as the 580°C isotherm.
 
 Current methods to derive Curie depth first compute the (fast) Fourier transform over a square window of a magnetic anomaly that has been reduced to the pole. The depth and thickness of magnetic sources is estimated from the slope of the radial power spectrum. `pycurious` implements the Tanaka *et al.* (1999) and Bouligand *et al.* (2009) methods for computing the thickness of a buried magnetic source, which are covered within Jupyter notebooks.
 
@@ -28,17 +28,17 @@ pycurious.install_documentation(path="Notebooks")
 
 ### Tanaka
 
-- [Ex1-Plot-power-spectrum.ipynb](pycurious-src/pycurious/Examples/Notebooks/Tanaka/Ex1-Plot-power-spectrum.ipynb)
-- [Ex2-Compute-Curie-depth.ipynb](pycurious-src/pycurious/Examples/Notebooks/Tanaka/Ex2-Compute-Curie-depth.ipynb)
-- [Ex3-Parameter-exploration.ipynb](pycurious-src/pycurious/Examples/Notebooks/Tanaka/Ex3-Parameter-exploration.ipynb)
+- [Ex1-Plot-power-spectrum.ipynb](pycurious/Examples/Notebooks/Tanaka/Ex1-Plot-power-spectrum.ipynb)
+- [Ex2-Compute-Curie-depth.ipynb](pycurious/Examples/Notebooks/Tanaka/Ex2-Compute-Curie-depth.ipynb)
+- [Ex3-Parameter-exploration.ipynb](pycurious/Examples/Notebooks/Tanaka/Ex3-Parameter-exploration.ipynb)
 
 ### Bouligand
 
-- [Ex1-Plot-power-spectrum.ipynb](pycurious-src/pycurious/Examples/Notebooks/Bouligand/Ex1-Plot-power-spectrum.ipynb)
-- [Ex2-Compute-Curie-depth.ipynb](pycurious-src/pycurious/Examples/Notebooks/Bouligand/Ex2-Compute-Curie-depth.ipynb)
-- [Ex3-Posing-the-inverse-problem.ipynb](pycurious-src/pycurious/Examples/Notebooks/Bouligand/Ex3-Posing-the-inverse-problem.ipynb)
-- [Ex4-Spatial-variation-of-Curie-depth.ipynb](pycurious-src/pycurious/Examples/Notebooks/Bouligand/Ex4-Spatial-variation-of-Curie-depth.ipynb)
-- [Ex5-Mapping-Curie-depth-EMAG2.ipynb](pycurious-src/pycurious/Examples/Notebooks/Bouligand/Ex5-Mapping-Curie-depth-EMAG2.ipynb)
+- [Ex1-Plot-power-spectrum.ipynb](pycurious/Examples/Notebooks/Bouligand/Ex1-Plot-power-spectrum.ipynb)
+- [Ex2-Compute-Curie-depth.ipynb](pycurious/Examples/Notebooks/Bouligand/Ex2-Compute-Curie-depth.ipynb)
+- [Ex3-Posing-the-inverse-problem.ipynb](pycurious/Examples/Notebooks/Bouligand/Ex3-Posing-the-inverse-problem.ipynb)
+- [Ex4-Spatial-variation-of-Curie-depth.ipynb](pycurious/Examples/Notebooks/Bouligand/Ex4-Spatial-variation-of-Curie-depth.ipynb)
+- [Ex5-Mapping-Curie-depth-EMAG2.ipynb](pycurious/Examples/Notebooks/Bouligand/Ex5-Mapping-Curie-depth-EMAG2.ipynb)
 
 
 ## Installation

diff --git a/pycurious/Examples/0-StartHere.ipynb b/pycurious/Examples/0-StartHere.ipynb
@@ -14,9 +14,18 @@
     "\n",
     "Launch the demonstration at [mybinder.org](https://mybinder.org/v2/gh/brmather/pycurious/binder?filepath=Notebooks%2F0-StartHere.ipynb)\n",
     "\n",
+    "\n",
     "## Navigation / Notebooks\n",
     "\n",
-    "There are two matching sets of `pycurious` notebooks - one set for the [Tanaka](#Tanaka) and one for [Bouligand](#Bouligand) implementations. The Bouligand set of noteboks are a natural choice for Bayesian inference applications.\n",
+    "There are two matching sets of Jupyter notebooks - one set for the [Tanaka](#Tanaka) and one for [Bouligand](#Bouligand) implementations. The Bouligand set of noteboks are a natural choice for Bayesian inference applications.\n",
+    "\n",
+    "Note, these examples can be installed from the package itself by running:\n",
+    "\n",
+    "```python\n",
+    "import pycurious\n",
+    "pycurious.install_documentation(path=\"Notebooks\")\n",
+    "```\n",
+    "\n",
     "\n",
     "### Tanaka\n",
     "\n",
@@ -32,13 +41,42 @@
     "- [Ex4-Spatial-variation-of-Curie-depth.ipynb](./Notebooks/Bouligand/Ex4-Spatial-variation-of-Curie-depth.ipynb)\n",
     "- [Ex5-Mapping-Curie-depth-EMAG2.ipynb](./Notebooks/Bouligand/Ex5-Mapping-Curie-depth-EMAG2.ipynb)\n",
     "\n",
-    "### Examples\n",
+    "## Installation\n",
     "\n",
-    "Note, these examples can be installed from the package itself by running:\n",
+    "### Dependencies\n",
     "\n",
-    "```python\n",
-    "import pycurious\n",
-    "pycurious.install_documentation(path=\"Notebooks\")\n",
+    "You will need **Python 2.7 or 3.5+**.\n",
+    "Also, the following packages are required:\n",
+    "\n",
+    "- [`numpy`](http://numpy.org)\n",
+    "- [`scipy`](https://scipy.org)\n",
+    "- [`cython`](https://cython.org/)\n",
+    "\n",
+    "__Optional dependencies__ for mapping module and running the Notebooks:\n",
+    "\n",
+    "- [`matplotlib`](https://matplotlib.org/)\n",
+    "- [`pyproj`](https://github.com/jswhit/pyproj)\n",
+    "- [`cartopy`](https://scitools.org.uk/cartopy/docs/latest/)\n",
+    "\n",
+    "### Installing using pip\n",
+    "\n",
+    "You can install `pycurious` using the\n",
+    "[`pip package manager`](https://pypi.org/project/pip/) with either version of Python:\n",
+    "\n",
+    "```bash\n",
+    "python2 -m pip install pycurious\n",
+    "python3 -m pip install pycurious\n",
+    "```\n",
+    "All the dependencies will be automatically installed by `pip`.\n",
+    "\n",
+    "### Installing using Docker\n",
+    "\n",
+    "A more straightforward installation for `pycurious` and all of its dependencies may be deployed with [Docker](https://www.docker.com).\n",
+    "To install the docker image and start the Jupyter notebook examples:\n",
+    "\n",
+    "```bash\n",
+    "docker pull brmather/pycurious:latest\n",
+    "docker run --name pycurious -p 8888:8888 brmather/pycurious:latest\n",
     "```\n",
     "\n",
     "## Usage\n",
@@ -65,43 +103,19 @@
     "k, Phi, sigma_Phi = grid.radial_spectrum(subgrid)\n",
     "```\n",
     "\n",
-    "## Installation\n",
-    "\n",
-    "To install with **setuptools**:\n",
+    "A series of tests are located in the *tests* subdirectory.\n",
+    "In order to perform these tests, clone the repository and run [`pytest`](https://pypi.org/project/pytest/):\n",
     "\n",
     "```bash\n",
-    "python setup.py install --user\n",
+    "git checkout https://github.com/brmather/pycurious.git\n",
+    "cd pycurious\n",
+    "pytest -v\n",
     "```\n",
     "\n",
-    "This will compile all C source code and install them to the user directory (omit the `--user` flag to install to the system directory). Remember to delete the build folder if you are upgrading this package.\n",
-    "\n",
-    "Alternatively, install using **pip**:\n",
+    "### API Documentation\n",
     "\n",
-    "```bash\n",
-    "pip install pycurious --user\n",
-    "```\n",
+    "The API for all functions and classes in `pycurious` can be accessed from [https://brmather.github.io/pycurious/](https://brmather.github.io/pycurious/).\n",
     "\n",
-    "### Dependencies\n",
-    "\n",
-    "- Python 2.7+ and 3.6+\n",
-    "- Numpy 1.9+\n",
-    "- Scipy 0.14+\n",
-    "- Cython\n",
-    "\n",
-    "Optional dependencies for mapping module:\n",
-    "\n",
-    "- Matplotlib\n",
-    "- [pyproj](https://github.com/jswhit/pyproj)\n",
-    "- [Cartopy](http://scitools.org.uk/cartopy/docs/latest/index.html)\n",
-    "\n",
-    "### Docker\n",
-    "\n",
-    "A more straightforward installation for `pycurious` and all of its dependencies may be deployed with [Docker](https://www.docker.com). To install the docker image and test it is working:\n",
-    "\n",
-    "```bash\n",
-    "docker pull brmather/pycurious:latest\n",
-    "docker run --rm brmather/pycurious:latest help\n",
-    "```\n",
     "\n",
     "## References\n",
     "\n",

diff --git a/pycurious/__init__.py b/pycurious/__init__.py
@@ -1,7 +1,26 @@
+# Copyright 2018-2019 Ben Mather, Robert Delhaye
+# 
+# This file is part of PyCurious.
+# 
+# PyCurious is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or any later version.
+# 
+# PyCurious 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 Lesser General Public License for more details.
+# 
+# You should have received a copy of the GNU Lesser General Public License
+# along with PyCurious.  If not, see <http://www.gnu.org/licenses/>.
+
 """
-Copyright 2018 Ben Mather, Robert Delhaye
 
-This file is part of PyCurious.
+> PyCurious is a Python package for computing the Curie depth from the magnetic anomaly.
+
+## Licence
+
+Copyright 2018-2019 Ben Mather, Robert Delhaye
 
 PyCurious is free software: you can redistribute it and/or modify
 it under the terms of the GNU Lesser General Public License as published by
@@ -14,6 +33,112 @@
 
 You should have received a copy of the GNU Lesser General Public License
 along with PyCurious.  If not, see <http://www.gnu.org/licenses/>.
+
+## Installation
+
+### Dependencies
+
+You will need **Python 2.7 or 3.5+**.
+Also, the following packages are required:
+
+- [`numpy`](http://numpy.org)
+- [`scipy`](https://scipy.org)
+- [`cython`](https://cython.org/)
+
+__Optional dependencies__ for mapping module and running the Notebooks:
+
+- [`matplotlib`](https://matplotlib.org/)
+- [`pyproj`](https://github.com/jswhit/pyproj)
+- [`cartopy`](https://scitools.org.uk/cartopy/docs/latest/)
+
+### Installing using pip
+
+You can install `pycurious` using the
+[`pip package manager`](https://pypi.org/project/pip/) with either
+version of Python:
+
+>>> python2 -m pip install pycurious
+>>> python3 -m pip install pycurious
+
+All the dependencies will be automatically installed by `pip`.
+
+### Installing using Docker
+
+A more straightforward installation for `pycurious` and all of its
+dependencies may be deployed with [Docker](https://www.docker.com).
+To install the docker image and start the Jupyter notebook examples:
+
+>>> docker pull brmather/pycurious:latest
+>>> docker run --name pycurious -p 8888:8888 brmather/pycurious:latest
+
+## Documenation / Notebooks
+
+Jupyter notebooks that demonstrate the functionality of PyCurious and
+some common workflows may be installed to a local directory with
+
+```python
+import pycurious
+pycurious.install_documentation(path="Notebooks")
+```
+
+## Contributing to pycurious
+
+We welcome contributions to `pycurious`, large or small [\\*](#footnote1).
+That can be in the form of new code, improvements to the documentation, 
+helping with a missing test, or it may even just be pointing out a bug or
+potential improvement to the team. 
+
+For bugs and suggestions, the most effective way to reach the team is by
+raising an issue on the github issue tracker. Github allows you to classify
+your issues so that we know if it is a bug report, feature request or
+feedback to the authors.
+
+If you wish to contribute some changes to the code then you should submit a
+*pull request*. On GitHub we can review the code that you are contributing
+and discuss it before the changes are merged into the development version of
+the code. Before embarking on changes to the code, please first take a look
+at the [`dev` branch](https://github.com/brmather/pycurious/tree/dev) which
+is where unreleased changes are staged: we may have been working on something
+similar already. 
+
+### How to create a Pull Request (PR)
+
+Create your own fork of the project on github: log into your github account,
+navigate to the [`pycurious` repository](https://github.com/brmather/pycurious/tree/dev)
+and click on the *fork* button at the top right corner of this repository.
+You can find detailed instructions and a discussion of how to fork a
+repository, clone it locally and work on the changes
+[in the GitHub guides](https://guides.github.com/activities/forking/). 
+
+### When to make your pull request
+
+It is much easier to merge in small changes to the code than extensive ones
+that touch multiple files. If a small incremental change is possible, please
+issue a request for that change rather than saving everything up. 
+
+It is a good idea to commit frequently and with commit messages that refer
+to the changes that have been make and why they have been made. The commit
+message is usually browsed without seeing the actual changes themselves and
+which sections of the code have been altered so a helpful message provides
+relevant details. 
+
+### Tests
+
+We use [`pytest`](https://pypi.org/project/pytest/) for the unit testing
+framework in `pycurious`. In the source directory this means running:
+
+>>> python setup.py test
+
+The existing tests should be passing before you start coding (help us out with
+an issue if that is not the case !) and when you have finished. Any new
+functionality should also have tests that we can use to verify the code.
+It is important that you make it clear if the original tests have had to
+change to accomodate new code / functionality.
+
+<a name="footnote1">*</a> _Small changes are our favorites as they are much
+easier to quickly merge into the existing code. Proofreading typos, bug fixes,
+... the little stuff is especially welcome._
+
 """
 
 # -*- coding: utf-8 -*-

diff --git a/pycurious/documentation.py b/pycurious/documentation.py
@@ -1,19 +1,23 @@
-"""
-Copyright 2018 Ben Mather, Robert Delhaye
-
-This file is part of PyCurious.
+# Copyright 2018-2019 Ben Mather, Robert Delhaye
+# 
+# This file is part of PyCurious.
+# 
+# PyCurious is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or any later version.
+# 
+# PyCurious 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 Lesser General Public License for more details.
+# 
+# You should have received a copy of the GNU Lesser General Public License
+# along with PyCurious.  If not, see <http://www.gnu.org/licenses/>.
 
-PyCurious is free software: you can redistribute it and/or modify
-it under the terms of the GNU Lesser General Public License as published by
-the Free Software Foundation, either version 3 of the License, or any later version.
-
-PyCurious 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 Lesser General Public License for more details.
+"""
+Use the `pycurious.documentation.install_documentation` function to copy all
+Jupyter Notebooks and example data to a local directory.
 
-You should have received a copy of the GNU Lesser General Public License
-along with PyCurious.  If not, see <http://www.gnu.org/licenses/>.
 """
 
 import pkg_resources as _pkg_resources
@@ -33,14 +37,14 @@ def install_documentation(path="./PyCurious-Examples"):
 
     Some dependencies exist for the notebooks to be useful:
 
-       - matplotlib: for some diagrams
-       - cartopy: for mapping and visualisation
-       - pyepsg: for converting between map projections
+       - `matplotlib`: for some diagrams
+       - `cartopy`: for mapping and visualisation
+       - `pyepsg`: for converting between map projections
 
     PyCurious dependencies may be explicitly imported in the notebooks including:
 
-       - numpy
-       - scipy
+       - `numpy`
+       - `scipy`
 
     """