Metadata-Version: 2.4
Name: autolei
Version: 1.0.6.260819
Summary: A GUI for electron diffraction data analysis
License: BSD-3-Clause
License-File: LICENSE
Keywords: electron-diffraction,XDS,microed,data-analysis,automation,crystallography
Author: Lei Wang
Author-email: lei.wang@su.se
Requires-Python: >=3.9,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Dist: PyQt5 (>=5.15.0)
Requires-Dist: fabio (>=0.14.0)
Requires-Dist: h5py (>=3.1.0)
Requires-Dist: hdf5plugin (>=3.3.1)
Requires-Dist: matplotlib (>=3.3.4,<3.12)
Requires-Dist: mplcursors (>=0.5.1)
Requires-Dist: mrcfile (>=1.5.0)
Requires-Dist: numpy (>=1.19.5)
Requires-Dist: openpyxl (>=3.0.0)
Requires-Dist: packaging (>=21.0)
Requires-Dist: pandas (>=1.1.5)
Requires-Dist: pillow (>=8.0.0)
Requires-Dist: plotly (>=5.0.0)
Requires-Dist: scikit-image (>=0.18.0)
Requires-Dist: scipy (>=1.5.4)
Requires-Dist: spglib (>=1.9.0)
Requires-Dist: tqdm (>=4.46.1)
Project-URL: Bug Reports, https://gitlab.com/tristonewang/autolei/issues
Project-URL: Documentation, https://gitlab.com/tristonewang/autolei/-/wikis/home
Project-URL: Homepage, https://gitlab.com/tristonewang/autolei
Project-URL: Repository, https://gitlab.com/tristonewang/autolei
Description-Content-Type: text/markdown

# AutoLEI

**AutoLEI: Automated Real-time and Offline Batch 3D ED/MicroED Data Processing Graphic User Interface** is an XDS-based GUI designed for real-time and batch processing of MicroED/3DED datasets. It provides a user-friendly platform for rapid, automated data processing and merging of multiple MicroED datasets, with well-designed and significantly streamlining structure determination workflows.

**Key Features**

- **User-Friendly Interface**: Simplifies MicroED data processing, requiring minimal manual input.
- **Batch Processing**: Handles large numbers of datasets with automated workflows.
- **Real-Time Data Processing**: Provides live feedback during data collection.
- **Versatility**: Supports diverse samples, including small molecules and proteins workflow.

---

## Installation

### Requirements

- **Operating Systems**: Linux or Windows via [WSL](https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux) (versions
  1/2).
- **Software Dependencies**:
    - Python 3.9+ with libraries specified in `pyproject.toml`.
    - [XDS](https://xds.mr.mpg.de/) and [XDSGUI](https://wiki.uni-konstanz.de/xds/index.php/XDSGUI).
    - Optional tools: `xprep` for advanced features and LibreOffice for `.xlsx` files in Linux.

### Steps

1. Install via pip:
   ```bash
   pip install autolei
   ```
   For a specific historical version, use:
   ```bash
   pip install "autolei==<version>"
   ```
2. For a managed Linux/WSL installation including required XDS and optional XDSGUI tooling, use the
   reviewed installer from a source checkout:
   ```bash
   bash install_script/linux.sh
   ```
3. Manual installation:
   Follow the steps in the [Tutorial for AutoLEI](doc/AutoLEI_Tutorial.pdf)
   and [our Wiki](https://gitlab.com/tristonewang/autolei/-/wikis/home).

---

## Usage

### Command-line Usage

- **Launch the GUI**:
   ```bash
   autolei
   ```
   The equivalent module command is `python -m autolei`.
  > *Note*: The first launch may take slightly longer as dependencies initialize.

- **Configure Settings**:
   ```bash
   autolei-setting
   ```
  Use `autolei-setting --path` to print the writable per-user settings path.

- **Import Instrument**:
   ```bash
   autolei-add-instrument instrument_setting_file
   ```
Custom profiles are stored in the user data directory and survive package upgrades.

- **Restore an XDS cleanup backup**:
   ```bash
   autolei-restore-cleanup project/.autolei-trash/xds-<timestamp>-<id>
   ```

- **Check External Tools**:
   ```bash
   autolei-doctor
   ```
  Reports the resolved locations of required and optional XDS/SHELX tools.

- **Run without the GUI**:
   ```bash
   autolei-process xds-generate PROJECT --settings PROJECT/Input_parameters.txt
   autolei-process xds-run PROJECT
   autolei-process --json convert PROJECT mrc
   ```
  The command also provides `cluster`, `merge`, `geometry`, and `shelx`
  workflows. See [Headless workflows](doc/Headless_Workflows.md) for validation,
  cancellation, and Python API examples.

### Configuration and provenance

AutoLEI creates `setting.ini` in the platform-specific user configuration
directory when it first starts. Packaged settings and instrument profiles remain
read-only defaults. To run with a separate configuration, set `AUTOLEI_SETTINGS`
to another INI file. `AUTOLEI_CONFIG_HOME` and `AUTOLEI_DATA_HOME` can override
the user directories for managed installations and tests. Missing options retain
documented defaults, while invalid values produce a setting-specific error.

AutoLEI 1.0.x supports Python 3.9 through 3.14 and tests every supported minor
version. Python 3.9 is retained only for compatibility in the 1.0 release line;
the next minor release is planned to require Python 3.11 or newer.

When upgrading from AutoLEI 1.0.5 or older, the managed installer copies a
package-local `setting.ini` and custom-named profiles before pip replaces the old
installation. Users upgrading directly with pip should back up any files they
previously edited inside `site-packages/autolei` first.

Batch and refinement runs write `xdsrunner.provenance.json` or
`xdsrunner2.provenance.json` next to the Excel result. The manifest records the
AutoLEI and Python versions, effective configuration and its SHA-256 fingerprint,
XDS executable location, run parameters, and SHA-256 hashes of all `XDS.INP`
files used by the run.

### GUI pages

AutoLEI is organised into multiple working pages:

- **Input**: Configure experiment parameters and generate input files.
- **XDSRunner**: Automate initial processing and data quality inspection.
- **CellCorr**: Update unit cell information and refine settings.
- **XDSRefine**: Fine-tune processing parameters, including rotation axis and scaling.
- **DataMerge**: Filter and merge datasets for downstream analysis.
- **Cluster&Output**: Perform clustering and generate outputs for structure determination.
- **Expert**: Miscellaneous tools for data reduction and PETS related function.
- **RealTime**: Live data processing with real-time feedback and automatic merging.

### Package layout

- `autolei/app/`: PyQt application entry point, pages, realtime processing, and expert tools.
- `autolei/core/`: Validated settings, package version handling, and run provenance.
- `autolei/src/`: Scientific processing and file-format implementation modules.
- `autolei/workflows/`: Headless XDS, image, geometry, clustering, merging, and
  SHELX services shared by the GUI, CLI, and tests.
- `autolei/autolei.py`: Small compatibility launcher for existing direct-file commands.

---

## Documentation

Detailed guides and examples can be found in:

- [Tutorial for AutoLEI](doc/AutoLEI_Tutorial.pdf)
- [Development roadmap](doc/ROADMAP.md)
- [Our Wiki](https://gitlab.com/tristonewang/autolei/-/wikis/home)

---

## Authors and Acknowledgments

Developed by Lei Wang and Yinlin Chen. Contributions from Gerhard Hofer, Hongyi Xu, and Xiaodong Zou at Stockholm
University. The project integrates valuable resources from [edtools](https://github.com/instamatic-dev/edtools). Special
thanks to the [XDS](https://xds.mr.mpg.de/) team for their support and resources.

---

## Licence

The software is licensed under the BSD 3-Clause Licence.

