Re-merging changes of #49 into main (#51)

* update image path to be url rather than local path

* Update version of cartopy for JBook

* update logo to be relevant to this study

* Create intro markdown

The goal is to make an intro markdown file that quickly directs the
user to the most relevant notebooks.

* create installation.md

* simplify notebook explanations in grid

* Update toc given new files

Add the new intro and installation markdown files.
Adjust order of analysis notebooks.

---------

Co-authored-by: Nick Swanson-Hysell <[email protected]>

.github/workflows/book.yml

@@ -24,8 +24,8 @@ jobs:
         python-version: 3.9
     - name: Install dependencies manually
       run: |
-        pip install future matplotlib cartopy pandas requests seaborn jupyter-book scikit-learn ipywidgets
-        # pip install jupyter-book matplotlib numpy pandas future cartopy
+        pip install future matplotlib pandas requests seaborn jupyter-book scikit-learn ipywidgets
+        pip install cartopy==0.22
         pip install pmagpy==4.2.106
         pip install -e ./smpsite
         

_toc.yml

@@ -1,12 +1,15 @@
 format: jb-book
-root: book/Main
+root: book/intro
 
 parts:
+- caption: Installation
+  chapters:
+    - file: book/installation
 - caption: Analysis
   chapters:
-    - file: notebooks/Sampling_example.ipynb
-    - file: notebooks/Sampling_comparison.ipynb
     - file: notebooks/DIY-Figure1.ipynb
+    - file: notebooks/Sampling_comparison.ipynb
+    - file: notebooks/Sampling_example.ipynb
 - caption: Figures
   chapters:
     - file: figures/figure1/Figure1.ipynb

book/installation.md

@@ -0,0 +1,35 @@
+## Installation
+
+All the notebooks inside this JupyterBook can be executed after properly setting the environment. The `environment.yml` file in the [GitHub repository](https://github.com/PolarWandering/PaleoSampling) can be used to
+install all the required dependencies. Beside some standard Python dependencies, the `environment.yml` file include the installation of
+`Pmagpy` using pip and the extra installation of the module `smpsite` (included in this repository). The package `smpsite` includes all the code used to make the simulations and compute the
+estimated poles.
+
+In order to install the environment, you can use conda or mamba (see [Managing Environments](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html) for more information) with `conda env create -f environment.yml`. Once the environment is created, you can create the associated iPython kernel with 
+```
+python -m ipykernel install --user --name paleostats --display-name "IPython - PaleoStats"
+```
+This will allow you to execute this environment directly from Jupyter notebooks. 
+
+Alternatively, we included a `Makefile` in the [GitHub repository](https://github.com/PolarWandering/PaleoSampling) that creates the conda environment and installs the associated iPython kernel so this environment can be accessible though Jupyter notebooks all at once. In order to use the Makefile, you need to open a terminal where the repository is located and enter
+```
+make env
+```
+
+Alternatively, if you just want to install the `smpsite` module, you can clone this repository and do
+```
+pip install smpsite
+```
+or
+```
+pip install -e smpsite
+```
+if you are working in developer mode. 
+
+### Makefile
+
+The current [repository](https://github.com/PolarWandering/PaleoSampling) contains a `Makefile` that allows the user to run different routines on the code. You can move in a terminal to the
+path to this repository and use the following commands to trigger their respective actions. 
+- `make env`: Creates the conda environment associated with the `environment.yml` file and then creates the respective iPython kernel such that the 
+environment can be accessed via Jupyter notebooks. 
+- `make help`: Prints a short description of all available commands and their explanation. 

book/intro.md

@@ -0,0 +1,107 @@
+---
+title: PaleoSampling
+---
+
+# Quantitative Analysis of Paleomagnetic Sampling Strategies
+
+This JupyterBook contains notebooks to analyze different sampling procedures in order to estimate the precision of different strategies for estimating paleomagnetic poles and paleosecular variation of the magnetic field based on site magnetizations. It also contains the notebooks that generate all the figures of [Sapienza et al. 2023](https://doi.org/10.1029/2023JB027211).
+
+::::{grid} 1 1 2 2
+:class-container: text-center
+:gutter: 3
+
+:::{grid-item-card}
+:link: ../notebooks/DIY-Figure1
+:link-type: doc
+:class-header: bg-light
+
+DIY Figure 1 📈
+^^^
+
+```{image} ../figures/logo.png
+:width: 200
+```
+
+This notebook enables a researcher to compute the mean error associated with paleopole estimation given different sampling strategies. It generates a "do-it-yourself" version of Figure 1 of Sapienza et al. 2023 using the theoretical approximation.
+
+:::
+
+:::{grid-item-card}
+:link: ../notebooks/Sampling_comparison
+:link-type: doc
+:class-header: bg-light
+
+Sampling strategy comparison ✏️
+^^^
+
+```{image} ../figures/figure3_histogram/Figure3a.png
+:width: 250
+```
+
+Compare the distribution of paleopole estimation errors for two sampling strategies through simulation. The user can vary parameters (e.g. # of samples per site, outlier rate, and within-site precision) to make their own version of Sapienza et al. 2023 Figure 3.
+:::
+
+::::
+
+## Running the notebooks yourself
+
+The notebooks within this JupyterBook book are a static rendition of the code. Running the code yourself enables you to change the parameters to best fit your study by either creating a Python environment to run the code locally or by opening the PaleoSampling repository on Binder.
+
+### Run the code locally 💻
+
+For instructions for how to set up your environment to run the notebooks on your computer, see the [installation instructions](installation.md).
+
+### Run on Binder ☁️
+
+To open a cloud JupyterHub version of the notebooks in this repository and run them on Binder used the following Binder link. Note that the repository will take a long time to load as the environment is being created: [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/PolarWandering/PaleoSampling/HEAD)
+
+## How to cite 📖
+
+If you want to cite this work, the citation is:
+
+Sapienza, F., Gallo, L. C., Zhang, Y., Vaes, B., Domeier, M., & Swanson-Hysell, N. L. (2023). Quantitative Analysis of Paleomagnetic Sampling Strategies. Journal of Geophysical Research: Solid Earth, 128, e2023JB027211. https://doi.org/10.1029/2023JB027211
+
+You can use this BibTex citation:
+```
+@article{Sapienza2023_Quantitative,
+author = {Sapienza, F. and Gallo, L. C. and Zhang, Y. and Vaes, B. and Domeier, M. and Swanson-Hysell, N. L.},
+title = {Quantitative Analysis of Paleomagnetic Sampling Strategies},
+journal = {Journal of Geophysical Research: Solid Earth},
+pages = {e2023JB027211},
+keywords = {Paleomagnetism, Paleopole estimation, Secular variation, Error quantification},
+doi = {https://doi.org/10.1029/2023JB027211},
+}
+```
+If you want to cite the software in this repository, you can instead use the following DOI in Zenodo:
+
+[![DOI](https://zenodo.org/badge/595793364.svg)](https://zenodo.org/badge/latestdoi/595793364)
+
+or use this bibtex entry: 
+```
+@software{Sapienza_PaleoSampling,
+  author = {Sapienza, Facundo and Gallo, Leandro Cesar and Zhang, Yiming and Vaes, Bram and Domeier, Mathew and Swanson-Hysell, Nick},
+  title = {PaleoSampling},
+  month = sep,
+  year = 2023,
+  note = {{Quantitative Analysis of Paleomagnetic Sampling Strategies}},
+  publisher = {Zenodo},
+  version = {v1.0.0},
+  doi = {10.5281/zenodo.8347149},
+  url = {https://doi.org/10.5281/zenodo.8347149}
+}
+```
+
+## Contributors
+
+<table>
+  <tbody>
+    <tr>
+      <td align="center" valign="top" width="14.28%"><a href="http://facusapienza.com"><img src="https://avatars.githubusercontent.com/u/39526081?v=4?s=100" width="100px;" alt="Facundo Sapienza"/><br /><sub><b>Facundo Sapienza</b></sub></a><br /><a href="#doc-facusapienza21" title="Documentation">📖</a> <a href="#code-facusapienza21" title="Code">💻</a> <a href="#infra-facusapienza21" title="Infrastructure (Hosting, Build-Tools, etc)">🚇</a> <a href="#design-facusapienza21" title="Design">🎨</a> <a href="#maintenance-facusapienza21" title="Maintenance">🚧</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/LenGallo"><img src="https://avatars.githubusercontent.com/u/29756069?v=4?s=100" width="100px;" alt="Leandro Gallo"/><br /><sub><b>Leandro Gallo</b></sub></a><br /><a href="#code-LenGallo" title="Code">💻</a> <a href="#bug-LenGallo" title="Bug reports">🐛</a> <a href="#mentoring-LenGallo" title="Mentoring">🧑‍🏫</a> <a href="#design-LenGallo" title="Design">🎨</a> <a href="#question-LenGallo" title="Answering Questions">💬</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="http://www.swanson-hysell.org"><img src="https://avatars.githubusercontent.com/u/4332322?v=4?s=100" width="100px;" alt="Nick Swanson-Hysell"/><br /><sub><b>Nick Swanson-Hysell</b></sub></a><br /><a href="#review-Swanson-Hysell" title="Reviewed Pull Requests">👀</a> <a href="#doc-Swanson-Hysell" title="Documentation">📖</a> <a href="#design-Swanson-Hysell" title="Design">🎨</a> <a href="#mentoring-Swanson-Hysell" title="Mentoring">🧑‍🏫</a> <a href="#code-Swanson-Hysell" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/matdomeier"><img src="https://avatars.githubusercontent.com/u/40273197?v=4?s=100" width="100px;" alt="matdomeier"/><br /><sub><b>matdomeier</b></sub></a><br /><a href="#ideas-matdomeier" title="Ideas, Planning, & Feedback">🤔</a> <a href="#design-matdomeier" title="Design">🎨</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://www.uu.nl/medewerkers/BVaes"><img src="https://avatars.githubusercontent.com/u/94557078?v=4?s=100" width="100px;" alt="Bram Vaes"/><br /><sub><b>Bram Vaes</b></sub></a><br /><a href="#design-bramvaes" title="Design">🎨</a> <a href="#ideas-bramvaes" title="Ideas, Planning, & Feedback">🤔</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://duserzym.github.io/"><img src="https://avatars.githubusercontent.com/u/39976081?v=4?s=100" width="100px;" alt="Yiming Zhang"/><br /><sub><b>Yiming Zhang</b></sub></a><br /><a href="#ideas-duserzym" title="Ideas, Planning, & Feedback">🤔</a></td>
+    </tr>
+  </tbody>
+</table>

notebooks/Sampling_comparison.ipynb

@@ -11,7 +11,7 @@
     "\n",
     "<table style=\"border-collapse: collapse; border: none;\">\n",
     "    <tr>\n",
-    "        <td style=\"border: none;\"><img src=\"../figures/figure3_histogram/Figure3a.png\" width=\"500\"></td>\n",
+    "        <td style=\"border: none;\"><img src=\"https://raw.githubusercontent.com/PolarWandering/PaleoSampling/57e98e6cc79638b28949893508981cbfcc3a1643/figures/figure3_histogram/Figure3a.png\" width=\"500\"></td>\n",
     "        <td style=\"border: none; vertical-align: bottom; width: 300px;\">\n",
     "            <b>Figure 3a:</b> Comparison between two different sampling strategies to determine a mean paleomagnetic pole position in the presence of outliers for a fixed number of total samples (n = 100). The red histograms and curve are strategy 1 where we have one sample per site (n0 = 1), one hundred sites (N = 100) and we use the Vandamme filter. The blue histograms and curve are strategy 2 where n0 = 5, (N = 20) and we filter all the outliers (perfect detection algorithm) for (a) p_outlier = 0.10.\n",
     "        </td>\n",