janas 2.2.2__tar.gz → 2.2.4__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {janas-2.2.2 → janas-2.2.4}/CHANGELOG.md +115 -0
- janas-2.2.4/CITATION.cff +12 -0
- {janas-2.2.2 → janas-2.2.4}/MANIFEST.in +3 -0
- {janas-2.2.2 → janas-2.2.4}/PKG-INFO +28 -2
- {janas-2.2.2 → janas-2.2.4}/README.md +26 -1
- janas-2.2.4/docs/CLASS_REASSIGNMENT.md +99 -0
- janas-2.2.4/docs/ITERATIVE_SELECTION.md +270 -0
- janas-2.2.4/docs/accessory_utils.md +349 -0
- janas-2.2.4/docs/citation.md +30 -0
- janas-2.2.4/docs/custom_selected_stacks.md +159 -0
- janas-2.2.4/docs/examples/empiar-10308.md +179 -0
- janas-2.2.4/docs/gpu.md +157 -0
- janas-2.2.4/docs/index.md +37 -0
- janas-2.2.4/docs/installation.md +208 -0
- janas-2.2.4/docs/progress_dashboard.md +222 -0
- janas-2.2.4/docs/quick-start.md +108 -0
- janas-2.2.4/docs/reference/cli.md +319 -0
- janas-2.2.4/docs/reference/computational-requirements.md +67 -0
- janas-2.2.4/docs/reference/gpu-benchmarks.md +201 -0
- janas-2.2.4/docs/reference/star-operations.md +102 -0
- janas-2.2.4/docs/sigma_estimate.md +82 -0
- janas-2.2.4/docs/slurm_examples.md +236 -0
- janas-2.2.4/docs/subtraction_operators.md +116 -0
- janas-2.2.4/docs/troubleshooting.md +88 -0
- janas-2.2.4/docs/workflows/classification.md +184 -0
- janas-2.2.4/docs/workflows/cryosparc.md +135 -0
- janas-2.2.4/docs/workflows/cryosparc_star_recovery.md +423 -0
- janas-2.2.4/docs/workflows/selection.md +172 -0
- janas-2.2.4/mkdocs.yml +68 -0
- {janas-2.2.2 → janas-2.2.4}/requirements.txt +2 -1
- {janas-2.2.2 → janas-2.2.4}/setup.py +5 -5
- {janas-2.2.2 → janas-2.2.4}/src/janas/IO_utils.py +9 -2
- {janas-2.2.2 → janas-2.2.4}/src/janas/assessParticles.py +111 -13
- {janas-2.2.2 → janas-2.2.4}/src/janas/benchmarking_janas_cmd_session_manager.py +15 -13
- {janas-2.2.2 → janas-2.2.4}/src/janas/bin_wrapper.py +2 -0
- janas-2.2.4/src/janas/gpu/__init__.py +1 -0
- janas-2.2.4/src/janas/gpu/ctf.py +149 -0
- janas-2.2.4/src/janas/gpu/device_policy.py +47 -0
- janas-2.2.4/src/janas/gpu/devices.py +101 -0
- janas-2.2.4/src/janas/gpu/projector.py +422 -0
- janas-2.2.4/src/janas/gpu/reconstruction.py +670 -0
- janas-2.2.4/src/janas/gpu/reconstruction_ctf.py +89 -0
- janas-2.2.4/src/janas/gpu/reconstruction_dispatch.py +49 -0
- janas-2.2.4/src/janas/gpu/reconstruction_finish.py +105 -0
- janas-2.2.4/src/janas/gpu/sci.py +238 -0
- janas-2.2.4/src/janas/gpu/scoring.py +643 -0
- janas-2.2.4/src/janas/gpu/scoring_adapter.py +982 -0
- janas-2.2.4/src/janas/gpu/scoring_ctf.py +56 -0
- janas-2.2.4/src/janas/gpu/scoring_dispatch.py +102 -0
- janas-2.2.4/src/janas/gpu/scoring_io.py +243 -0
- janas-2.2.4/src/janas/gpu/scoring_masks.py +125 -0
- janas-2.2.4/src/janas/gpu/scoring_projection.py +121 -0
- janas-2.2.4/src/janas/gpu/sessions.py +44 -0
- janas-2.2.4/src/janas/gpu/subtraction.py +28 -0
- janas-2.2.4/src/janas/gpu/subtraction_local.py +50 -0
- janas-2.2.4/src/janas/gpu/subtraction_mask.py +50 -0
- janas-2.2.4/src/janas/gpu/subtraction_ops.py +140 -0
- janas-2.2.4/src/janas/gpu/subtraction_options.py +100 -0
- janas-2.2.4/src/janas/gpu/subtraction_projection.py +118 -0
- janas-2.2.4/src/janas/gpu/workers.py +704 -0
- {janas-2.2.2 → janas-2.2.4}/src/janas/janas_alternative_selector.py +34 -25
- {janas-2.2.2 → janas-2.2.4}/src/janas/janas_cmd_caller.py +115 -22
- {janas-2.2.2 → janas-2.2.4}/src/janas/janas_cmd_optimizer.py +22 -16
- {janas-2.2.2 → janas-2.2.4}/src/janas/janas_cmd_session_manager.py +105 -49
- {janas-2.2.2 → janas-2.2.4}/src/janas/janas_cmd_utils.py +223 -72
- {janas-2.2.2 → janas-2.2.4}/src/janas/janas_developer_test.py +3 -1
- {janas-2.2.2 → janas-2.2.4}/src/janas/janas_mapProcess.py +9 -6
- {janas-2.2.2 → janas-2.2.4}/src/janas/janas_reconstructor.py +81 -151
- janas-2.2.4/src/janas/locres_adaptive.py +844 -0
- {janas-2.2.2 → janas-2.2.4}/src/janas/locres_repro.py +4 -4
- {janas-2.2.2 → janas-2.2.4}/src/janas/locres_utils.py +244 -14
- {janas-2.2.2 → janas-2.2.4}/src/janas/projector_utils.py +15 -6
- janas-2.2.4/src/janas/reconstruction/__init__.py +1 -0
- janas-2.2.4/src/janas/reconstruction/ctf.py +107 -0
- janas-2.2.4/src/janas/reconstruction/finish.py +168 -0
- janas-2.2.4/src/janas/reconstruction/memory.py +168 -0
- janas-2.2.4/src/janas/reconstruction/model.py +32 -0
- janas-2.2.4/src/janas/reconstruction/schedule.py +34 -0
- {janas-2.2.2 → janas-2.2.4}/src/janas/reconstructor_utils.py +83 -225
- janas-2.2.4/src/janas/sci_policy.py +74 -0
- {janas-2.2.2 → janas-2.2.4}/src/janas/starHandler.py +36 -22
- janas-2.2.4/src/janas/text_io.py +13 -0
- {janas-2.2.2 → janas-2.2.4}/src/janas/utils.py +20 -11
- {janas-2.2.2 → janas-2.2.4}/src/janas.egg-info/PKG-INFO +28 -2
- janas-2.2.4/src/janas.egg-info/SOURCES.txt +201 -0
- {janas-2.2.2 → janas-2.2.4}/src/janas.egg-info/entry_points.txt +2 -2
- {janas-2.2.2 → janas-2.2.4}/src/janas.egg-info/requires.txt +1 -0
- {janas-2.2.2 → janas-2.2.4}/src/src_cpp/euler_libs.h +8 -4
- {janas-2.2.2 → janas-2.2.4}/src/src_cpp/janas_app_meanMinMax.cxx +13 -4
- {janas-2.2.2 → janas-2.2.4}/src/src_cpp/janas_app_starProcess.cxx +23 -8
- {janas-2.2.2 → janas-2.2.4}/src/src_cpp/janas_core.cpp +237 -57
- {janas-2.2.2 → janas-2.2.4}/src/src_cpp/mrcIO.h +316 -163
- janas-2.2.4/src/src_cpp/sci_policy.h +67 -0
- {janas-2.2.2 → janas-2.2.4}/src/src_cpp/scores.h +21 -70
- {janas-2.2.2 → janas-2.2.4}/tests/test_behaviour_preserving_fixes.py +23 -10
- janas-2.2.4/tests/test_class_writeback.py +457 -0
- janas-2.2.4/tests/test_cli_release_errors.py +91 -0
- janas-2.2.4/tests/test_default_devices.py +126 -0
- {janas-2.2.2 → janas-2.2.4}/tests/test_euler_anchor_assignment.py +19 -6
- {janas-2.2.2 → janas-2.2.4}/tests/test_generated_session_scripts.py +12 -0
- janas-2.2.4/tests/test_gpu_classification.py +377 -0
- janas-2.2.4/tests/test_gpu_cli_devices.py +333 -0
- janas-2.2.4/tests/test_gpu_ctf.py +435 -0
- janas-2.2.4/tests/test_gpu_generated_sessions.py +487 -0
- janas-2.2.4/tests/test_gpu_projector.py +763 -0
- janas-2.2.4/tests/test_gpu_projector_performance.py +628 -0
- janas-2.2.4/tests/test_gpu_sci_kernel.py +480 -0
- janas-2.2.4/tests/test_gpu_score_particles.py +605 -0
- janas-2.2.4/tests/test_gpu_scoring.py +1242 -0
- janas-2.2.4/tests/test_gpu_scoring_dispatch.py +640 -0
- janas-2.2.4/tests/test_gpu_scoring_performance.py +485 -0
- janas-2.2.4/tests/test_gpu_scoring_production.py +170 -0
- janas-2.2.4/tests/test_gpu_scoring_retry.py +120 -0
- janas-2.2.4/tests/test_gpu_stack_images.py +113 -0
- janas-2.2.4/tests/test_gpu_subtraction_support.py +589 -0
- janas-2.2.4/tests/test_gpu_worker_order.py +356 -0
- janas-2.2.4/tests/test_gpu_workers.py +1557 -0
- janas-2.2.4/tests/test_harness_contract.py +183 -0
- janas-2.2.4/tests/test_locres_adaptive.py +441 -0
- janas-2.2.4/tests/test_locres_cli_defaults.py +389 -0
- {janas-2.2.2 → janas-2.2.4}/tests/test_locres_release_fixes.py +8 -7
- {janas-2.2.2 → janas-2.2.4}/tests/test_locres_v3_closure.py +5 -4
- janas-2.2.4/tests/test_mrc_mode12.py +185 -0
- janas-2.2.4/tests/test_mrc_mode12_workflows.py +336 -0
- janas-2.2.4/tests/test_mrc_stack_writers.py +243 -0
- janas-2.2.4/tests/test_mrc_writer.py +690 -0
- janas-2.2.4/tests/test_noncubic_map_commands.py +588 -0
- janas-2.2.4/tests/test_optional_star_columns.py +491 -0
- janas-2.2.4/tests/test_optional_torch_imports.py +170 -0
- janas-2.2.4/tests/test_rankparticles_cli.py +295 -0
- janas-2.2.4/tests/test_rec_ctf.py +104 -0
- janas-2.2.4/tests/test_rec_finish.py +165 -0
- janas-2.2.4/tests/test_rec_gpu_canonical.py +682 -0
- janas-2.2.4/tests/test_rec_gpu_ctf_device.py +76 -0
- janas-2.2.4/tests/test_rec_gpu_pipeline.py +310 -0
- janas-2.2.4/tests/test_rec_gpu_throughput.py +350 -0
- janas-2.2.4/tests/test_rec_io_contract.py +180 -0
- janas-2.2.4/tests/test_rec_memory.py +336 -0
- janas-2.2.4/tests/test_rec_model.py +178 -0
- janas-2.2.4/tests/test_recfix_cpu_ctf.py +467 -0
- janas-2.2.4/tests/test_recfix_csv_tau.py +271 -0
- janas-2.2.4/tests/test_recfix_no_cpu_torch.py +464 -0
- janas-2.2.4/tests/test_sci_floor_arrays.py +381 -0
- janas-2.2.4/tests/test_sci_floor_cpp.py +260 -0
- janas-2.2.4/tests/test_sci_floor_policy.py +170 -0
- janas-2.2.4/tests/test_sci_floor_python.py +366 -0
- janas-2.2.4/tests/test_sci_floor_workflows.py +712 -0
- janas-2.2.4/tests/test_sci_floor_zero.py +386 -0
- janas-2.2.4/tests/test_sci_paper_default.py +271 -0
- janas-2.2.4/tests/test_scoring_subtraction_precision.py +408 -0
- janas-2.2.4/tests/test_selection_subtraction.py +433 -0
- janas-2.2.4/tests/test_subx2_operators.py +325 -0
- janas-2.2.4/tests/test_subx2_options.py +137 -0
- janas-2.2.4/tests/test_subx2_workflows.py +340 -0
- janas-2.2.4/tests/test_subx_cli.py +128 -0
- janas-2.2.4/tests/test_subx_operators.py +322 -0
- janas-2.2.4/tests/test_subx_options.py +99 -0
- janas-2.2.4/tests/test_text_encoding.py +153 -0
- janas-2.2.2/src/janas/bin/janas_app_meanMinMax +0 -0
- janas-2.2.2/src/janas/bin/janas_app_starProcess +0 -0
- janas-2.2.2/src/janas.egg-info/SOURCES.txt +0 -84
- {janas-2.2.2 → janas-2.2.4}/CMakeLists.txt +0 -0
- {janas-2.2.2 → janas-2.2.4}/LICENSE +0 -0
- {janas-2.2.2 → janas-2.2.4}/pyproject.toml +0 -0
- {janas-2.2.2 → janas-2.2.4}/setup.cfg +0 -0
- {janas-2.2.2 → janas-2.2.4}/src/janas/__init__.py +0 -0
- {janas-2.2.2 → janas-2.2.4}/src/janas/images/selection_finished.png +0 -0
- {janas-2.2.2 → janas-2.2.4}/src/janas/images/selection_step1.png +0 -0
- {janas-2.2.2 → janas-2.2.4}/src/janas/images/selection_step2.png +0 -0
- {janas-2.2.2 → janas-2.2.4}/src/janas/images/selection_step3.png +0 -0
- {janas-2.2.2 → janas-2.2.4}/src/janas/images/selection_step4.png +0 -0
- {janas-2.2.2 → janas-2.2.4}/src/janas/images/selection_unstarted.png +0 -0
- {janas-2.2.2 → janas-2.2.4}/src/janas/janas_progress.py +0 -0
- {janas-2.2.2 → janas-2.2.4}/src/janas/setup_environment_shell.sh +0 -0
- {janas-2.2.2 → janas-2.2.4}/src/janas/starDisplay.py +0 -0
- {janas-2.2.2 → janas-2.2.4}/src/janas/utils_csparc.py +0 -0
- {janas-2.2.2 → janas-2.2.4}/src/janas/version.py +0 -0
- {janas-2.2.2 → janas-2.2.4}/src/janas.egg-info/dependency_links.txt +0 -0
- {janas-2.2.2 → janas-2.2.4}/src/janas.egg-info/not-zip-safe +0 -0
- {janas-2.2.2 → janas-2.2.4}/src/janas.egg-info/top_level.txt +0 -0
- {janas-2.2.2 → janas-2.2.4}/src/src_cpp/CsvStarReadWriteAnalyseLibs.h +0 -0
- {janas-2.2.2 → janas-2.2.4}/src/src_cpp/ctfLibs.h +0 -0
- {janas-2.2.2 → janas-2.2.4}/src/src_cpp/derivative_libs.h +0 -0
- {janas-2.2.2 → janas-2.2.4}/src/src_cpp/imageProcessingLib.h +0 -0
- {janas-2.2.2 → janas-2.2.4}/src/src_cpp/matrix_computations.h +0 -0
- {janas-2.2.2 → janas-2.2.4}/src/src_cpp/randomLibs.h +0 -0
- {janas-2.2.2 → janas-2.2.4}/src/src_cpp/recline.c +0 -0
- {janas-2.2.2 → janas-2.2.4}/src/src_cpp/recline.h +0 -0
- {janas-2.2.2 → janas-2.2.4}/tests/test_backmap_stars.py +0 -0
- {janas-2.2.2 → janas-2.2.4}/tests/test_clean_csparc_blob_path.py +0 -0
- {janas-2.2.2 → janas-2.2.4}/tests/test_create_stack_path_mode.py +0 -0
- {janas-2.2.2 → janas-2.2.4}/tests/test_csparc2star_missing_pose.py +0 -0
- {janas-2.2.2 → janas-2.2.4}/tests/test_csparc_finalise.py +0 -0
- {janas-2.2.2 → janas-2.2.4}/tests/test_csparc_login.py +0 -0
- {janas-2.2.2 → janas-2.2.4}/tests/test_custom_selected_stacks.py +0 -0
- {janas-2.2.2 → janas-2.2.4}/tests/test_eulerhist_show_flag.py +0 -0
- {janas-2.2.2 → janas-2.2.4}/tests/test_fixstack.py +0 -0
- {janas-2.2.2 → janas-2.2.4}/tests/test_janas_progress.py +0 -0
- {janas-2.2.2 → janas-2.2.4}/tests/test_locres_reproducibility.py +0 -0
- {janas-2.2.2 → janas-2.2.4}/tests/test_mrc_reader.py +0 -0
- {janas-2.2.2 → janas-2.2.4}/tests/test_reconstructor_nan_guard.py +0 -0
- {janas-2.2.2 → janas-2.2.4}/tests/test_sanitize_particle.py +0 -0
- {janas-2.2.2 → janas-2.2.4}/tests/test_score_particles_arrays_equivalence.py +0 -0
- {janas-2.2.2 → janas-2.2.4}/tests/test_scoreparticles_additional_options.py +0 -0
- {janas-2.2.2 → janas-2.2.4}/tests/test_support_floor.py +0 -0
|
@@ -1,5 +1,120 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 2.2.4
|
|
4
|
+
|
|
5
|
+
### Building release wheels with a Conda toolchain
|
|
6
|
+
|
|
7
|
+
A Conda Python can inject its absolute library directory into the
|
|
8
|
+
native extension's ELF RPATH through Python's linker configuration, outside
|
|
9
|
+
CMake. Before distributing a Linux wheel built with that toolchain, remove
|
|
10
|
+
that build-machine RPATH and regenerate the wheel's RECORD. Run the build,
|
|
11
|
+
repair and validation on a compute node; keep temporary paths off node-local /tmp:
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
# Install wheel and patchelf in the build environment beforehand.
|
|
15
|
+
python -m wheel unpack --dest "$TMPDIR/wheel-unpack" dist/janas-*.whl
|
|
16
|
+
patchelf --remove-rpath "$TMPDIR"/wheel-unpack/janas-*/janas/janas_core*.so
|
|
17
|
+
mkdir -p repaired-dist
|
|
18
|
+
python -m wheel pack --dest-dir repaired-dist "$TMPDIR"/wheel-unpack/janas-*
|
|
19
|
+
readelf -d "$TMPDIR"/wheel-unpack/janas-*/janas/janas_core*.so
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
Use a fresh unpack directory and one wheel per invocation. Confirm that
|
|
23
|
+
`readelf` shows no RPATH/RUNPATH, install the repaired wheel in a fresh
|
|
24
|
+
environment, run `pip check`, and recheck native help and workflows before
|
|
25
|
+
publication. Publish the repaired wheel, not the raw build. This repair does
|
|
26
|
+
not establish manylinux compatibility or bundle external runtime libraries;
|
|
27
|
+
use the normal release-platform build/repair checks for those guarantees.
|
|
28
|
+
|
|
29
|
+
### New
|
|
30
|
+
|
|
31
|
+
- CUDA SCI scoring with `janas scoreParticles --gpu 0,1`, including half-map
|
|
32
|
+
scoring, multiple sigmas, Euler-balanced ranking and image subtraction.
|
|
33
|
+
- GPU scoring in particle-selection and class-reassignment sessions; the
|
|
34
|
+
ordered device list is saved and forwarded to generated commands.
|
|
35
|
+
- Batched internal GPU reconstruction across the requested devices, including
|
|
36
|
+
cumulative subset checkpoints and independent half maps, with bounded reads
|
|
37
|
+
and Fourier preparation. The internal method uses per-particle CTF
|
|
38
|
+
correction, nearest-grid insertion and hit-count normalisation.
|
|
39
|
+
- Opt-in `--sci-option floorproduct` on CPU and GPU: each SCI factor is floored
|
|
40
|
+
at 1e-8, with zero retained when all five raw factors are <= 1e-8. The default
|
|
41
|
+
remains the paper's `product` policy. The choice can change ranks, selections
|
|
42
|
+
and class assignments.
|
|
43
|
+
- Optional GPU subtraction controls: subtraction-only low-pass/FSC weighting,
|
|
44
|
+
fixed or regularised fitted amplitudes, mask edges and a scoring sigma
|
|
45
|
+
multiplier. Fitted amplitudes are recorded in the STAR.
|
|
46
|
+
- Optional 3D-region subtraction and local-resolution-adapted subtraction,
|
|
47
|
+
combined with the amplitude controls. Supply a removal-region mask for 3D
|
|
48
|
+
mode. See [Subtraction operators](docs/subtraction_operators.md).
|
|
49
|
+
- [GPU usage](docs/gpu.md) and [complete CLI benchmarks](docs/reference/gpu-benchmarks.md)
|
|
50
|
+
for 5,000 native 384-pixel particles, including whole-node CPU, one/four A100
|
|
51
|
+
and four L40S measurements, both repeats and numerical checks. Timings
|
|
52
|
+
describe the stated fixtures, cache conditions and concurrent workloads.
|
|
53
|
+
|
|
54
|
+
### Changed
|
|
55
|
+
|
|
56
|
+
- Scoring and internal reconstruction default to all visible CUDA devices
|
|
57
|
+
(`--gpu auto`), with a logged CPU/MPI fallback. Use `--gpu none` to force CPU;
|
|
58
|
+
generated sessions resolve auto on the executing node.
|
|
59
|
+
|
|
60
|
+
- Documentation recommends GPU selection and class reassignment, with generic
|
|
61
|
+
Slurm examples, subtraction workflows and CPU alternatives.
|
|
62
|
+
|
|
63
|
+
- Internal CPU multiworker reconstruction applies the selected CTF mode and
|
|
64
|
+
Wiener regularisation, including SSNR-derived tau curves. Internal GPU
|
|
65
|
+
reconstruction uses canonical CPU Fourier/CTF preparation, excludes
|
|
66
|
+
exact-zero corrected samples from hit counts and enforces explicit devices
|
|
67
|
+
through finishing and blur. Same-host CPU/GPU agreement is measured;
|
|
68
|
+
cross-host NumPy dispatch can affect rounding.
|
|
69
|
+
- Scoring subtraction with CTF uses explicit double-precision FFTs across
|
|
70
|
+
NumPy versions. Empty effective subtraction masks produce a GPU warning and
|
|
71
|
+
are skipped; GPU scoring reuses the full-map subtraction projection across sigmas.
|
|
72
|
+
- Selection sessions forward `--subtractionMask` to each scoring stage.
|
|
73
|
+
- Class reassignment writes class STARs for RELION 3.0 and 3.1 inputs, inserts
|
|
74
|
+
missing class labels and stops on score-join or extraction failure.
|
|
75
|
+
- Standalone `rankParticles` writes normalised ranks and separate view labels,
|
|
76
|
+
preserves field tokens and rejects output columns that collide with input
|
|
77
|
+
scores.
|
|
78
|
+
- MRC output uses deterministic MRC2014 headers, valid statistics and input
|
|
79
|
+
pixel spacing; slice-filled stacks contain their requested images and failed
|
|
80
|
+
reads or writes raise errors. Mode-12 float16 stacks are supported;
|
|
81
|
+
unsupported MRC modes are rejected.
|
|
82
|
+
- Map utilities preserve non-cubic geometry and validate matching mask sizes.
|
|
83
|
+
- Scoring accepts missing CTF B-factor and phase-shift fields with logged zero
|
|
84
|
+
defaults. Internal reconstruction without a class selection accepts missing
|
|
85
|
+
class labels as class 1.
|
|
86
|
+
- Generated text is UTF-8 and console output supports ASCII locales.
|
|
87
|
+
- Frequency-adaptive local resolution uses complete windows on a shared,
|
|
88
|
+
origin-anchored lattice and persists a schema-4 comparison plan. The
|
|
89
|
+
`--max-resolution` default is 45 Angstrom. Masks define bounding boxes;
|
|
90
|
+
`--accurate` is removed. Legacy estimation remains available through
|
|
91
|
+
`--no-adaptive-sampling` or schema-3 plan replay. Bulk and requested
|
|
92
|
+
reconstructor local-resolution failures stop with their cause.
|
|
93
|
+
|
|
94
|
+
RELION remains the default session reconstruction route. `--gpu` selects JANAS
|
|
95
|
+
GPU scoring; `--noExternalPrograms` selects internal reconstruction. CPU SCI
|
|
96
|
+
continues to default to `product`. See [GPU usage](docs/gpu.md) for execution,
|
|
97
|
+
memory and reproducibility details.
|
|
98
|
+
|
|
99
|
+
## 2.2.3
|
|
100
|
+
|
|
101
|
+
- **Anchor lattice generated exactly.** The Fibonacci lattice of anchor
|
|
102
|
+
views used by the Euler-balanced ranking (`scoreNormalizationHomogeneousViews`,
|
|
103
|
+
behind `EqualizedParticlesRank`, and `getEulerClassGroup`, both in
|
|
104
|
+
`src/src_cpp/euler_libs.h`) computed the z-coordinate of the anchors as a
|
|
105
|
+
running sum `K += 2/(n-1)`. For about half of all view numbers (1,396 of
|
|
106
|
+
the 2,999 values between 2 and 3000, among them 200 and 500) the sum
|
|
107
|
+
drifted just past 1.0 and the polar anchor was dropped, so that
|
|
108
|
+
`--numViews 500` produced 499 anchors and `--numViews 200` produced 199.
|
|
109
|
+
The coordinate is now computed as `-1 + 2 i/(n-1)` and clamped to 1.0;
|
|
110
|
+
every requested anchor exists and the regression test checks the anchor
|
|
111
|
+
count. For the other view numbers (for example 350 and 1500) only the
|
|
112
|
+
polar anchor moves, by floating-point rounding of the order of 1e-5
|
|
113
|
+
degrees (at most 2.3e-5 degrees for n up to 3000); all other anchors are
|
|
114
|
+
unchanged.
|
|
115
|
+
The same loop in the homogeneous-distribution simulation of
|
|
116
|
+
`janas_app_starProcess.cxx` is corrected in the same way.
|
|
117
|
+
|
|
3
118
|
## 2.2.2
|
|
4
119
|
|
|
5
120
|
- **Refined particle metadata retrieved through the cryosparc-tools API.**
|
janas-2.2.4/CITATION.cff
ADDED
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
cff-version: 1.2.0
|
|
2
|
+
message: "If you use this software, please cite it as below."
|
|
3
|
+
title: "JANAS: Joint ANAlysis of Stacks for CryoEM"
|
|
4
|
+
type: software
|
|
5
|
+
authors:
|
|
6
|
+
- family-names: Maiorca
|
|
7
|
+
given-names: Mauro
|
|
8
|
+
email: mauro.maiorca@cssb-hamburg.de
|
|
9
|
+
repository-code: https://gitlab.com/topf-lab/janas
|
|
10
|
+
license: MIT
|
|
11
|
+
version: 2.2.4
|
|
12
|
+
date-released: 2026-10-31
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: janas
|
|
3
|
-
Version: 2.2.
|
|
3
|
+
Version: 2.2.4
|
|
4
4
|
Summary: Pipeline for per-particle selection and 3D class reassignment in single-particle cryo-EM.
|
|
5
5
|
Home-page: https://gitlab.com/topf-lab/janas
|
|
6
6
|
Author: Mauro Maiorca
|
|
@@ -22,6 +22,7 @@ Requires-Dist: scikit-image>=0.18
|
|
|
22
22
|
Requires-Dist: matplotlib>=3.3
|
|
23
23
|
Requires-Dist: seaborn>=0.11
|
|
24
24
|
Requires-Dist: toml>=0.10
|
|
25
|
+
Requires-Dist: mrcfile>=1.5.4
|
|
25
26
|
Provides-Extra: gpu
|
|
26
27
|
Requires-Dist: torch>=2.0; extra == "gpu"
|
|
27
28
|
Dynamic: author
|
|
@@ -65,7 +66,8 @@ It uses the per-particle Structural Cross-correlation Index (SCI) to rank partic
|
|
|
65
66
|
- [Install from PyPI](https://pypi.org/project/janas/) — install JANAS with `pip install janas`.
|
|
66
67
|
- [Source code](https://gitlab.com/topf-lab/janas) — main GitLab repository.
|
|
67
68
|
- [Documentation](docs/) — installation, workflows, command reference and utilities.
|
|
68
|
-
- [Quick start](docs/quick-start.md)
|
|
69
|
+
- [Quick start](docs/quick-start.md): minimal commands to start using JANAS.
|
|
70
|
+
- [Slurm examples](docs/slurm_examples.md): four-card Slurm workflows.
|
|
69
71
|
- [Particle selection workflow](docs/workflows/selection.md) — SCI-based ranking and subset selection.
|
|
70
72
|
- [3D class reassignment workflow](docs/workflows/classification.md) — reassignment of particles across predefined 3D classes.
|
|
71
73
|
- [Demo bundle](demo_bundle/) — self-contained software-testing bundle with example inputs, scripts, expected outputs, run-time information and documentation for particle selection and 3D class reassignment.
|
|
@@ -82,6 +84,29 @@ The demo package contains small example inputs, scripts, expected outputs and ru
|
|
|
82
84
|
| [3D class reassignment](docs/CLASS_REASSIGNMENT.md) | Assign particles to pre-computed classes using per-map SCI scores. |
|
|
83
85
|
|
|
84
86
|
|
|
87
|
+
## GPU execution
|
|
88
|
+
|
|
89
|
+
Scoring and internal reconstruction default to all visible CUDA devices
|
|
90
|
+
(`--gpu auto`), with a logged CPU/MPI fallback when CUDA is unavailable.
|
|
91
|
+
Explicit examples can still pass `--gpu 0,1`; JANAS 2.2.4
|
|
92
|
+
supports CUDA SCI scoring and internal reconstruction. Sessions retain RELION
|
|
93
|
+
as their default reconstruction route; add `--noExternalPrograms` for internal
|
|
94
|
+
reconstruction. See [GPU usage](docs/gpu.md),
|
|
95
|
+
[optional subtraction operators](docs/subtraction_operators.md) and
|
|
96
|
+
[measured CLI timings](docs/reference/gpu-benchmarks.md). CPU SCI defaults to
|
|
97
|
+
the paper's `product` policy; `--sci-option floorproduct` is opt-in. Use
|
|
98
|
+
`--gpu none --mpi 16` to force CPU scoring, or `--gpu none --cpu 16` for
|
|
99
|
+
standalone CPU reconstruction.
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
janas scoreParticles --i particles.star --map halfA.mrc --map2 halfB.mrc \
|
|
103
|
+
--mask mask.mrc --apix 0.83 --sigma 1 --gpu 0,1 --o scored.star
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
> **Example of use on a cluster (Slurm):** see the
|
|
107
|
+
> [four-card Slurm workflows](docs/slurm_examples.md) for selection with and
|
|
108
|
+
> without subtraction, class reassignment, environment setup and timing.
|
|
109
|
+
|
|
85
110
|
## Monitoring a running session
|
|
86
111
|
|
|
87
112
|
JANAS records the outcome of every selection iteration in `overview.txt` and the timing of every individual processing step in `runtime/step_timings.csv`. While the session runs it also keeps an HTML dashboard, `progress.html`, in sync with the latest state. See [Monitoring a running session](docs/progress_dashboard.md) for how to view it locally or over SSH from a remote browser.
|
|
@@ -137,6 +162,7 @@ See the [Installation Guide](docs/installation.md) for conda, pipx, troubleshoot
|
|
|
137
162
|
- [Documentation index](docs/index.md)
|
|
138
163
|
- [Installation](docs/installation.md)
|
|
139
164
|
- [Quick start](docs/quick-start.md)
|
|
165
|
+
- [Slurm examples](docs/slurm_examples.md)
|
|
140
166
|
- [Iterative particle selection](docs/workflows/selection.md)
|
|
141
167
|
- [3D class reassignment](docs/workflows/classification.md)
|
|
142
168
|
- [CryoSPARC integration](docs/workflows/cryosparc.md)
|
|
@@ -26,7 +26,8 @@ It uses the per-particle Structural Cross-correlation Index (SCI) to rank partic
|
|
|
26
26
|
- [Install from PyPI](https://pypi.org/project/janas/) — install JANAS with `pip install janas`.
|
|
27
27
|
- [Source code](https://gitlab.com/topf-lab/janas) — main GitLab repository.
|
|
28
28
|
- [Documentation](docs/) — installation, workflows, command reference and utilities.
|
|
29
|
-
- [Quick start](docs/quick-start.md)
|
|
29
|
+
- [Quick start](docs/quick-start.md): minimal commands to start using JANAS.
|
|
30
|
+
- [Slurm examples](docs/slurm_examples.md): four-card Slurm workflows.
|
|
30
31
|
- [Particle selection workflow](docs/workflows/selection.md) — SCI-based ranking and subset selection.
|
|
31
32
|
- [3D class reassignment workflow](docs/workflows/classification.md) — reassignment of particles across predefined 3D classes.
|
|
32
33
|
- [Demo bundle](demo_bundle/) — self-contained software-testing bundle with example inputs, scripts, expected outputs, run-time information and documentation for particle selection and 3D class reassignment.
|
|
@@ -43,6 +44,29 @@ The demo package contains small example inputs, scripts, expected outputs and ru
|
|
|
43
44
|
| [3D class reassignment](docs/CLASS_REASSIGNMENT.md) | Assign particles to pre-computed classes using per-map SCI scores. |
|
|
44
45
|
|
|
45
46
|
|
|
47
|
+
## GPU execution
|
|
48
|
+
|
|
49
|
+
Scoring and internal reconstruction default to all visible CUDA devices
|
|
50
|
+
(`--gpu auto`), with a logged CPU/MPI fallback when CUDA is unavailable.
|
|
51
|
+
Explicit examples can still pass `--gpu 0,1`; JANAS 2.2.4
|
|
52
|
+
supports CUDA SCI scoring and internal reconstruction. Sessions retain RELION
|
|
53
|
+
as their default reconstruction route; add `--noExternalPrograms` for internal
|
|
54
|
+
reconstruction. See [GPU usage](docs/gpu.md),
|
|
55
|
+
[optional subtraction operators](docs/subtraction_operators.md) and
|
|
56
|
+
[measured CLI timings](docs/reference/gpu-benchmarks.md). CPU SCI defaults to
|
|
57
|
+
the paper's `product` policy; `--sci-option floorproduct` is opt-in. Use
|
|
58
|
+
`--gpu none --mpi 16` to force CPU scoring, or `--gpu none --cpu 16` for
|
|
59
|
+
standalone CPU reconstruction.
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
janas scoreParticles --i particles.star --map halfA.mrc --map2 halfB.mrc \
|
|
63
|
+
--mask mask.mrc --apix 0.83 --sigma 1 --gpu 0,1 --o scored.star
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
> **Example of use on a cluster (Slurm):** see the
|
|
67
|
+
> [four-card Slurm workflows](docs/slurm_examples.md) for selection with and
|
|
68
|
+
> without subtraction, class reassignment, environment setup and timing.
|
|
69
|
+
|
|
46
70
|
## Monitoring a running session
|
|
47
71
|
|
|
48
72
|
JANAS records the outcome of every selection iteration in `overview.txt` and the timing of every individual processing step in `runtime/step_timings.csv`. While the session runs it also keeps an HTML dashboard, `progress.html`, in sync with the latest state. See [Monitoring a running session](docs/progress_dashboard.md) for how to view it locally or over SSH from a remote browser.
|
|
@@ -98,6 +122,7 @@ See the [Installation Guide](docs/installation.md) for conda, pipx, troubleshoot
|
|
|
98
122
|
- [Documentation index](docs/index.md)
|
|
99
123
|
- [Installation](docs/installation.md)
|
|
100
124
|
- [Quick start](docs/quick-start.md)
|
|
125
|
+
- [Slurm examples](docs/slurm_examples.md)
|
|
101
126
|
- [Iterative particle selection](docs/workflows/selection.md)
|
|
102
127
|
- [3D class reassignment](docs/workflows/classification.md)
|
|
103
128
|
- [CryoSPARC integration](docs/workflows/cryosparc.md)
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
[Repository home](../README.md) · [Installation](installation.md) · [Quick start](quick-start.md) · [CLI reference](reference/cli.md) · [Troubleshooting](troubleshooting.md)
|
|
2
|
+
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
# 3D Class reassignment
|
|
6
|
+
|
|
7
|
+
<p align="center">
|
|
8
|
+
<img src="images/fig1B.png" alt="fig1B.png" width="600">
|
|
9
|
+
</p>
|
|
10
|
+
|
|
11
|
+
3D class reassignment refines particle membership across a set of user-provided reference maps. The input maps usually come from a previous 3D classification step and represent alternative conformational states, but they can also be generated using different masks, refinements, or processing strategies.
|
|
12
|
+
|
|
13
|
+
JANAS compares each particle with reprojections from every reference map using the Structural Cross-correlation Index (SCI). Each particle is then assigned to the class that best matches its structural signal. This can correct particle misassignment from an initial classification and reduce differences in class quality, especially when classes contain related conformations, minority states, or particles affected by local heterogeneity.
|
|
14
|
+
|
|
15
|
+
After reassignment, each class can be reconstructed directly or passed to iterative particle selection. This per-class selection step can further improve the coherence of each state before downstream refinement, inspection, or another round of classification.
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
## Quick start
|
|
19
|
+
|
|
20
|
+
### Create and launch a GPU session (recommended)
|
|
21
|
+
|
|
22
|
+
Run these commands on a compute node. Omission defaults to all visible CUDA
|
|
23
|
+
devices when the session executes, with a logged CPU/MPI fallback when CUDA
|
|
24
|
+
is unavailable. Use `--gpu none --mpi 16` to force CPU execution. See [memory and batch planning](gpu.md#memory-and-batches).
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
janas_session_manager classification_session \
|
|
28
|
+
--name reclassify \
|
|
29
|
+
--particles particles.star \
|
|
30
|
+
--maps class1.mrc class2.mrc class3.mrc \
|
|
31
|
+
--mask mask.mrc \
|
|
32
|
+
--mpi 16 \
|
|
33
|
+
--noExternalPrograms --gpu 0,1
|
|
34
|
+
|
|
35
|
+
./reclassify/reclassify_run.sh
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
> **Example of use on a cluster (Slurm):**
|
|
39
|
+
> [Submit a whole four-card node](slurm_examples.md#submit-one-executable-workflow)
|
|
40
|
+
> for selection with/without subtraction or class reassignment, including
|
|
41
|
+
> internal reconstruction, local resolution and wall-time logging.
|
|
42
|
+
|
|
43
|
+
To force a specific CTF handling during scoring, add `--ctf-mode`:
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
janas_session_manager classification_session \
|
|
47
|
+
... \
|
|
48
|
+
--ctf-mode modulate
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Choices: `phaseflip` (default — applies `sign(CTF)`), `modulate` (multiplies by the full CTF), `wiener` (`CTF / (CTF² + 0.1)`).
|
|
52
|
+
|
|
53
|
+
The SCI scores use the paper's Eq. 3 by default (each factor clamped at 0). Add `--sci-option floorproduct` to floor each of the five SCI factors at 1e-8 instead of 0; the SCI is 0 only when all five factors are <= 1e-8. A particle with zero SCI for every class follows the same assignment and tie handling as in `product` mode. The choice is saved in the session settings and used by every scoring call. The floor is planned to become the default in JANAS 2.3.0.
|
|
54
|
+
|
|
55
|
+
## Skipping reconstruction with `--noRecs`
|
|
56
|
+
|
|
57
|
+
If you want to score and assign particles but reconstruct each class yourself with an external tool (RELION, cryoSPARC, etc.), add `--noRecs`:
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
janas_session_manager classification_session \
|
|
61
|
+
--name reclassify \
|
|
62
|
+
--particles particles.star \
|
|
63
|
+
--maps class1.mrc class2.mrc class3.mrc \
|
|
64
|
+
--mask mask.mrc \
|
|
65
|
+
--mpi 16 \
|
|
66
|
+
--noRecs --gpu 0,1
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
The run script will produce the per-class STAR files in `reclassify/final_classes/` (`class_1.star`, `class_2.star`, ...) but skip reconstruction. You can then reconstruct each class with the software of your choice, for example:
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
relion_reconstruct --i class_1.star --o class_1.mrc --ctf
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Output: `reclassify/final_classes/`
|
|
76
|
+
|
|
77
|
+
> `--gpu 0,1` runs particle scoring on the listed CUDA devices. Add
|
|
78
|
+
> `--noExternalPrograms` to use JANAS internal GPU reconstruction too; without
|
|
79
|
+
> it, reconstruction and local resolution use RELION. Internal session local
|
|
80
|
+
> resolution uses CPU workers. See [GPU usage](gpu.md) for device syntax, memory and reproducibility.
|
|
81
|
+
|
|
82
|
+
See [scoring and assignment steps](workflows/classification.md#scoring-and-assignment-steps)
|
|
83
|
+
for the GPU commands and [the CPU alternative](workflows/classification.md#cpu-alternative).
|
|
84
|
+
The class-session generator does not accept `--subtractionMask` or SUBX
|
|
85
|
+
controls; [optional subtraction operators](subtraction_operators.md) are
|
|
86
|
+
available through explicit scoring commands.
|
|
87
|
+
|
|
88
|
+
## About `--mpi`
|
|
89
|
+
|
|
90
|
+
`--gpu` sets the GPU worker list independently of `--mpi`. With GPU scoring,
|
|
91
|
+
`--mpi` supplies CPU workers for host stages, including internal selection
|
|
92
|
+
local resolution. For the CPU alternative, `--mpi` sets the number of
|
|
93
|
+
parallel scoring worker processes. The requested value is automatically capped to a safe one at runtime:
|
|
94
|
+
|
|
95
|
+
1. If `--mpi` is greater than the number of available CPU cores, it is reduced to the CPU count (`multiprocessing.cpu_count()`). For example, requesting `--mpi 50` on a machine with 20 cores will use 20.
|
|
96
|
+
2. If `--mpi` is less than 1, it is raised to 1.
|
|
97
|
+
3. If `--mpi` is greater than the number of particles being processed, it is reduced to the particle count.
|
|
98
|
+
|
|
99
|
+
This means you can safely set `--mpi` to a generous value and JANAS will pick the largest reasonable number of workers without over-subscribing the machine. For best performance, set `--mpi` to the number of physical cores you want to dedicate to the run.
|
|
@@ -0,0 +1,270 @@
|
|
|
1
|
+
[Repository home](../README.md) · [Installation](installation.md) · [Quick start](quick-start.md) · [CLI reference](reference/cli.md) · [Troubleshooting](troubleshooting.md)
|
|
2
|
+
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
# Iterative Selection
|
|
6
|
+
|
|
7
|
+
<p align="center">
|
|
8
|
+
<img src="images/fig1A.png" alt="fig1A.png" width="600">
|
|
9
|
+
</p>
|
|
10
|
+
|
|
11
|
+
Iterative selection identifies a particle subset that aims to support a more interpretable reconstruction. Starting from an input particle stack (and ideally reference half maps, and mask), JANAS scores particles using the Structural Cross-correlation Index (SCI), ranks them while accounting for angular distribution, and evaluates candidate particle subsets through repeated reconstruction.
|
|
12
|
+
|
|
13
|
+
Rather than selecting a fixed percentage of particles, JANAS searches for the particle count that gives the most favourable local-resolution behaviour within the masked region. This allows the workflow to retain particles that contribute consistently to the reconstruction while excluding particles that reduce map quality or introduce artefacts.
|
|
14
|
+
|
|
15
|
+
> 📊 **Watch a run live:** while the script is executing, the session directory always carries an up-to-date HTML dashboard (`progress.html`). See **[Monitoring a running session](progress_dashboard.md)** for how to open it locally or over SSH from a remote browser — it is the recommended way to follow what JANAS is doing.
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
## Quick start
|
|
19
|
+
|
|
20
|
+
### Create and launch a GPU session (recommended)
|
|
21
|
+
|
|
22
|
+
Run these commands on a compute node. Omission defaults to all visible CUDA
|
|
23
|
+
devices when the session executes, with a logged CPU/MPI fallback when CUDA
|
|
24
|
+
is unavailable. Use `--gpu none --mpi 16` to force CPU execution. See [memory and batch planning](gpu.md#memory-and-batches).
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
janas_session_manager new_select_session \
|
|
28
|
+
--name my_selection \
|
|
29
|
+
--particles particles.star \
|
|
30
|
+
--map halfA.mrc \
|
|
31
|
+
--map2 halfB.mrc \
|
|
32
|
+
--mask mask.mrc \
|
|
33
|
+
--mpi 16 \
|
|
34
|
+
--noExternalPrograms --gpu 0,1
|
|
35
|
+
|
|
36
|
+
./my_selection/my_selection_run.sh
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
> `--gpu 0,1` runs particle scoring on the listed CUDA devices. Add
|
|
40
|
+
> `--noExternalPrograms` to use JANAS internal GPU reconstruction too; without
|
|
41
|
+
> it, reconstruction and local resolution use RELION. Internal session local
|
|
42
|
+
> resolution uses CPU workers. See [GPU usage](gpu.md) for device syntax, memory and reproducibility.
|
|
43
|
+
|
|
44
|
+
> **Example of use on a cluster (Slurm):**
|
|
45
|
+
> [Submit a whole four-card node](slurm_examples.md#submit-one-executable-workflow)
|
|
46
|
+
> for selection with/without subtraction or class reassignment, including
|
|
47
|
+
> internal reconstruction, local resolution and wall-time logging.
|
|
48
|
+
|
|
49
|
+
For selection with subtraction, add `--subtractionMask subtraction_mask.mrc`
|
|
50
|
+
to the command above. See [the subtraction workflow](workflows/selection.md#selection-with-image-subtraction)
|
|
51
|
+
and [opt-in SUBX controls](subtraction_operators.md). For CPU execution, see
|
|
52
|
+
[the CPU alternative](workflows/selection.md#cpu-alternative).
|
|
53
|
+
|
|
54
|
+
## About `--mpi`
|
|
55
|
+
|
|
56
|
+
`--gpu` sets the GPU worker list independently of `--mpi`. With GPU scoring,
|
|
57
|
+
`--mpi` supplies CPU workers for host stages, including internal selection
|
|
58
|
+
local resolution. For the CPU alternative, `--mpi` sets the number of
|
|
59
|
+
parallel scoring worker processes. The requested value is automatically capped to a safe one at runtime:
|
|
60
|
+
|
|
61
|
+
1. If `--mpi` is greater than the number of available CPU cores, it is reduced to the CPU count (`multiprocessing.cpu_count()`). For example, requesting `--mpi 50` on a machine with 20 cores will use 20.
|
|
62
|
+
2. If `--mpi` is less than 1, it is raised to 1.
|
|
63
|
+
3. If `--mpi` is greater than the number of particles being processed, it is reduced to the particle count.
|
|
64
|
+
|
|
65
|
+
This means you can safely set `--mpi` to a generous value and JANAS will pick the largest reasonable number of workers without over-subscribing the machine. For best performance, set `--mpi` to the number of physical cores you want to dedicate to the run.
|
|
66
|
+
|
|
67
|
+
---
|
|
68
|
+
|
|
69
|
+
## Advanced example
|
|
70
|
+
|
|
71
|
+
A typical command using most of the available options — including
|
|
72
|
+
`--autoSigma`, which JANAS can use **from the very first selection** as
|
|
73
|
+
long as `--map` and `--map2` are independent half-maps (or `--bootstrap`
|
|
74
|
+
is set, which generates an independent pair on the fly):
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
janas_session_manager new_select_session \
|
|
78
|
+
--name janas_selection_adptiveMaskRound01 \
|
|
79
|
+
--particles J606_004_particlesStack.star \
|
|
80
|
+
--map J606_004_particlesStack_recH1.mrc \
|
|
81
|
+
--map2 J606_004_particlesStack_recH2.mrc \
|
|
82
|
+
--mask maskFinal/mask_AB_dilated2.mrc \
|
|
83
|
+
--assessMask maskFinal/E12707_assessmentMask_AB.mrc \
|
|
84
|
+
--preGaussianBlur 1 \
|
|
85
|
+
--bootstrap \
|
|
86
|
+
--angpix 0.9540 \
|
|
87
|
+
--autoSigma \
|
|
88
|
+
--maxSelections 15 \
|
|
89
|
+
--numRecs 10 \
|
|
90
|
+
--numViews 350 \
|
|
91
|
+
--mpi 80 \
|
|
92
|
+
--gpu 0,1 \
|
|
93
|
+
--noExternalPrograms \
|
|
94
|
+
--adaptive_mask
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
If you would rather pin sigma explicitly (e.g. for a controlled
|
|
98
|
+
comparison across runs), replace `--autoSigma` with `--sigma 1`.
|
|
99
|
+
|
|
100
|
+
A subsequent round naturally reuses the half-maps of the previous round
|
|
101
|
+
as the new `--map` / `--map2`:
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
janas_session_manager new_select_session \
|
|
105
|
+
--name janas_selection_adptiveMaskRound02b \
|
|
106
|
+
--particles janas_selection_adptiveMaskRound01/refine_LR/particles_0004.star \
|
|
107
|
+
--map janas_selection_adptiveMaskRound01/refine_LR/J899_004_volume_map_half_A.mrc \
|
|
108
|
+
--map2 janas_selection_adptiveMaskRound01/refine_LR/J899_004_volume_map_half_B.mrc \
|
|
109
|
+
--mask maskFinal/mask_AB_dilated2.mrc \
|
|
110
|
+
--assessMask maskFinal/E12707_assessmentMask_AB.mrc \
|
|
111
|
+
--preGaussianBlur 1 \
|
|
112
|
+
--bootstrap \
|
|
113
|
+
--angpix 0.9540 \
|
|
114
|
+
--autoSigma \
|
|
115
|
+
--maxSelections 15 \
|
|
116
|
+
--numRecs 10 \
|
|
117
|
+
--numViews 350 \
|
|
118
|
+
--mpi 70 \
|
|
119
|
+
--gpu 0,1 \
|
|
120
|
+
--noExternalPrograms \
|
|
121
|
+
--adaptive_mask
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
### Highlights of the advanced workflow
|
|
125
|
+
|
|
126
|
+
A few things in the command above are worth calling out explicitly,
|
|
127
|
+
because they change the behaviour of the selection in non-obvious ways.
|
|
128
|
+
|
|
129
|
+
#### Use `--assessMask` to focus the optimiser — but only on densities you trust
|
|
130
|
+
|
|
131
|
+
`--assessMask` separates the **scoring region** (`--mask`, used during
|
|
132
|
+
SCI) from the **assessment region** (where local resolution is
|
|
133
|
+
measured to decide which subset is best). This lets you score against a
|
|
134
|
+
broad mask covering the full particle while optimising the selection
|
|
135
|
+
for the local resolution of a specific functional region.
|
|
136
|
+
|
|
137
|
+
This is a very powerful lever, and it is exactly the reason it has to
|
|
138
|
+
be used carefully. As discussed in the
|
|
139
|
+
[JANAS manuscript](citation.md), the optimiser will
|
|
140
|
+
**chase any signal that increases local resolution inside the assess
|
|
141
|
+
mask** — including artefacts inherited from earlier processing steps.
|
|
142
|
+
A good `--assessMask` should therefore enclose **only densities you are
|
|
143
|
+
confident about**:
|
|
144
|
+
|
|
145
|
+
- Avoid regions with obvious overfitting bumps, streaks, or other
|
|
146
|
+
reconstruction artefacts (e.g. from an over-aggressive angular
|
|
147
|
+
refinement upstream).
|
|
148
|
+
- Avoid solvent / disordered regions and box edges.
|
|
149
|
+
- Prefer well-resolved, structurally meaningful densities — even if
|
|
150
|
+
that means making the mask small.
|
|
151
|
+
|
|
152
|
+
The same caveat applies, to a lesser extent, to `--mask`, but
|
|
153
|
+
`--assessMask` is what the optimiser ultimately reads as "ground truth",
|
|
154
|
+
so it is the one that benefits the most from a conservative definition.
|
|
155
|
+
|
|
156
|
+
#### `--adaptive_mask`: the same caveat, amplified
|
|
157
|
+
|
|
158
|
+
`--adaptive_mask` builds the assessment mask **dynamically** at every
|
|
159
|
+
iteration, by carving out the highest-resolution voxels inside
|
|
160
|
+
`--assessMask` (or `--mask` if no `--assessMask` is given). This is
|
|
161
|
+
extremely effective at locking onto the well-resolved parts of the map,
|
|
162
|
+
but it also **amplifies every problem of the parent mask**: if
|
|
163
|
+
`--assessMask` includes an overfit hotspot, the adaptive mask will
|
|
164
|
+
shrink onto it and the optimiser will happily race towards a fictitious
|
|
165
|
+
high-resolution score.
|
|
166
|
+
|
|
167
|
+
Rule of thumb: when you enable `--adaptive_mask`, audit the
|
|
168
|
+
`--assessMask` (or `--mask`) you are feeding it more strictly than you
|
|
169
|
+
would otherwise. The combination is the most powerful tool JANAS
|
|
170
|
+
exposes and, by the same token, the easiest one to misuse.
|
|
171
|
+
|
|
172
|
+
#### `--aggressive`: trade thoroughness for wall-clock time
|
|
173
|
+
|
|
174
|
+
`--aggressive` makes the optimiser update the target particles from the
|
|
175
|
+
current overview selection at every iteration, rather than waiting for
|
|
176
|
+
the usual stability checks. The selection converges in fewer
|
|
177
|
+
iterations and the run wall-clock goes down noticeably, at the cost of
|
|
178
|
+
slightly less robustness against transient regressions.
|
|
179
|
+
|
|
180
|
+
Use it when you need to wrap up a session quickly — for example when
|
|
181
|
+
you are iterating on parameters, or when you want to launch a JANAS-
|
|
182
|
+
based repicking pass (see
|
|
183
|
+
[custom selected stacks](custom_selected_stacks.md)) before the end of
|
|
184
|
+
the working day. For final, publication-grade selections, leaving
|
|
185
|
+
`--aggressive` off is the safer default.
|
|
186
|
+
|
|
187
|
+
#### Following the run
|
|
188
|
+
|
|
189
|
+
Every option above changes what the optimiser does at every iteration —
|
|
190
|
+
the best way to confirm that the run is doing what you expect is to
|
|
191
|
+
open `progress.html` and watch the *Current stage*, the per-iteration
|
|
192
|
+
overview and the live Euler-angle histograms. See
|
|
193
|
+
[Monitoring a running session](progress_dashboard.md).
|
|
194
|
+
|
|
195
|
+
---
|
|
196
|
+
|
|
197
|
+
## Parameters reference
|
|
198
|
+
|
|
199
|
+
The arguments are grouped as in `janas_session_manager new_select_session --help`. Only the most frequently used options are listed here; run the command with `--help` for the full list including expert-level tuning parameters.
|
|
200
|
+
|
|
201
|
+
### Core inputs
|
|
202
|
+
|
|
203
|
+
| Flag | Required | Description |
|
|
204
|
+
|---|---|---|
|
|
205
|
+
| `--name` | yes | Name of the new session. Creates a directory and a TOML settings file inside it. |
|
|
206
|
+
| `--particles` | yes | STAR file with the list of particles. |
|
|
207
|
+
| `--map` | yes | First reference (a full reconstruction, or the first half-map of a pair). |
|
|
208
|
+
| `--map2` | no | Second half-map. Required for any workflow that needs an independent half-map pair (gold-standard FSC, auto-sigma, bootstrap). |
|
|
209
|
+
| `--angpix` | no | Pixel spacing in Å/pixel. If omitted, it is inferred from `--map`. |
|
|
210
|
+
|
|
211
|
+
### Masks
|
|
212
|
+
|
|
213
|
+
| Flag | Required | Description |
|
|
214
|
+
|---|---|---|
|
|
215
|
+
| `--mask` | yes | Main 3D mask used during particle scoring (defines the region of interest). |
|
|
216
|
+
| `--assessMask` | no | MRC mask used **only** for the local-resolution assessment that drives the selection. If omitted, the main `--mask` is used. Useful when you want to score against a broad mask but optimise local resolution within a tighter region (for example, a single domain). |
|
|
217
|
+
| `--adaptive_mask` | no | Build an adaptive assessment mask from `partialLocres.mrc` and use it for the final `locresStats` evaluation of each selection. The adaptive mask is recomputed every iteration as the reconstruction improves. |
|
|
218
|
+
| `--adaptive_mask_locres_blur` | no | Gaussian sigma (default `1.0`) used by `janas_utils split_mask` when deriving the adaptive assessment mask. |
|
|
219
|
+
| `--adaptive_mask_independent` | no | Force the current iteration to use an independent adaptive mask without merging it with the target adaptive mask. Implies `--adaptive_mask`. |
|
|
220
|
+
| `--subtractionMask` | no | Optional 3D MRC mask defining the region to subtract during scoring (map-based signal subtraction). |
|
|
221
|
+
|
|
222
|
+
### Scoring and assessment
|
|
223
|
+
|
|
224
|
+
| Flag | Default | Description |
|
|
225
|
+
|---|---|---|
|
|
226
|
+
| `--sigma` | `1.0` | Gaussian sigma (in pixels) used by SCI scoring. Larger values smooth out high-frequency noise; smaller values emphasise fine structure. See [sigma_estimate](sigma_estimate.md) for the full theory. |
|
|
227
|
+
| `--preGaussianBlur` | `0.0` | Gaussian blur applied to the input map(s) **before** scoring (sigma in Å). Use `0` (the default) to disable. A small blur (e.g. `1`) reduces sensitivity to high-frequency reconstruction artefacts when scoring against unsharpened half-maps. |
|
|
228
|
+
| `--ctf-mode` | `phaseflip` | CTF application mode for particle scoring: `modulate` (multiply by the full CTF), `phaseflip` (sign of CTF), or `wiener` (`CTF / (CTF² + 0.1)`). |
|
|
229
|
+
| `--sci-option` | `product` | SCI factor combination: `product` (the paper's Eq. 3, each factor clamped at 0) or `floorproduct` (each of the five SCI factors is floored at 1e-8 instead of 0; the SCI is 0 only when all five factors are <= 1e-8; planned to become the default in JANAS 2.3.0). Saved in the session settings and forwarded to every scoring call. |
|
|
230
|
+
| `--postprocessing` | `avg` | Post-processing mode used when combining half-maps: `avg` or `autobfac`. |
|
|
231
|
+
| `--resolutionBestTarget` | `meanResolution` | Resolution statistic to optimise. One of `meanResolution`, `highResolution`, `highresolutionquartile`, `lowResolution`, `lowresolutionquartile`. |
|
|
232
|
+
| `--assessmentMethod` | `mean` | Statistic used for local-resolution assessment: `mean` or `median`. |
|
|
233
|
+
| `--maskingCrop` | off | Crop to the mask to accelerate local-resolution computation. |
|
|
234
|
+
|
|
235
|
+
### Auto-sigma
|
|
236
|
+
|
|
237
|
+
`--sigma` can be specified explicitly, or estimated automatically from the FSC between two half-maps (see [sigma_estimate](sigma_estimate.md)).
|
|
238
|
+
|
|
239
|
+
| Flag | Description |
|
|
240
|
+
|---|---|
|
|
241
|
+
| `--autoSigma` | Estimate `--sigma` automatically. Requires either `--map` + `--map2` pointing to two **different** half-map files, or `--bootstrap` (which generates an independent half-map pair on the fly), or `--autoSigmaInitialHalfMaps`. |
|
|
242
|
+
| `--autoSigmaInitialHalfMaps HALFM1 HALFM2` | Optional half-map pair used **only** for the initial auto-sigma estimate. If omitted, `--map` and `--map2` are used. Useful when the maps passed via `--map`/`--map2` are coupled (e.g. derived from the same reconstruction) and you want to seed the sigma estimate from an independent pair. |
|
|
243
|
+
| `--autoSigmaMask MASK` | Optional mask used **only** for the auto-sigma estimation. Use `none` (or omit) to compute sigma without a mask. |
|
|
244
|
+
|
|
245
|
+
### Iteration and optimisation
|
|
246
|
+
|
|
247
|
+
| Flag | Default | Description |
|
|
248
|
+
|---|---|---|
|
|
249
|
+
| `--bootstrap` | off | Randomise the half-map assignments at each iteration. Recommended when running with `--autoSigma` against a single combined map, and useful in general for robustness. |
|
|
250
|
+
| `--maxSelections` | `8` | Maximum number of selection iterations. Early termination kicks in if no improvement is observed for several consecutive iterations. |
|
|
251
|
+
| `--numRecs` | `10` | Number of sampling reconstructions per selection iteration. More samples explore the particle-count axis more finely but cost roughly proportionally more reconstructions. |
|
|
252
|
+
| `--numViews` | `350` | Number of Euler views used to partition the orientation sphere when ranking particles by SCI. Increase (e.g. to `1500`) for very large datasets with uniform angular coverage; decrease (e.g. to `100`) for small or strongly oriented datasets. Going below ~50 is discouraged. |
|
|
253
|
+
| `--aggressive` | off | Aggressively update the target particles from the current overview selection at each iteration. |
|
|
254
|
+
| `--samplingDensityFactor` | `0.5` | Sampling density factor for reconstruction sampling. |
|
|
255
|
+
| `--extraSamples_num` | `5` | Number of extra reconstruction samples used to escape local minima. |
|
|
256
|
+
|
|
257
|
+
### Runtime and backend
|
|
258
|
+
|
|
259
|
+
With `floorproduct`, an entirely floored Euler view has zero scores and uses
|
|
260
|
+
the existing zero-view ranking path. Compared with the former positive floor
|
|
261
|
+
minimum, this can change Euler-balanced ranks and selected identities even
|
|
262
|
+
for particles in other views whose scores are unchanged. Raw-score order
|
|
263
|
+
alone does not predict these effects.
|
|
264
|
+
|
|
265
|
+
| Flag | Default | Description |
|
|
266
|
+
|---|---|---|
|
|
267
|
+
| `--mpi` | `5` | Number of host CPU workers, also used for particle scoring when CPU is selected. Auto-capped to `cpu_count()` and to the particle count (see [About `--mpi`](#about--mpi)). |
|
|
268
|
+
| `--gpu` | `auto` | All visible CUDA devices at execution time, with logged CPU/MPI fallback. Use `none` to force CPU or `I,J` for ordered devices. Applies to scoring and, with `--noExternalPrograms`, internal reconstruction. Internal session local resolution uses CPU workers. |
|
|
269
|
+
| `--noExternalPrograms` | off | Generate a self-contained run script that avoids external software (RELION for reconstruction and local resolution). |
|
|
270
|
+
| `--particleSubtraction` | off | Declare that the input stack comes from particle subtraction. The STAR file should then contain a backup field linking to the unsubtracted particles. |
|