From 47bf9fa976dd2e99aa7987d865845a20f5426f79 Mon Sep 17 00:00:00 2001 From: Lorenzo Gaifas Date: Mon, 28 Aug 2023 16:55:24 +0200 Subject: [PATCH] update readme with some usage guidelines --- README.md | 29 ++++++++++++++++++++--------- 1 file changed, 20 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 343341f..22c3f37 100644 --- a/README.md +++ b/README.md @@ -16,16 +16,27 @@ pip install waretomo # Usage -Assuming we're in a pre-processed Warp directory containing an `./imod/` directory with averaged and stacked tilt series, and mdoc files inside `./mdocs/`: +Here's a short summary of how I recommend using this script: +- pre-process your dataset in Warp, up to `Create stack for imod`. Make sure to deselect bad tilts from the warp interface; they will be skipped in subsequent steps +- run `waretomo` in `dry-run` mode (`-d`), to make sure everything is set up correctly. Pass any other options you'd like (see `waretomo -h` for a complete list and shorthands): +```bash +waretomo . --mdoc-dir ./mdocs -b 8 -t 800 -d ``` -waretomo . --mdoc-dir mdocs --binning 8 -``` - -_TIP: run first with the dry-run `-d` option as above to get a summary of all the steps that will be performed._ - -For detailed help: - +- follow error messages if any arise (you may have to provide the path to the `AreTomo` executable with `--aretomo`, for example) +- once the above command works, it will give you a summary of inputs and of the upcoming pipeline. It's time to try to run it on a single tomogram, using `-j` (`--just`). _Note that the name to provide to `-j` is the tomogram name given at the top of the mdoc file (`ImageFile = `), and not the input file (this is because warp actually uses this value for all subsequent outputs)._ ```bash -waretomo -h +waretomo . --mdoc-dir ./mdocs -b 8 -t 800 -j tiltseries_23.mrc ``` +- this will run the full pipeline on that tomogram. Keep an eye out for error messages, they might give you tips for solving them. +- if everything works, you will now have a few outputs to check out: + - `./waretomo_processing/tiltseries_23.mrc`: raw aretomo reconstruction. + - `./waretomo_processing/denoised/tiltseries_23.mrc`: same as above, denoised with topaz for better annotation + - `/mdoc_tilted/tiltseries_23.mrc.mdoc`: mdoc file updated with skipped tilt and with adjusted tilt angles from aretomo's `TiltAlign` option (e.g: to align lamellae to the XY plane) + - `./waretomo_processing/tiltseries_23.xf`: alignment metadata, used by warp together with above mdocs for reconstruction. +- check out the reconstructions and make sure everything looks as you want. If anything is wrong, adjust parameters as you see fit. You can also run only parts of the script by using the `--start-from` and `--stop-at` options (both are inclusive). Use `-f` if you want to overwrite existing outputs. +- once you're happy, remove the `-j` option to process the full dataset. + +At this point, you're ready to go back to Warp. Here, you can simply `import tilt series from IMOD`. Don't forget to provide the `mdoc_tilted` directory instead of the original mdocs. Set `waretomo_processing` as the `Root folder with IMOD processing results`, and Warp will find the `xf` files located there. Provide the pixel size of the binned aretomo reconstructions (find out with e.g: `header waretomo_processing/tiltseries_23.mrc.mrc`). You might have to provide the dose per tilt, depending on the origin/correctness of your mdocs. + +You can now proceed with reconstructing with Warp, use M, and so on, while having matching AreTomo reconstructions with their local patch alignments and subsequent denoising to maximize readability for picking and annotation.