Documentation update

Author: PlethoraChutney

README.md

@@ -11,6 +11,8 @@ These packages are mostly used for plotting, so if you do not wish to install th
 
 Once dependencies are installed, you can run notebooks (`*.ipynb`) using your [Jupyter Notebook](https://jupyter.org/) environment of choice.
 You can run python scripts (`*.py`) directly in the terminal in the usual way (`path/to/script.py` or `python path/to/script.py`).
+If you click a notebook in GitHub it will open so that you can see the result of each cell.
+Python scripts do not have this feature, but are contained in their own directory with a README explaining the script's usage.
 
 ## 💻 Where can I run these scripts from?
 The scripts and notebooks do *not* need to be run on the master node --- they simply need to have access to the following ports:

attachments/custom-latent-traj-points.png

@@ -1,5 +1,13 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Back to CS UID\n",
+    "Sometimes particles must be processed outside CryoSPARC and then re-imported. Unfortunately, the re-imported particles have new UIDs, making some jobs more difficult or impossible in CryoSPARC. This script re-assigns the original UIDs to particles, provided they were not externally re-extracted."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -29,6 +37,13 @@
     "project = cs.find_project(project_uid)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Here we load particles from two jobs. The first (J134 in this case) was never exported from CryoSPARC. This job provides the original UIDs. The second (J217 in this case) is the Import Particles job that was used to re-import the particles after external processing."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 2,
@@ -43,10 +58,11 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
+    "# function to strip UIDs from micrographs\n",
     "uid_pattern = r\"^[0-9]{21}_\"\n",
     "def remove_uid(uid_mic:str) -> str:\n",
     "    uid_mic = uid_mic.split('/')[-1]\n",
@@ -59,10 +75,11 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
+    "# \"img\" is a temporary field which combines the particle stack and blob index for a given particle\n",
     "rel_parts.add_fields(fields = ['img'], dtypes = ['str'])\n",
     "rel_parts['img'] = [\n",
     "    f\"{i}@{remove_uid(m)}\"\n",
@@ -109,6 +126,7 @@
     }
    ],
    "source": [
+    "# remove the temporary field and save the particles with CryoSPARC UIDs to the workspace.\n",
     "drop_image = rel_parts.drop_fields('img', copy = True)\n",
     "cs.save_external_result(\n",
     "    project_uid,\n",

attachments/custom-latent-traj-smoothed.png

@@ -0,0 +1,24 @@
+# Changing Pixel Size
+
+The scripts in this directory create a new output with an updated pixel size, perhaps found as a result of pixel size calibrations performed using earlier results.
+
+## `change_apix_extract.py`
+
+This script changes the pixel size of all particles in a stack to a provided value.
+Note that only particle metadata is changed, and it is only changed for the new particle output this job creates.
+No existing jobs are modified.
+Note also that the micrograph pixel sizes are *not* changed, so if the particles are re-extracted their pixel sizes will revert to the old value.
+
+Example usage:
+```
+change_apix_extract.py P123,W2,J456 1.008
+```
+
+## `change_apix_micrographs.py`
+
+This script changes all of the pixel size fields of a set of micrographs.
+
+Example usage:
+```
+change_apix_micrographs.py P123,W2,J456 1.008
+```

back-to-cs-uid.ipynb

@@ -1,5 +1,14 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Check Pose Duplicates\n",
+    "This notebook checks a particle stack for particles with identical poses and stores their UIDs in a set for downstream use.\n",
+    "This may be useful if one wishes to [remove particles only when their location *and pose* are identical](https://discuss.cryosparc.com/t/remove-duplicates-considering-orientation/13474/6?u=rwaldo) (or very close)."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 165,

change-pixel-size/README.md

@@ -1,5 +1,13 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Class 2D No Gaps\n",
+    "This notebook plots 2D Classes with no gaps between them."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 23,

change_apix_extract.py change-pixel-size/change_apix_extract.pychange_apix_extract.py renamed to change-pixel-size/change_apix_extract.py

@@ -1,5 +1,14 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Count Sym Exp Copies\n",
+    "This notebook counts and plots the number of symmetry-expanded copies of a particle remain in a particle stack.\n",
+    "It may be useful when using classification on symmetry-expanded particles to count the occurance of a given feature."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 6,