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.
The easiest way to try the TEMUL Toolkit is via Binder: introductory Jupyter Notebook. To install the TEMUL Toolkit on your own computer, see the Installation instructions.
And there are more examples with Binder, just click the below button!
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.
Some published results using the TEMUL Toolkit¶
16/02/2021: Version 0.1.4 released¶
The polarisation, structure tools and fft mapping has now been refactored into the topotem module. The temul functionality remains the same i.e. ``import temul.api as tml`.
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:
atom_deviation_from_straight_line_fitfunction has been corrected and expanded. For a use case, see Finding Polarisation Vectors
- Corrected the
plot_polarisation_vectorsfunction’s vector quiver key.
- Created the “polar_colorwheel”
plot_polarisation_vectorsby using a HSV to RGB 2D colorwheel and mapping the angles and magnitudes to these values. Used code from PixStem for colorwheel visualisation.
cmapscaling for the colorbar for the “contour”, “colorwheel” and “colormap”
plot_styles. Now each of these
plot_stylesscale nicely, and colorbar
ticksmay be specified.
- Added invert_y_axis param for plot_polarisation_vectors function, useful for testing if angles are displaying correctly.
plot_polarisation_vectorsfunction now returns a Matplotlib
Axesobject, 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:
- Added documentation for how to find the polarisation vectors.
- Added “code_tutorials” ipynb (interactive Jupyter Notebook) examples. See the GitHub repository for downloads.
- The workflows folder in “code_tutorials/workflows” also contains starting workflows for analysis of different materials. See the GitHub repository for downloads.
- Added “publication_examples” tutorial ipynb (interactive Jupyter Notebook) examples. See the GitHub repository for downloads.
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_vectorsfunction. Check out the walkthrough here for more info!
- Interactive double Gaussian filtering with the
visualise_dg_filterfunction in the signal_processing module. Thanks to Michael Hennessy for the help!
calculate_atom_plane_curvaturefunction 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!
- Getting started
- Analysis Workflows
- Finding Polarisation Vectors
- Plotting Polarisation and Movement Vectors
- Plot Lattice Structure Maps
- Calculation of Atom Plane Curvature
- Analysis of PTO Domain Wall Junction
- Masked FFT and iFFT
- Line Intensity Profile Comparisons
- Interactive Image Filtering
- API documentation
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
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.
If you want to use the
temul.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
temul.model_refinermodules, you will need to install PyPrismatic. This requires Visual Studio and other dependencies. It is unfortunately not guaranteed to work. If you want to help develop the
temul.model_refiner.Model_Refiner, please create an issue and/or a pull request on the TEMUL github.
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!
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.
To use the vast majority of the temul functionality, import it from the api module:
import temul.api as tml
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. (2021). PinkShnack/TEMUL: (Version 0.1.3). Zenodo. http://doi.org/10.5281/zenodo.4543963
If you wish to cite an older release of the TEMUL Toolkit, click on the above badge to find the relevant version.
The project is licensed under the GPL-3.0 License.