Skip to content

Latest commit

 

History

History
161 lines (114 loc) · 6.54 KB

README.md

File metadata and controls

161 lines (114 loc) · 6.54 KB
Raw

pydidas

zenodo badge

pydidas (the Python DIffraction Data Analysis Suite) is a toolkit for the analysis of diffraction datasets, both live at beamlines and offline for in-depth analysis.

Pydidas includes a graphical user interface and a command line interface to embed its functionality in other projects or scripts.

Pydidas relies on Qt for the user interface and for internal communication. Some widgets are extensions of silx widgets. The (azimuthal/radial) integration uses the pyFAI engine for fast azimuthal integration. Both pyFAI and silx are developed at the ESRF.

References

  • Please check the citation file CITATION.cff
  • Pydidas has also been issued with a global DOI for citations: 10.5281/zenodo.7568610
    zenodo badge

Installation

Pydidas should be installed in a clean environment to allow pydidas to fix the required dependency versions. This environment should be used exclusively for pydidas and no further packages should be installed.

Pydidas requires a Python version >= 3.11.

Preparing the environment

Environments can be managed using any environment manager (e.g. venv, conda/mamba). Due to dependency management issues, pydidas does not support pre-configured conda/mamba environments any more but relies exclusively on pip for the dependency management.

Pip will install all dependencies together with the pydidas package. There is no need to prepare the environment further.

Building and installing pydidas

You will require a pydidas wheel file to install it using pip. If you have not downloaded a build wheel file, you need to prepare one prior to installation.

Using a python wheel

Wheels for pydidas are available on the pydidas releases webpage. To install a downloaded wheel, activate your chosen environment and use the following command:

python -m pip install <path_to_pydidas_wheel_file.whl>

Using the source code directly

Download the pydidas source code or clone the git repository and navigate to the folder with the project metadata files (like this README.md). Then, install the package and any missing dependencies:

python -m pip install .

Note that pip might need to build a wheel from pydidas first which will take some time. If you want to build the wheel manually, for example to keep it for later use, simply use the following commands (again, in the pydidas folder)::

python -m build

This will create a tarball and a wheel file in the dist subdirectory.

Note: You will need to install the build and setuptools packages manually in your chosen environment if you want to build pydidas from source.

Using pydidas

Entry points

If installed as wheel, pydidas offers the following entry points:

  • pydidas-gui to start the graphical user interface.
  • pydidas-documentation to open the pydidas documentation in the default system web browser. Note: The pydidas module must have been run at least once (either through opening the GUI or imported in a python shell) for the documentation to have been created.
  • pydidas-clear-settings Remove the stored registry keys for pydidas.
  • pydidas-updater Start a script which automatically updates pydidas to the latest version available on GitHub.
  • pydidas-remove-local-files This script removes all local log files and stored configuration files.
  • run-pydidas-workflow Script to run a defined workflow in the console. This script also requires configuration files for the scan and diffraction experiment. Please refer to the full documentation for more details.
  • remove-pydidas Remove all local config files and registry settings from the system. Please note that this script will not remove the python code itself, but only cleans up the system.

Scripts

Pydidas includes multiple scripts which are located in the pydidas_scripts folder. These can be called directly by python from the command line and they are:

  • pydidas_gui.py to start the GUI.
  • pydidas_documentation.py to open the html documentation in a browser.
  • run_pydidas_workflow.py to run a processing workflow on the command line.
  • pydidas_updater_script.py to update pydidas to the latest release published on GitHub.
  • clear_local_settings.py to remove all registry settings written by pydidas.

Command line

Much of pydidas' functionality is also available from the command line or notebooks. Pydidas can be imported and used as any other python module. Please refer to the documentation for more details (see the entrypoint and script for opening the documentation above).

Documentation

Local documentation

The documentation is included with the distribution, but only in form of the source to keep the distribution small. It will be compiled automatically the first time pydidas is imported in python. This will take some time (about 30 seconds, depending on the system) and a notification will be displayed.

The compiled documentation can be found in the lib/site-packages/pydidas/sphinx/html folder and the index.html file is the global start page.

A pydidas-documentation entrypoint is available to open the documentation in the system's default browser. The graphical user interface also has a menu entry to open the help in a web browser.

Online documentation

The pydidas documentation is also available online through github-pages: https://hereon-gems.github.io/pydidas/

Referencing pydidas

For the full citation information of pydidas, please see the CITATION.cff file.

Pydidas can also be cited by its global DOI on zenodo: 10.5281/zenodo.7568610
zenodo badge

License

The pydidas source code is released under the GNU General Public License Version 3. The documentation is licensed under the Creative Commons Attribution 4.0 International Public License (CC-BY-4.0). Images and logos are licensed under Creative Commons Attribution-NoDerivatives 4.0 International Public License (CC-BY-ND-4.0). Insignificant files (e.g. changelog) are released under the CC0 1.0 Universal Public Domain Dedication (CC0-1.0).