From 416222cc1d9305d3929c475127fda280c50c976d Mon Sep 17 00:00:00 2001 From: Thomas Fish Date: Fri, 6 Sep 2024 18:54:28 +0100 Subject: [PATCH] Add docs directory --- README.md | 227 ++++++++++++++++++++++++++++++++++ docs/help/otf_view.txt | 19 +++ docs/help/sim_otf.txt | 54 ++++++++ docs/help/sim_recon.txt | 113 +++++++++++++++++ docs/sections/command_line.md | 17 ++- docs/template.md | 4 +- 6 files changed, 426 insertions(+), 8 deletions(-) create mode 100644 README.md create mode 100644 docs/help/otf_view.txt create mode 100644 docs/help/sim_otf.txt create mode 100644 docs/help/sim_recon.txt diff --git a/README.md b/README.md new file mode 100644 index 0000000..c2c0a22 --- /dev/null +++ b/README.md @@ -0,0 +1,227 @@ +# 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 }} + +### 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] + +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) +``` + +##### 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] + [--ndirs NDIRS] [--nphases NPHASES] [--nordersout NORDERSOUT] + [--angle0 ANGLE0] [--ls LS] [--na NA] [--nimm NIMM] + [--wiener WIENER] [--zoomfact ZOOMFACT] [--zzoom ZZOOM] + [--background BACKGROUND] [--usecorr USECORR] + [--k0angles K0ANGLES K0ANGLES K0ANGLES] [--otfRA OTFRA] + [--otfPerAngle OTFPERANGLE] [--fastSI FASTSI] + [--k0searchAll K0SEARCHALL] [--norescale NORESCALE] + [--equalizez EQUALIZEZ] [--equalizet EQUALIZET] + [--dampenOrder0 DAMPENORDER0] [--nosuppress NOSUPPRESS] + [--nokz0 NOKZ0] [--gammaApo GAMMAAPO] + [--explodefact EXPLODEFACT] [--nofilterovlps NOFILTEROVLPS] + [--deskew DESKEW] [--deskewshift DESKEWSHIFT] + [--noRecon NORECON] [--cropXY CROPXY] [--xyres XYRES] + [--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 + the OTFs and the other configs + -d SIM_DATA_PATHS [SIM_DATA_PATHS ...], --data SIM_DATA_PATHS [SIM_DATA_PATHS ...] + Paths to SIM data files to be reconstructed (multiple + paths can be given) + -o OUTPUT_DIRECTORY, --output-directory OUTPUT_DIRECTORY + The output directory to save reconstructed files in + --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 reconstruction + process will not be cleaned up + --keep-split If specified, channels will not be stitched back + together after reconstruction + --parallel If specified, up to 2 processes will be run at a time + -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. + + --ndirs NDIRS Number of SIM directions + --nphases NPHASES Number of pattern phases per SIM direction + --nordersout NORDERSOUT + Number of output SIM orders (must be <= nphases//2; + safe to ignore usually) + --angle0 ANGLE0 Angle of the first SIM angle in radians + --ls LS Line spacing of SIM pattern in microns + --na NA Detection objective's numerical aperture + --nimm NIMM Refractive index of immersion medium + --wiener WIENER Wiener constant; lower value leads to higher + resolution and noise; playing with it extensively is + strongly encouraged + --zoomfact ZOOMFACT Lateral zoom factor in the output over the input + images; leaving it at 2 should be fine in most cases + --zzoom ZZOOM Axial zoom factor; almost never needed + --background BACKGROUND + Camera readout background + --usecorr USECORR Use a flat-field correction file if provided + --k0angles K0ANGLES K0ANGLES K0ANGLES + Use these pattern vector k0 angles for all directions + (instead of inferring the rest angles from angle0) + --otfRA OTFRA Use rotationally averaged OTF; otherwise uses 3/2D OTF + for 3/2D raw data + --otfPerAngle OTFPERANGLE + Use one OTF per SIM angle; otherwise one OTF is used + for all angles, which is how it's been done + traditionally + --fastSI FASTSI SIM image is organized in Z->Angle->Phase order; + otherwise assuming Angle->Z->Phase image order + --k0searchAll K0SEARCHALL + Search for k0 at all time points + --norescale NORESCALE + No bleach correction + --equalizez EQUALIZEZ + Bleach correction for z + --equalizet EQUALIZET + Bleach correction for time + --dampenOrder0 DAMPENORDER0 + Dampen order-0 in final assembly; do not use for 2D + SIM; good choice for high-background images + --nosuppress NOSUPPRESS + Do not suppress DC singularity in the result (good + choice for 2D/TIRF data) + --nokz0 NOKZ0 Do not use kz=0 plane of the 0th order in the final + assembly (mostly for debug) + --gammaApo GAMMAAPO Output apodization gamma; 1.0 means triangular apo; + lower value means less dampening of high-resolution + info at the trade-off of higher noise + --explodefact EXPLODEFACT + Artificially exploding the reciprocal-space distance + between orders by this factor (for debug) + --nofilterovlps NOFILTEROVLPS + --deskew DESKEW Deskew angle; if not 0.0 then perform deskewing before + processing + --deskewshift DESKEWSHIFT + If deskewed, the output image's extra shift in X + (positive->left) + --noRecon NORECON No reconstruction will be performed; useful when + combined with "deskew": + --cropXY CROPXY Crop the X-Y dimension to this number; 0 means no + cropping + --xyres XYRES X-Y pixel size (only used for TIFF files) + --zres ZRES Z pixel size (only used for TIFF files) + --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 ...] + +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) +``` + +##### dv2tiff + +Accepts a list of DV files to be converted to TIFFs (with some OME metadata). diff --git a/docs/help/otf_view.txt b/docs/help/otf_view.txt new file mode 100644 index 0000000..6c750bd --- /dev/null +++ b/docs/help/otf_view.txt @@ -0,0 +1,19 @@ +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) diff --git a/docs/help/sim_otf.txt b/docs/help/sim_otf.txt new file mode 100644 index 0000000..fa92dc1 --- /dev/null +++ b/docs/help/sim_otf.txt @@ -0,0 +1,54 @@ +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) diff --git a/docs/help/sim_recon.txt b/docs/help/sim_recon.txt new file mode 100644 index 0000000..5a546a1 --- /dev/null +++ b/docs/help/sim_recon.txt @@ -0,0 +1,113 @@ +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] + [--ndirs NDIRS] [--nphases NPHASES] [--nordersout NORDERSOUT] + [--angle0 ANGLE0] [--ls LS] [--na NA] [--nimm NIMM] + [--wiener WIENER] [--zoomfact ZOOMFACT] [--zzoom ZZOOM] + [--background BACKGROUND] [--usecorr USECORR] + [--k0angles K0ANGLES K0ANGLES K0ANGLES] [--otfRA OTFRA] + [--otfPerAngle OTFPERANGLE] [--fastSI FASTSI] + [--k0searchAll K0SEARCHALL] [--norescale NORESCALE] + [--equalizez EQUALIZEZ] [--equalizet EQUALIZET] + [--dampenOrder0 DAMPENORDER0] [--nosuppress NOSUPPRESS] + [--nokz0 NOKZ0] [--gammaApo GAMMAAPO] + [--explodefact EXPLODEFACT] [--nofilterovlps NOFILTEROVLPS] + [--deskew DESKEW] [--deskewshift DESKEWSHIFT] + [--noRecon NORECON] [--cropXY CROPXY] [--xyres XYRES] + [--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 + the OTFs and the other configs + -d SIM_DATA_PATHS [SIM_DATA_PATHS ...], --data SIM_DATA_PATHS [SIM_DATA_PATHS ...] + Paths to SIM data files to be reconstructed (multiple + paths can be given) + -o OUTPUT_DIRECTORY, --output-directory OUTPUT_DIRECTORY + The output directory to save reconstructed files in + --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 reconstruction + process will not be cleaned up + --keep-split If specified, channels will not be stitched back + together after reconstruction + --parallel If specified, up to 2 processes will be run at a time + -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. + + --ndirs NDIRS Number of SIM directions + --nphases NPHASES Number of pattern phases per SIM direction + --nordersout NORDERSOUT + Number of output SIM orders (must be <= nphases//2; + safe to ignore usually) + --angle0 ANGLE0 Angle of the first SIM angle in radians + --ls LS Line spacing of SIM pattern in microns + --na NA Detection objective's numerical aperture + --nimm NIMM Refractive index of immersion medium + --wiener WIENER Wiener constant; lower value leads to higher + resolution and noise; playing with it extensively is + strongly encouraged + --zoomfact ZOOMFACT Lateral zoom factor in the output over the input + images; leaving it at 2 should be fine in most cases + --zzoom ZZOOM Axial zoom factor; almost never needed + --background BACKGROUND + Camera readout background + --usecorr USECORR Use a flat-field correction file if provided + --k0angles K0ANGLES K0ANGLES K0ANGLES + Use these pattern vector k0 angles for all directions + (instead of inferring the rest angles from angle0) + --otfRA OTFRA Use rotationally averaged OTF; otherwise uses 3/2D OTF + for 3/2D raw data + --otfPerAngle OTFPERANGLE + Use one OTF per SIM angle; otherwise one OTF is used + for all angles, which is how it's been done + traditionally + --fastSI FASTSI SIM image is organized in Z->Angle->Phase order; + otherwise assuming Angle->Z->Phase image order + --k0searchAll K0SEARCHALL + Search for k0 at all time points + --norescale NORESCALE + No bleach correction + --equalizez EQUALIZEZ + Bleach correction for z + --equalizet EQUALIZET + Bleach correction for time + --dampenOrder0 DAMPENORDER0 + Dampen order-0 in final assembly; do not use for 2D + SIM; good choice for high-background images + --nosuppress NOSUPPRESS + Do not suppress DC singularity in the result (good + choice for 2D/TIRF data) + --nokz0 NOKZ0 Do not use kz=0 plane of the 0th order in the final + assembly (mostly for debug) + --gammaApo GAMMAAPO Output apodization gamma; 1.0 means triangular apo; + lower value means less dampening of high-resolution + info at the trade-off of higher noise + --explodefact EXPLODEFACT + Artificially exploding the reciprocal-space distance + between orders by this factor (for debug) + --nofilterovlps NOFILTEROVLPS + --deskew DESKEW Deskew angle; if not 0.0 then perform deskewing before + processing + --deskewshift DESKEWSHIFT + If deskewed, the output image's extra shift in X + (positive->left) + --noRecon NORECON No reconstruction will be performed; useful when + combined with "deskew": + --cropXY CROPXY Crop the X-Y dimension to this number; 0 means no + cropping + --xyres XYRES X-Y pixel size (only used for TIFF files) + --zres ZRES Z pixel size (only used for TIFF files) + --zresPSF ZRESPSF Z pixel size (used in PSF TIFF files) + --wavelength WAVELENGTH + Emission wavelength in nm (only used for TIFF files) diff --git a/docs/sections/command_line.md b/docs/sections/command_line.md index 77e68d9..1dd1e08 100644 --- a/docs/sections/command_line.md +++ b/docs/sections/command_line.md @@ -1,18 +1,23 @@ ### CLI ##### sim-otf + ``` -${{ env.OTF_HELP_OUTPUT }} +{{ HELP_SIM_OTF_TXT }} ``` - ##### sim-recon + ``` -${{ env.RECON_HELP_OUTPUT }} +{{ 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). -##### otf-view -Accepts a list of OTF files (DV or TIFF), the amplitude and phase of which will be plotted. +Accepts a list of DV files to be converted to TIFFs (with some OME metadata). diff --git a/docs/template.md b/docs/template.md index 2b2e161..046acae 100644 --- a/docs/template.md +++ b/docs/template.md @@ -17,6 +17,6 @@ To reconstruct the SIM data and create OTFs from PSFs from the cryoSIM at B24, D Under development -${{ env.SECTIONS_CONFIGURATION_MD }} +{{ SECTIONCONFIGURATION_MD }} -${{ env.SECTIONS_COMMAND_LINE_MD }} +{{ SECTIONS_COMMAND_LINE_MD }}