diff --git a/.github/workflows/README from docs.yaml b/.github/workflows/README from docs.yaml new file mode 100644 index 0000000..5aaa8b9 --- /dev/null +++ b/.github/workflows/README from docs.yaml @@ -0,0 +1,53 @@ +name: Generate README + +on: + pull_request: + paths: + - "docs/**/*" + workflow_run: + workflows: + - "generate_help_docs" + +jobs: + make-README: + runs-on: ubuntu-latest + permissions: + contents: write + steps: + - uses: actions/checkout@v4 + - name: Fill template + working-directory: "docs/" + timeout-minutes: 0.1 + run: | + sub_doc_parts_from() { + template="$1" + directory="$2" + + for file in "$directory"/*; do + if [ -f "$file" ]; then + placeholder="{{ $(echo "${file^^}" | tr ./ _) }}" + echo "Saving $file to $placeholder with expanded environment variables" >&2 + # Export file contents to text following a pattern in template.md, e.g.: + # section/test_file.md would replace "{{ SECTION_TEST_FILE_MD }}"" + template="${template//"$placeholder"/"$(<"$file")"}" + fi + done + echo "$template" + } + # Fills from docs/sections sections, then docs/help (note "working-directory") + sub_doc_parts_from "$(sub_doc_parts_from "$(../README.md + - name: Setup git + run: | + git config --local user.name "github-actions[bot]" + git config --local user.email "github-actions[bot]@users.noreply.github.com" + git remote set-url origin https://${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }} + - name: Push changes (if any) + run: | + git pull + if git update-index --refresh && git diff-index --quiet HEAD --; then + git add README.md + git commit -m "Automated update of README.md from docs" + + branch_name="${GITHUB_HEAD_REF:-${GITHUB_REF#refs/heads/}}" + git push origin HEAD:$branch_name + fi diff --git a/.github/workflows/generate_help_docs.yaml b/.github/workflows/generate_help_docs.yaml new file mode 100644 index 0000000..4ef4e65 --- /dev/null +++ b/.github/workflows/generate_help_docs.yaml @@ -0,0 +1,47 @@ +name: Generate README + +on: + pull_request: + paths: + - "src/sim_recon/cli/parsing/*" + - "src/sim_recon/settings/formatting.py" + +jobs: + generate-help-docs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Set up Python + uses: actions/setup-python@v5 + - name: Display Python version + run: python -c "import sys; print(sys.version)" + - name: Copy template + run: cp -f docs/template.md README.md + - name: Install (without dependencies) + run: | + python -m pip install --upgrade pip + python -m pip install . --no-deps + - name: Ensure README exists + run: | + if [ ! -f "README.md" ]; then + touch README.md + fi + - name: Get help strings from package + run: | + python -m sim_recon.cli.parsing.otf '--help' >docs/help/sim_otf.txt + python -m sim_recon.cli.parsing.recon '--help' >docs/help/sim_recon.txt + python -m sim_recon.cli.parsing.otf_view '--help' >docs/help/otf_view.txt + - name: Setup git + run: | + git config --local user.name "github-actions[bot]" + git config --local user.email "github-actions[bot]@users.noreply.github.com" + git remote set-url origin https://${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }} + - name: Push changes (if any) + run: | + if git update-index --refresh && git diff-index --quiet HEAD --; then + git add docs/help/* + git commit -m "Automated update of help docs" + + branch_name="${GITHUB_HEAD_REF:-${GITHUB_REF#refs/heads/}}" + git push origin HEAD:$branch_name + fi diff --git a/docs/help/otf_view.txt b/docs/help/otf_view.txt new file mode 100644 index 0000000..372985e --- /dev/null +++ b/docs/help/otf_view.txt @@ -0,0 +1,20 @@ +usage: otf-view [-h] [--show] [--show-only] [-o OUTPUT_DIRECTORY] [-v] + [--no-progress] + otf_paths [otf_paths ...] + +Create OTF views + +positional arguments: + otf_paths OTF file paths + +options: + -h, --help show this help message and exit + --show Display the plots while running + --show-only Show plots without saving + -o OUTPUT_DIRECTORY, --output-directory OUTPUT_DIRECTORY + Save to this directory if saving plots, otherwise each + plot will be saved with its input file + -v, --verbose Show more logging + --no-progress turn off progress bars (only has an effect if tqdm is + installed) +sdfsdf diff --git a/docs/help/sim_otf.txt b/docs/help/sim_otf.txt new file mode 100644 index 0000000..95382de --- /dev/null +++ b/docs/help/sim_otf.txt @@ -0,0 +1,55 @@ +usage: sim-otf [-c CONFIG_PATH] [-p PSF_PATHS [PSF_PATHS ...]] + [-o OUTPUT_DIRECTORY] [--overwrite] [--no-cleanup] + [--shape XY_SHAPE XY_SHAPE] [-v] [--no-progress] + [--nphases NPHASES] [--ls LS] [--na NA] [--nimm NIMM] + [--background BACKGROUND] [--beaddiam BEADDIAM] [--angle ANGLE] + [--nocompen NOCOMPEN] [--fixorigin FIXORIGIN FIXORIGIN] + [--leavekz LEAVEKZ LEAVEKZ LEAVEKZ] [-h] + +SIM PSFs to OTFs + +options: + -c CONFIG_PATH, --config-path CONFIG_PATH + Path to the root config that specifies the paths to + the OTFs and the other configs + -p PSF_PATHS [PSF_PATHS ...], --psf PSF_PATHS [PSF_PATHS ...] + Paths to PSF files to be reconstructed (multiple paths + can be given) + -o OUTPUT_DIRECTORY, --output-directory OUTPUT_DIRECTORY + If specified, the output directory that the OTFs will + be saved in, otherwise each OTF will be saved in the + same directory as its PSF + --overwrite If specified, files will be overwritten if they + already exist (unique filenames will be used + otherwise) + --no-cleanup If specified, files created during the OTF creation + process will not be cleaned up + --shape XY_SHAPE XY_SHAPE + Takes 2 integers (X Y), specifying the shape to crop + PSFs to before converting (powers of 2 are fastest) + -v, --verbose Show more logging + --no-progress turn off progress bars (only has an effect if tqdm is + installed) + -h, --help show this help message and exit + +Overrides: + Arguments that override configured values. Defaults stated are only used + if no value is given or configured. + + --nphases NPHASES Number of pattern phases per SIM direction + --ls LS Line spacing of SIM pattern in microns + --na NA Detection objective's numerical aperture + --nimm NIMM Refractive index of immersion medium + --background BACKGROUND + Camera readout background + --beaddiam BEADDIAM The diameter of the bead in microns, by default 0.12 + --angle ANGLE The k0 vector angle with which the PSF is taken, by + default 0 + --nocompen NOCOMPEN Do not perform bead size compensation, default False + (do perform) + --fixorigin FIXORIGIN FIXORIGIN + The starting and end pixel for interpolation along kr + axis, by default (2, 9) + --leavekz LEAVEKZ LEAVEKZ LEAVEKZ + Pixels to be retained on kz axis, by default (0, 0, 0) +sad diff --git a/README.md b/docs/help/sim_recon.txt similarity index 52% rename from README.md rename to docs/help/sim_recon.txt index 6bd3733..5630e53 100644 --- a/README.md +++ b/docs/help/sim_recon.txt @@ -1,105 +1,3 @@ -# PySIMRecon - -Easy to use wrapper for pyCUDAsirecon, allowing the use of DV (DeltaVision) files without IVE/Priism (UCSF library with MRC/DV support). - -This is built for easy use from the command line or as part of an auto-processing pipeline, allowing parameters to be pre-configured or defined at runtime. - -### Goal - -To reconstruct the SIM data and create OTFs from PSFs from the cryoSIM at B24, Diamond from the .dv files created by Cockpit. Requirements are: - -- Easy to use -- Open source -- Reproducable results -- Can be used as part of an automatic processing pipeline - -### Current state - -Under development - -### Configuration - -Calls to `sim-otf` and `sim-recon` can both take a `-c`/`--config` argument. This should be similar to the `config.ini` file in the configs directory, which specifies the defaults config, any per-channel configs (some values should be set on a per-channel basis), and the locations of OTFs for each channel. -The channels are specified based on the emission wavelength in nanometres (must be an integer). - -##### Example: - -For a channel with an emission wavelength of 525nm: - -- In the `[configs]` section, the channel config can be specified as `525=/path/to/configs/525.cfg` -- In the `[otfs]` section, the channel OTF file can be specified as `525=/path/to/otfs/525_otf.tiff` - -A directory can be specified within each of the `[configs]` and `[otfs]` sections. If given, files can also be defined relative to that directory, e.g. if `directory=/path/to`, then `525=/path/to/otfs/525_otf.tiff` could simply be `525=otfs/525_otf.tiff`. -Config settings will be overriden by higher-priority sources. - -##### Order of setting priority: - -1. Command line arguments (override all) -2. Per-channel configs (override defaults for the appropriate channel only) -3. Defaults (override any cudasirecon defaults) - -### CLI - -##### sim-otf - -``` -usage: sim-otf [-c CONFIG_PATH] [-p PSF_PATHS [PSF_PATHS ...]] - [-o OUTPUT_DIRECTORY] [--overwrite] [--no-cleanup] - [--shape XY_SHAPE XY_SHAPE] [-v] [--no-progress] - [--nphases NPHASES] [--ls LS] [--na NA] [--nimm NIMM] - [--background BACKGROUND] [--beaddiam BEADDIAM] [--angle ANGLE] - [--nocompen NOCOMPEN] [--fixorigin FIXORIGIN FIXORIGIN] - [--leavekz LEAVEKZ LEAVEKZ LEAVEKZ] [-h] - -options: - -c CONFIG_PATH, --config-path CONFIG_PATH - Path to the root config that specifies the paths to - the OTFs and the other configs - -p PSF_PATHS [PSF_PATHS ...], --psf PSF_PATHS [PSF_PATHS ...] - Paths to PSF files to be reconstructed (multiple paths - can be given) - -o OUTPUT_DIRECTORY, --output-directory OUTPUT_DIRECTORY - If specified, the output directory that the OTFs will - be saved in, otherwise each OTF will be saved in the - same directory as its PSF - --overwrite If specified, files will be overwritten if they - already exist (unique filenames will be used - otherwise) - --no-cleanup If specified, files created during the OTF creation - process will not be cleaned up - --shape XY_SHAPE XY_SHAPE - Takes 2 integers (X Y), specifying the shape to crop - PSFs to before converting (powers of 2 are fastest) - -v, --verbose Show more logging - --no-progress turn off progress bars (only has an effect if tqdm is - installed) - -h, --help show this help message and exit - -Overrides: - Arguments that override configured values. Defaults stated are only used - if no value is given or configured. - - --nphases NPHASES Number of pattern phases per SIM direction - --ls LS Line spacing of SIM pattern in microns - --na NA Detection objective's numerical aperture - --nimm NIMM Refractive index of immersion medium - --background BACKGROUND - Camera readout background - --beaddiam BEADDIAM The diameter of the bead in microns, by default 0.12 - --angle ANGLE The k0 vector angle with which the PSF is taken, by - default 0 - --nocompen NOCOMPEN Do not perform bead size compensation, default False - (do perform) - --fixorigin FIXORIGIN FIXORIGIN - The starting and end pixel for interpolation along kr - axis, by default (2, 9) - --leavekz LEAVEKZ LEAVEKZ LEAVEKZ - Pixels to be retained on kz axis, by default (0, 0, 0) -``` - -##### sim-recon - -``` usage: sim-recon [-c CONFIG_PATH] [-d SIM_DATA_PATHS [SIM_DATA_PATHS ...]] [-o OUTPUT_DIRECTORY] [--overwrite] [--no-cleanup] [--keep-split] [--parallel] [-v] [--no-progress] @@ -119,6 +17,8 @@ usage: sim-recon [-c CONFIG_PATH] [-d SIM_DATA_PATHS [SIM_DATA_PATHS ...]] [--zres ZRES] [--zresPSF ZRESPSF] [--wavelength WAVELENGTH] [-h] +Reconstruct SIM data + options: -c CONFIG_PATH, --config-path CONFIG_PATH Path to the root config that specifies the paths to @@ -211,32 +111,4 @@ Overrides: --zresPSF ZRESPSF Z pixel size (used in PSF TIFF files) --wavelength WAVELENGTH Emission wavelength in nm (only used for TIFF files) -``` - -##### otf-view - -``` -usage: otf-view [-h] [--show] [--show-only] [-o OUTPUT_DIRECTORY] [-v] - [--no-progress] - otf_paths [otf_paths ...] - -positional arguments: - otf_paths OTF file paths - -options: - -h, --help show this help message and exit - --show Display the plots while running - --show-only Show plots without saving - -o OUTPUT_DIRECTORY, --output-directory OUTPUT_DIRECTORY - Save to this directory if saving plots, otherwise each - plot will be saved with its input file - -v, --verbose Show more logging - --no-progress turn off progress bars (only has an effect if tqdm is - installed) - -``` - - -##### dv2tiff - -Accepts a list of DV files to be converted to TIFFs (with some OME metadata). + safas diff --git a/docs/sections/command_line.md b/docs/sections/command_line.md new file mode 100644 index 0000000..1dd1e08 --- /dev/null +++ b/docs/sections/command_line.md @@ -0,0 +1,23 @@ +### CLI + +##### sim-otf + +``` +{{ HELP_SIM_OTF_TXT }} +``` + +##### sim-recon + +``` +{{ HELP_SIM_RECON_TXT }} +``` + +##### otf-view + +``` +{{ HELP_OTF_VIEW_TXT }} +``` + +##### dv2tiff + +Accepts a list of DV files to be converted to TIFFs (with some OME metadata). diff --git a/docs/sections/configuration.md b/docs/sections/configuration.md new file mode 100644 index 0000000..55e54df --- /dev/null +++ b/docs/sections/configuration.md @@ -0,0 +1,14 @@ +### Configuration +Calls to `sim-otf` and `sim-recon` can both take a `-c`/`--config` argument. This should be similar to the `config.ini` file in the configs directory, which specifies the defaults config, any per-channel configs (some values should be set on a per-channel basis), and the locations of OTFs for each channel. +The channels are specified based on the emission wavelength in nanometres (must be an integer). +##### Example: +For a channel with an emission wavelength of 525nm: +- In the `[configs]` section, the channel config can be specified as `525=/path/to/configs/525.cfg` +- In the `[otfs]` section, the channel OTF file can be specified as `525=/path/to/otfs/525_otf.tiff` +A directory can be specified within each of the `[configs]` and `[otfs]` sections. If given, files can also be defined relative to that directory, e.g. if `directory=/path/to`, then `525=/path/to/otfs/525_otf.tiff` could simply be `525=otfs/525_otf.tiff`. +Config settings will be overriden by higher-priority sources. + +##### Order of setting priority: +1. Command line arguments (override all) +2. Per-channel configs (override defaults for the appropriate channel only) +3. Defaults (override any cudasirecon defaults) diff --git a/docs/template.md b/docs/template.md new file mode 100644 index 0000000..046acae --- /dev/null +++ b/docs/template.md @@ -0,0 +1,22 @@ +# PySIMRecon + +Easy to use wrapper for pyCUDAsirecon, allowing the use of DV (DeltaVision) files without IVE/Priism (UCSF library with MRC/DV support). + +This is built for easy use from the command line or as part of an auto-processing pipeline, allowing parameters to be pre-configured or defined at runtime. + +### Goal + +To reconstruct the SIM data and create OTFs from PSFs from the cryoSIM at B24, Diamond from the .dv files created by Cockpit. Requirements are: + +- Easy to use +- Open source +- Reproducable results +- Can be used as part of an automatic processing pipeline + +### Current state + +Under development + +{{ SECTIONCONFIGURATION_MD }} + +{{ SECTIONS_COMMAND_LINE_MD }}