Package: pept
ThepeptLibraryA Python library that integrates all the tools necessary to perform research using Positron Emission Particle Tracking (PEPT). It includes algorithms for the location, identification and tracking of particles, in addition to tools for visualisation and analysis, and utilities allowing the realistic simulation of PEPT data.Positron Emission Particle TrackingPEPT is a technique developed at the University of Birmingham which allows the non-invasive, three-dimensional tracking of one or more 'tracer' particles through particulate, fluid or multiphase systems. The technique allows particle or fluid motion to be tracked with sub-millimetre accuracy and sub-millisecond temporal resolution and, due to its use of highly-penetrating 511keV gamma rays, can be used to probe the internal dynamics of even large, dense, optically opaque systems - making it ideal for industrial as well as scientific applications.PEPT is performed by radioactively labelling a particle with a positron-emitting radioisotope such as fluorine-18 (18F) or gallium-66 (66Ga), and using the back-to-back gamma rays produced by electron-positron annihilation events in and around the tracer to triangulate its spatial position. Each detected gamma ray represents a line of response (LoR).Transforming gamma rays, or lines of response (left) into individual tracer trajectories (right) using the `pept` library. Depicted is experimental data of two tracers rotating at 42 RPM, imaged using the University of Birmingham Positron Imaging Centre's parallel screens PEPT camera.Getting StartedThese instructions will help you get started with PEPT data analysis.PrerequisitesThis package supports Python 3.7 and above - it is built and tested for Python 3.7, 3.8 and 3.9 on Windows, Linux and macOS (thanks toconda-forge, which is awesome!).You can install it using the batteries-includedAnaconda distributionor the bare-bonesPython interpreter. You can also check out our Python andpepttutorialshere.InstallationThe easiest and quickest installation, if you are using Anaconda:conda install -c conda-forge peptYou can also install the latest release version ofpeptfrom PyPI:pip install --upgrade peptOr you can install the development version from the GitHub repository:pip install --upgrade git+https://github.com/uob-positron-imaging-centre/peptTutorialsSome PEPT analysis example scripts are available onpept.readthedocs.io. A minimal script can read PEPT from an online location (e.g. the experiment shown above - two radioactive tracers rotating at 42 RPM), transform the lines of response into accurate tracer locations and plot them in a browser-based interactive 3D graph (live version availablehere):A more complete PEPT analysis script can track multiple tracers at the same time, produce "tight", separate trajectories and create multiple interactive Plotly subplots that are opened in a webpage (example live graphhere). The resulting trajectories can then be post-processed to extract system-specific data - e.g. residence time distributions.You can download some PEPT data samples from theUoB Positron Imaging Centre's Repository:$> git clone https://github.com/uob-positron-imaging-centre/example_dataDocumentationAn absurd amount of time was spent making sure thaneveryfunction and class in thepeptlibrary is well-documented (and most have examples) and all code is explained through comments - no dragons shall be dwelling in thepeptsource code. The library API / reference can be foundhere- including a search function for quickly finding what you need.A very fast-paced introduction to Python is availablehere; it is aimed at engineers whose background might be a few lines written MATLAB, as well as moderate C/C++ programmers.A beginner-friendly tutorial for using thepeptpackage is availablehere.The links above point to Google Colaboratory, a Jupyter notebook-hosting website that lets you combine text with Python code, executing it on Google servers. Pretty neat, isn't it?Library ArchitectureThe main purpose of thepeptlibrary is to provide a common, consistent foundation for PEPT-related algorithms, including tracer tracking, visualisation and post-processing tools - such that they can be used interchangeably, mixed and matched for different systems. VirtuallyanyPEPT processing routine follows these steps:Convert raw gamma camera / scanner data into3D lines(i.e. the captured gamma rays, or lines of response - LoRs).Take asampleof lines, locate tracer locations, then repeat for the next samples.Separate out individual tracer trajectories.Visualise and post-process trajectories.For these algorithm-agnostic steps,peptprovides five base data structures upon which the rest of the library is built:pept.LineData: general 3D line samples, formatted as[time, x1, y1, z1, x2, y2, z2, extra...].pept.PointData: general 3D point samples, formatted as[time, x, y, z, extra...].pept.Pixels: single 2D pixellised space with physical dimensions, including fast line traversal.pept.Voxels: single 3D voxellised space with physical dimensions, including fast line traversal.All the data structures above are built on top of NumPy and integrate natively with the rest of the Python / SciPy ecosystem. The rest of thepeptlibrary is organised into submodules:pept.scanners: converters between native scanner data and the base classes.pept.tracking: radioactive tracer tracking algorithms, e.g. the Birmingham method, PEPT-ML, FPI.pept.plots: PEPT data visualisation subroutines.pept.utilities: general-purpose helpers, e.g.read_csv,traverse3d.pept.processing: PEPT-oriented post-processing algorithms, e.g.occupancy2d.PerformanceSignificant effort has been put into making the algorithms in this package as fast as possible. The most computionally-intensive parts have been implemented inC/Cythonand parallelised usingjoblibandconcurrent.futures.ThreadPoolExecutor. For example, using thepeptmlsubpackage, analysing 1,000,000 LoRs on the author's machine (mid 2012 MacBook Pro) takes about 26 s.The tracking algorithms inpept.trackingsuccessfully scaled up to hundreds of processors on BlueBEAR, the University of Birmingham's awesomesupercomputer.Help and SupportWe recommend you check outour tutorials. If your issue is not suitably resolved there, please check theissuespage on our GitHub. Finally, if no solution is available there, feel free toopen an issue; the authors will attempt to respond as soon as possible.ContributingThepeptlibrary is not a one-man project; it is being built, improved and extended continuously (directly or indirectly) by an international team of researchers of diverse backgrounds - including programmers, mathematicians and chemical / mechanical / nuclear engineers. Want to contribute and become a PEPTspert yourself? Great, join the team!There are multiple ways to help:Open an issuementioning any improvement you thinkpeptcould benefit from.Write a tutorial or share scripts you've developed that we can add to thepeptdocumentationto help other people in the future.Share your PEPT-related algorithms - tracking, post-processing, visualisation, anything really! - so everybody can benefit from them.Want to be a superhero and contribute code directly to the library itself? Grand - fork the project, add your code and submit a pull request (if that sounds like gibberish but you're an eager programmer, checkthis article). We are more than happy to work with you on integrating your code into the library and, if helpful, we can schedule a screen-to-screen meeting for a more in-depth discussion about thepeptpackage architecture.Naturally, anything you contribute to the library will respect your authorship - protected by the strong GPL v3.0 open-source license (see the "Licensing" section below). If you include published work, please add a pointer to your publication in the code documentation.CitingIf you used this codebase or any software making use of it in a scientific publication, we ask you to cite the following paper:Nicuşan AL, Windows-Yule CR. Positron emission particle tracking using machine learning. Review of Scientific Instruments. 2020 Jan 1;91(1):013329.Aspeptis a project bringing together the expertise of many people, it hosts multiple algorithms that were developed and published in other papers. Please check the documentation of thepeptalgorithms you are using in your research and cite the original papers mentioned accordingly.ReferencesPapers presenting PEPT algorithms included in this library:[1] Parker DJ, Broadbent CJ, Fowles P, Hawkesworth MR, McNeil P. Positron emission particle tracking-a technique for studying flow within engineering equipment. Nuclear Instruments and Methods in Physics Research Section A: Accelerators, Spectrometers, Detectors and Associated Equipment. 1993 Mar 10;326(3):592-607.[2] Nicuşan AL, Windows-Yule CR. Positron emission particle tracking using machine learning. Review of Scientific Instruments. 2020 Jan 1;91(1):013329.[3] Wiggins C, Santos R, Ruggles A. A feature point identification method for positron emission particle tracking with multiple tracers. Nuclear Instruments and Methods in Physics Research Section A: Accelerators, Spectrometers, Detectors and Associated Equipment. 2017 Jan 21;843:22-8.LicensingThepeptpackage isGPL v3.0licensed. In non-lawyer terms, the key points of this license are:You can view, use, copy and modify this codefreely.Your modifications mustalsobe licensed with GPL v3.0 or later.If you share your modifications with someone, you have to include the source code as well.Essentially do whatever you want with the code, but don't try selling it saying it's yours :). This is a community-driven project building upon many other wonderful open-source projects (NumPy, Plotly, even Python itself!) without whichpeptsimply would not have been possible. GPL v3.0 is indeed a very strongcopyleftlicense; it was deliberately chosen to maintain the openness and transparency of great software and progress, and respect the researchers pushing PEPT forward. Frankly, open collaboration is way more efficient than closed, for-profit competition.Copyright (C) 2021 thepeptdevelopers. Until now, this library was built directly or indirectly through the brain-time of:Andrei Leonard Nicusan (University of Birmingham)Dr. Kit Windows-Yule (University of Birmingham)Dr. Sam Manger (University of Birmingham)Matthew Herald (University of Birmingham)Chris Jones (University of Birmingham)Mark Al-Shemmeri (University of Birmingham)Prof. David Parker (University of Birmingham)Dr. Antoine Renaud (University of Edinburgh)Dr. Cody Wiggins (Virginia Commonwealth University)Dawid Michał HampelDr. Tom Leadbeater