Reworking the documentation

docs/.gitignore

@@ -0,0 +1,5 @@
+# sphinx build folder
+_build
+
+# singularity images
+*.sif

docs/README.md

@@ -0,0 +1,23 @@
+This is the code for the mobest documentation website. It uses the [Sphinx documentation generator](https://www.sphinx-doc.org/en/master).
+
+To build the website you need the sphinx CLI tool and a number of extensions for it. `sphinx.def` defines an [apptainer](https://apptainer.org) image with the complete setup.
+
+The image can be build with
+```
+apptainer build docs/sphinx.sif docs/sphinx.def
+```
+
+For development the latest state of the documentation can be rendered with
+```
+apptainer exec docs/sphinx.sif sphinx-build docs docs/_build/html
+```
+
+For deployment it should be build with [sphinx-multiversion](https://holzhaus.github.io/sphinx-multiversion/master/index.html), which will build separate documentation folders for each git tag (considers only committed changes!)
+```
+apptainer exec docs/sphinx.sif sphinx-multiversion docs docs/_build/html
+```
+
+To see the automatically generated label section to reference them (as described [here](https://docs.readthedocs.io/en/stable/guides/cross-referencing-with-sphinx.html)):
+```
+apptainer exec docs/sphinx.sif python -m sphinx.ext.intersphinx docs/_build/html/objects.inv
+```

docs/_templates/versions.html

@@ -0,0 +1,27 @@
+{%- if current_version %}
+<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
+  <span class="rst-current-version" data-toggle="rst-current-version">
+    <span class="fa fa-book"> Other Versions</span>
+    v: {{ current_version.name }}
+    <span class="fa fa-caret-down"></span>
+  </span>
+  <div class="rst-other-versions">
+    {%- if versions.tags %}
+    <dl>
+      <dt>Tags</dt>
+      {%- for item in versions.tags %}
+      <dd><a href="{{ item.url }}">{{ item.name }}</a></dd>
+      {%- endfor %}
+    </dl>
+    {%- endif %}
+    {%- if versions.branches %}
+    <dl>
+      <dt>Branches</dt>
+      {%- for item in versions.branches %}
+      <dd><a href="{{ item.url }}">{{ item.name }}</a></dd>
+      {%- endfor %}
+    </dl>
+    {%- endif %}
+  </div>
+</div>
+{%- endif %}

docs/bibliography.md

@@ -0,0 +1,4 @@
+# Bibliography
+
+```{bibliography} references.bib
+```

docs/citation.md

@@ -0,0 +1,29 @@
+# How to cite mobest
+
+If you use mobest for a scientific publication, please cite {cite:p}`Schmid2023`:
+
+```none
+@article{Schmid2023,
+  doi = {10.1073/pnas.2218375120},
+  url = {https://doi.org/10.1073/pnas.2218375120},
+  year = {2023},
+  month = feb,
+  publisher = {Proceedings of the National Academy of Sciences},
+  volume = {120},
+  number = {9},
+  author = {Clemens Schmid and Stephan Schiffels},
+  title = {Estimating human mobility in Holocene Western Eurasia with large-scale ancient genomic data},
+  journal = {Proceedings of the National Academy of Sciences}
+}
+```
+
+In the **materials section** you should
+
+- document the specific software version you used
+- explain the input data, specifically
+  - how the input data was prepared and selected
+  - how the spatial and temporal positions for each input sample was defined
+  - how the position in dependent variable space was obtained (e.g. PCA on genotype data)
+- list the kernel parameter settings and explain how they were obtained
+
+Naturally **all code and data used to generate the mobest results should be shared** with the publication to ensure computational reproducibility.

docs/conf.py

@@ -0,0 +1,41 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'mobest'
+copyright = '2023, Clemens Schmid'
+author = 'Clemens Schmid'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+  'myst_parser',
+  'sphinx_rtd_theme',
+  'sphinx_multiversion',
+  'sphinxcontrib.bibtex',
+  'sphinx.ext.autosectionlabel'
+]
+
+myst_enable_extensions = [
+  "dollarmath"
+]
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+exclude_patterns = ['README.md']
+
+bibtex_bibfiles = ['references.bib']
+
+# make sure the autosectionlabel targets are unique
+autosectionlabel_prefix_document = True
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'

docs/data/.gitignore

@@ -0,0 +1,3 @@
+Dataset_S1.csv
+Dataset_S2.csv
+*.zip

docs/data/hpc_crossvalidation/compile.R

@@ -0,0 +1,10 @@
+kernel_grid <- purrr::map_dfr(
+  list.files(
+    path = "docs/data/hpc_crossvalidation",
+    pattern = "*.csv",
+    full.names = TRUE
+  ),
+  function(x) {
+    readr::read_csv(x, show_col_types = FALSE)
+  }
+)

docs/data/hpc_crossvalidation/cross.R

@@ -0,0 +1,67 @@
+library(magrittr)
+
+args <- unlist(strsplit(commandArgs(trailingOnly = TRUE), " "))
+run <- args[1]
+ds_for_this_run <- as.numeric(args[2])
+dt_for_this_run <- as.numeric(args[3])
+
+samples_projected <- readr::read_csv(
+  "docs/data/samples_projected.csv"
+)
+
+ind <- mobest::create_spatpos(
+  id = samples_projected$Sample_ID,
+  x  = samples_projected$x,
+  y  = samples_projected$y,
+  z  = samples_projected$Date_BC_AD_Median
+)
+dep <- mobest::create_obs(
+  C1 = samples_projected$MDS_C1,
+  C2 = samples_projected$MDS_C2
+)
+
+kernel_for_this_run <- mobest::create_kernset_multi(
+  mobest::create_kernset(
+    C1 = mobest::create_kernel(
+      dsx = ds_for_this_run*1000,
+      dsy = ds_for_this_run*1000,
+      dt  = dt_for_this_run,
+      g   = 0.071
+    ),
+    C2 = mobest::create_kernel(
+      dsx = ds_for_this_run*1000,
+      dsy = ds_for_this_run*1000,
+      dt  = dt_for_this_run,
+      g   = 0.059
+    )
+  ),
+  .names = paste0("kernel_", run)
+)
+
+set.seed(123)
+
+interpol_comparison <- mobest::crossvalidate(
+  independent = ind,
+  dependent   = dep,
+  kernel      = kernel_for_this_run,
+  iterations  = 10,
+  groups      = 10,
+  quiet       = F
+)
+
+kernel_grid <- interpol_comparison %>%
+  dplyr::group_by(
+    dependent_var_id, ds = dsx, dt) %>%
+  dplyr::summarise(
+    mean_squared_difference = mean(difference^2),
+    .groups = "drop"
+  )
+
+readr::write_csv(
+  kernel_grid,
+  file = paste0(
+    "docs/data/hpc_crossvalidation/kernel_grid_",
+    sprintf("%06d", as.integer(run)),
+    ".csv"
+  )
+)

docs/data/hpc_crossvalidation/run.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+#
+#$ -S /bin/bash  # defines bash as the shell for execution
+#$ -N cross      # name of the command that will be listed in the queue
+#$ -cwd          # change to the current directory
+#$ -j y          # join error and standard output in one file
+#$ -o ~/log      # standard output file or directory
+#$ -q archgen.q  # queue
+#$ -pe smp 2     # use X CPU cores
+#$ -l h_vmem=10G # request XGb of memory
+#$ -V            # load personal profile
+#$ -t 1-225      # array job length
+#$ -tc 25        # number of concurrently submitted tasks
+
+date
+
+echo Task in Array: ${SGE_TASK_ID}
+i=$((SGE_TASK_ID - 1))
+
+ds_to_explore=($(seq 100 100 1500))
+dt_to_explore=($(seq 100 100 1500))
+dss=()
+dts=()
+for ds in "${ds_to_explore[@]}"
+do
+  for dt in "${dt_to_explore[@]}"
+  do
+    dss+=($ds)
+    dts+=($dt)
+  done
+done
+current_ds=${dss[${i}]}
+current_dt=${dts[${i}]}
+
+echo ds: ${current_ds}
+echo dt: ${current_dt}
+
+apptainer exec \
+  --bind=/mnt/archgen/users/schmid/mobest \
+  /mnt/archgen/users/schmid/mobest/apptainer_mobest.sif \
+  Rscript /mnt/archgen/users/schmid/mobest/docs/data/hpc_crossvalidation/cross.R ${i} ${current_ds} ${current_dt} \
+  /
+
+date
+exit 0