mkdocs site for pytom-match-pick (#199)

* feature: add deploy docs workflow for main * initial mkdocs setup * fix: update README to contain info for website * update: add wiki files to docs * fix: make images and latex work in tutorial * fix: entry point docs could not be snipped due to a syntax issue * fix execution of argparse code in markdown exec * add: snippet points to all argument parsers in entry points * fix: weird formatting * feature: working version that can render the argparse help to the docs page * fix: move usage of template and mask creation to the new page * fix: move template matching info to Usage page * fix: add the extracting particles section * reduce docs * fix: move the merging annotations docds * fix: remove the previous Home page * fix: move the particle handedness page to the FAQ * feature: add relion5 starfile header to Developers page * fix: remove redundant header * fix: grammar * fix: update some docs in the workflow * add conditional to only trigger for pushes to main of sbc-utrecht/pytom-match-pick * update math * Apply suggestions from code review Co-authored-by: Sander Roet <[email protected]> * fix: remove unused images to prevent unnecessary storage; correct a link * fix: add install dependencies for website * update: readme for mkdocs local test * fix: angstrom symbol in math --------- Co-authored-by: Sander Roet <[email protected]>
SBC-Utrecht · Aug 2, 2024 · 4abdb7a · 4abdb7a
1 parent eec9a7a
commit 4abdb7a
Show file tree

Hide file tree

Showing 20 changed files with 3,935 additions and 25 deletions.
diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml
@@ -0,0 +1,37 @@
+name: docs
+
+on:
+  push:
+    branches:
+      - main
+
+# This job installs dependencies, builds the docs, and pushes it to
+# the `gh-pages` branch of the same repository.
+jobs:
+  deploy-book:
+    if: github.repository == ‘SBC-Utrecht/pytom-match-pick’
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+
+      - name: Install dependencies
+        run: |
+          pip install mkdocs mkdocs-material markdown-exec
+
+      # Build the book
+      - name: Build the book
+        run: |
+          mkdocs build
+
+      # Push the site to github-pages
+      - name: GitHub Pages action
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          publish_dir: ./site
+          github_token: ${{ secrets.GITHUB_TOKEN }}
diff --git a/README.md b/README.md
@@ -4,9 +4,16 @@
 
 # pytom-match-pick: GPU template matching for cryo-ET
 
-GPU template matching, originally developed in [PyTom](https://github.com/SBC-Utrecht/PyTom), as a standalone python package that can be run from the command line.
+GPU template matching, originally developed in [PyTom](https://github.
+com/SBC-Utrecht/PyTom), as a standalone python package that is run from the command 
+line.
 
-![cover_image](images/tomo200528_100_illustration.png)
+![cover_image](docs/images/tomo200528_100_illustration.png)
+
+<!--
+This line starts the block that is incorporated into the website via mkdocs snippets
+-->
+#--8<-- [start:docs]
 
 ## Requires
 
@@ -54,7 +61,7 @@ The installation above also adds the optional dependencies `[matplotlib, seaborn
 python -m pip install pytom-match-pick
 ```
 
-## Cupy warning
+### Cupy warning
 Having issues running the software? If cupy is not correctly installed, 
 ```commandline
 python -c "import pytom_tm"
@@ -72,10 +79,6 @@ specific build compatible with the installed cuda toolkit.
 
 ## Usage
 
-Detailed usage instructions are available on the wiki: https://github.com/SBC-Utrecht/pytom-match-pick/wiki
-
-Also, a tutorial can be found on the same wiki: https://github.com/SBC-Utrecht/pytom-match-pick/wiki/Tutorial
-
 The following scripts are available to run with `--help` to see parameters:
 
 - create a template from an mrc file containing a density map: `pytom_create_template.py --help`
@@ -85,6 +88,8 @@ The following scripts are available to run with `--help` to see parameters:
 - estimate an ROC curve from a job file (.json): `pytom_estimate_roc.py --help`
 - merge multiple star files to a single starfile: `pytom_merge_stars.py --help`
 
+Detailed usage instructions and a tutorial are available on [our site](https://SBC-Utrecht.github.io/pytom-match-pick).
+
 ## Usage questions, ideas and solutions, engagement, etc
 Please use our [github discussions](https://github.com/SBC-Utrecht/pytom-match-pick/discussions) for:
  - Asking questions about bottlenecks.
@@ -113,7 +118,13 @@ you make PRs:
 pre-commit install
 ```
 
-This uses Ruff to check and format whenever you make commits. 
+This uses Ruff to check and format whenever you make commits.
+
+If you update anything in the (documentation) `docs/` folder make sure to test build the website locally:
+
+```commandline
+mkdocs serve
+```
 
 ## Tests
 
@@ -148,3 +159,8 @@ For a reference on GPU accelerated template matching in tomograms please see the
     DOI = {10.3390/ijms241713375}
 }
 ```
+
+<!--
+This ends the block for the website
+-->
+#--8<-- [end:docs]
diff --git a/docs/Developers.md b/docs/Developers.md
@@ -0,0 +1,47 @@
+Star files written out by pytom-match-pick should be easily integratable with other software as it follows RELION star file conventions. The only difference are three column headers with extraction statistics, which are important to maintain for annotations.
+
+The exact header is:
+
+```
+# Created by the starfile Python package (version x.x.x) at xx:xx:xx on xx/xx/xxxx
+
+
+data_
+
+loop_
+_rlnCoordinateX #1
+_rlnCoordinateY #2
+_rlnCoordinateZ #3
+_rlnAngleRot #4
+_rlnAngleTilt #5
+_rlnAnglePsi #6
+_rlnLCCmax #7
+_rlnCutOff #8
+_rlnSearchStd #9
+_rlnDetectorPixelSize #10
+_rlnMicrographName #11
+```
+
+With RELION5 compatibility mode in `pytom_extract_candidates.py` the star file 
+columns are this (correcting the position in to Angstrom and relative to the 
+tomogram center):
+
+```
+# Created by the starfile Python package (version x.x.x) at xx:xx:xx on xx/xx/xxxx
+
+
+data_
+
+loop_
+_rlnCenteredCoordinateXAngst #1
+_rlnCenteredCoordinateYAngst #2
+_rlnCenteredCoordinateZAngst #3
+_rlnAngleRot #4
+_rlnAngleTilt #5
+_rlnAnglePsi #6
+_rlnLCCmax #7
+_rlnCutOff #8
+_rlnSearchStd #9
+_rlnDetectorPixelSize #10
+_rlnTomoName #11
+```
diff --git a/docs/Frequently-asked-questions-(FAQ).md b/docs/Frequently-asked-questions-(FAQ).md
@@ -0,0 +1,34 @@
+## How to deal with gold beads?
+
+Gold beads (and other artifacts) can often interfer in template matching due to their high electron scattering potential. The easiest way to deal with them is by removing them on the micrograph level prior to reconstruction. The following IMOD commands can do the trick:
+
+```
+imodfindbeads -size [GOLD_BEAD_DIAMETER_IN_PIXELS] -input TS_ID.st -output  TS_ID.fid  -spacing 0.8
+ccderaser --input TS_ID.st --output TS_ID_erased.st -model TS_ID.fid -order 0 -circle / -better [1.5 * GOLD_BEAD_RADIUS_IN_PIXELS] -merge 1 -exclude -skip 1 -expand 3
+```
+
+## What template box size should I use?
+
+For the simple missing wedge model a box size that tightly fits the template and mask is easiest (and slightly faster).
+
+For the full per-tilt-weighting model its better to have some overhang, a rought estimate could be a box size of `4 * particle_diameter`. This aids in sampling the CTF function and the individual tilts in Fourier space. However, the mask radius should still snuggly fit the template. Although the larger box size slows down rotations slightly, the search benefits more from better sampling of the weighting function.
+
+## Is my particle handedness correct?
+
+If template matching is giving unexpectedly poor results for the particle of interest, it might that the template has the wrong handedness. In that case, the `pytom_create_template.py` has the option `--mirror` to produce a mirrored version of the template. We advice to create a mirrored and non-mirrored version of the template and to run template matching with both. After extracting ~1000 particle from both jobs, while setting the `--cut-off` to -1 (in `pytom_extract_candidates.py`). You can plot the results with the following python code:
+
+```
+import starfile
+import matplotlib.pyplot as plt
+
+raw = starfile.read('[TOMO_ID]_particles.star')
+mirror = starfile.read('[TOMO_ID]_mirror_particles.star')
+
+fig, ax = plt.subplots(figsize=(5,5))
+ax.plot(raw['ptmLCCmax'], label='raw')
+ax.plot(mirror['ptmLCCmax'], label='mirror')
+ax.set_xlabel('Particle index')
+ax.set_ylabel('LCCmax')
+ax.legend()
+plt.show()
+```
diff --git a/docs/Timings.md b/docs/Timings.md
@@ -0,0 +1,14 @@
+
+This page provides a quick overview of software timings. All were run on a tomogram with dimension (462x478x250) and a template box size of 34x34x34.
+
+```
+Single GPU (GTX 1080 Ti)
+12.85 (deg) - 193 sec. (3.22 min.)
+```
+
+```
+4 GPU's (GTX 1080 Ti)
+12.85 (deg) - 48 sec. (0.80 min.)
+7.00 (deg) - 306 sec. (5.10 min.)
+3.00 (deg) - 3801 sec. (63.35 min.)
+```