Welcome to TEMUL Toolkit’s documentation!

The TEMUL Toolkit is a suit of functions and classes for analysis and visualisation of atomic resolution images. It is mostly built upon the data structure of HyperSpy and Atomap.

Interactive Examples


Click the button above to start some data analysis (it may take a few minutes to load). The “code_tutorials” folder contains walkthroughs of some of the documentation examples from this website. The “publication_examples” folder will allow you to analyse data from published scientific papers! Just navigate to whichever of these folders you want click on the “.ipynb” files.


16/02/2021: Version 0.1.3 released

First articles uses and citations for the TEMUL Toolkit! This version updated the Publication Examples folder with two newly published articles. The folder contains interactive and raw code on how to reproduce the data in the publications. Congrats to those involved!

If you have a question or issue with using the publication examples, please make an issue on GitHub.

Code changes in this version:
  • The atom_deviation_from_straight_line_fit function has been corrected and expanded. For a use case, see Finding Polarisation Vectors
  • Corrected the plot_polarisation_vectors function’s vector quiver key.
  • Created the “polar_colorwheel” plot_style for plot_polarisation_vectors by using a HSV to RGB 2D colorwheel and mapping the angles and magnitudes to these values. Used code from PixStem for colorwheel visualisation.
  • Fixed norm and cmap scaling for the colorbar for the “contour”, “colorwheel” and “colormap” plot_styles. Now each of these plot_styles scale nicely, and colorbar ticks may be specified.
  • Added invert_y_axis param for plot_polarisation_vectors function, useful for testing if angles are displaying correctly.
  • plot_polarisation_vectors function now returns a Matplotlib Axes object, which can be used to further edit the layout/presentation of the plotted map.
  • Added functions to correct for possible off-zone tilt in the atomic columns. Use with caution.
Documentation changes in this version:

03/11/2020: Version 0.1.2 released

This version contains minor changes from the 0.1.1 release. It removes pyCifRW as a dependency.

02/11/2020: Version 0.1.1 released

This version contains many changes to the TEMUL Toolkit.

  • More parameters have been added to the polarisation module’s plot_polarisation_vectors function. Check out the walkthrough here for more info!
  • Interactive double Gaussian filtering with the visualise_dg_filter function in the signal_processing module. Thanks to Michael Hennessy for the help!
  • The calculate_atom_plane_curvature function has been added, creating the lattice_structure_tools module.
  • Strain, rotation, and c/a mapping can now be done here.
  • Masked FFT filtering to obtain iFFTs. See this guide to see some code!
  • Example walk-throughs for many features of the TEMUL Toolkit are now on this website! Check out the menu on the left to get started!


The TEMUL Toolkit can be installed easily with PIP (those using Windows may need to download VS C++ Build Tools, see below).

$ pip install temul-toolkit

Then, it can be imported with the name “temul”. For example, to import most of the temul functionality use:

import temul.api as tml

Matplotlib 3.3 currently has compatability issues with iPython, see below for the fix.

  • If installing on Windows, you will need Visual Studio C++ Build Tools. Download it here. After downloading, choose the “C++ Build Tools” Workload and click install.

  • Matplotlib seems to have issues with iPython at the moment. Install matplotlib==3.2 until this issue is resolved by Matplotlib. See here for more details.

  • If you want to use the io.write_cif_from_dataframe function, you will need to install pyCifRW version 4.3. This requires Visual Studio.

  • If you wish to use the simulations.py or model_refiner.py modules, you will need to install PyPrismatic. This requires Visual Studio and other dependencies.

  • If you’re using any of the functions or classes that require element quantification:

    • navigate to the “temul/external” directory, copy the “atomap_devel_012” folder and paste that in your “site-packages” directory.
    • Then, when using atomap to create sublattices and quantify elements call atomap like this: import atomap_devel_012.api as am.
    • This development version is slowly being folded into the master branch here: https://gitlab.com/atomap/atomap/-/issues/93 and any help or tips on implementation are welcome!

Getting started

There are many aspects to the TEMUL Toolkit, such as polarisation analysis, element quantification, and automatic image simulation (through pyprismatic).

Checkout the tutorials in the table of contents above or on the left of the page. One can also view the extensive documentation, where each function is described and examples of their use given.

Code Documentation

See the API documentation for examples and a full list of modules and functions.


To cite the latest TEMUL Toolkit version, use the following DOI:


For example: Eoghan O’Connell, Michael Hennessy, & Eoin Moynihan. (2020, November 2). PinkShnack/TEMUL: Initial Temul-Toolkit Release (Version 0.1.1). Zenodo. http://doi.org/10.5281/zenodo.4185974

If you wish to cite an older release of the TEMUL Toolkit, click on the above badge to find the relevant version.


If you are having issues, please let us know in the issue tracker on GitHub.


The project is licensed under the GPL-3.0 License.

Indices and tables