Pytme

Version 0.2.5 introduces analytical gradients for non-exhaustive scoring methods and adds support for complex template shapes in Fourier shift calculations.

**Enhancements**
- Cross-correlation-based scores in tme.matching_optimization were given a grad method to compute analytical gradients.
- tme.matching_data.fourier_padding supports computing shifts of complex-shaped templates.

**Documentation**
- Minor revision of code examples to reflect a change in test data packaging.

Version 0.2.4 addresses a critical bug, continues the deprecation process of tme.preprocessing, and includes various improvements and fixes. Users are strongly advised to update to this new version.

For users working with 0.2.3, the issue can be avoided by using `--pad_filter` with `match_template.py`. Alternatively, using the box size recommended by `postprocess.py` together with `--no_centering` can be used.

**Bug Fixes**
- Fixed a critical bug in `match_template.py` that caused wider cross-correlation peaks when using filters and templates not padded to the recommended shape by `preprocess.py` (4d0e01f50aa3ced49d24e67c5c6224aaf8eefbd6, Thanks to Min Zhang and 15 for reporting).
- Resolved a minor numerical inaccuracy when using weighted tilt masks (5d14e6b99b379e437db2e80d08c14fd902300087).
- Corrected a type error that occurred when using discrete bandpass filters on cupy backends (4d0e01f50aa3ced49d24e67c5c6224aaf8eefbd6).

**API/CLI Changes**
- Continued the deprecation of `tme.preprocessor` module and moved the implementation of wedge masks to `tme.preprocessing.tilt_series`.

**Enhancements**
- Restructured C extensions and tests to prevent potential circular imports when testing conda/pyenv installations (4d0e01f50aa3ced49d24e67c5c6224aaf8eefbd6).
- `postprocess.py` can automatically determine the ideal box size for a given backend.

Version 0.2.3 introduces quality-of-life improvements, fixes a range of outstanding issues, and more extensive documentation. Users are recommended to update to the new version.

**Enhancements**

- Relion star files can be created without extracting subtomograms (https://github.com/KosinskiLab/pyTME/issues/10).
- `preprocess.py` has more functionalities for template generation.

**API/CLI Changes**

- FFT padding was harmonized across backends, defaulting to `tme.backends.NumpyFFTWBackend`.
- `tme.preprocessing.WedgeReconstructed` returns a strictly binary mask if weighting is disabled.
- `match_template.py` can no longer perform threshold-based cropping of input data.

**Documentation**

- Deprecated quickstart in favor of a more extensive and structured user guide.

**Bug Fixes**

- `match_template.py` would create CTFs that did not factor in the spatial sampling rate, yielding incorrect CTFs. This has since been fixed and `tme.preprocessing.tilt_series.CTF` has been adapted accordingly to avoid such issues in the future (48eadf699b522d22269e22c6e825b2edebb10cd9).
- For certain data shape and parameter combinations (odd/even, fourier padding / edge padding), template matching results would be shifted by a single-voxel. This has been fixed in a79381535b6baf5c4dc26645260666a289277c3c.
- `tme.Density.from_file` would incorrectly extract the origin argument from CCP4/MRC files with non-standard MAPC, MAPS, MAPR configuration. This has been fixed in 2a2438b06e7990f2419c7b41e46d1b07218999aa.
- Using `tme.analyzer.PeakCallerMaximumFilter` with the pytorch backend would ignore peaks on the boundaries for certain min-distance requirements. This has been fixed in 531ff7710b4c3d852212cd000ceecfac516cd753.
- Fixed an issue where the pytorch backend would not be listed as available in c54ddefe73779588f9a9e05ead8d87f22f79d76f.

Version 0.2.2 introduces improvements to core functionality, new backends, and code refactoring.

**Enhancements**
- Exposed computation backend in `match_template.py`.
- Extended `match_template.py` to support n-dimensional matching (previously API-only).
- Added background correction feature to `postprocess.py`.
- Expanded GUI capabilities for manual matching refinement and target mask creation.
- Introduced new computation backends: MLX and Jax.

**API Changes**
- Deprecated `tme.helpers`; functions moved to `tme.Structure` and `tme.Preprocessor`.
- Replaced redundant functions in `tme.preprocessor` with the `tme.preprocessing` module.
- Updated shape expressions in `tme.matching_exhaustive` to use fundamental types instead of backend-specific arrays.
- Relocated scoring functions from `tme.matching_exhaustive` to `tme.matching_scores`.
- Refactored backends using metafunctions to reduce redundancy.

**Documentation**
- Updated `README.md` and made minor changes to overall documentation.

Version 0.2.1 introduces a range of new filters, improves interoperability, and addresses minor issues.

**Enhancements**
- match_template.py can perform 3D CTF correction.
- New reconstruction filters reducing artifact introdution.
- postprocess.py can oversample and locally refine peaks to subvoxel / sub angular sampling precision.
- Improved interoperability between dynamo, relion and pytme via tme.Orientations.

**API Changes**
- tme.Density.centered now pads to odd box shapes, which improves the stability of peak estimates.
- tme.MatchingData handles additional init parameters to avoid potentially unexpected interactions with setters.
- tme.backends data type naming scheme was changed to more accurately reflect the underlying fundamental data type.

**Documentation**
- Added code examples to Density / MatchingData / Exhaustive Matching and Orientations

**Bug Fixes**
- Fixed an issue where match_template.py would crash when specifying target_masks. This was caused by a specific interaction of the OS with the underlying memmap (Thanks to Xiaohan for reporting).
- Fixed an issue where postprocess.py would crash when specifying a minimum score cutoff. To avoid this moving forward, match_template.py and postprocess.py are now tested together with the API.
- Fixed an issue where tme.preprocessing._utils.fftfreqn would create grids of incorrect dimensions.
- skimage.io.imread raises a ValueError or OSError depending on the underlying OS when encountering an incorrect input. This would prevent users from running postprocess.py on atomic structures.
- Fixed an issue where bandpass filter creation would fail when only specifying lowpass or highpass cutoff.
- Fixed a performance issue when peak calling on GPU