BARNI¶

Intoduction¶

BARNI is a automatic radionuclide identification tool meant as a benchmark against commercial algorithms.

Installation¶

Prior to installation you will need Python3.6+ with additional packages. Anaconda is the recommended platform to install all the packages you need.

To instally BARNI you simply need to run the setup.py script:

python setup.py install --user

The “–user” option installs the package locally, which bipasses the need to be a computer administrator.

Quick Start¶

This quick start guide shows how to use BARNI python package for identification and training. Sample files can be found in examples directory.

Identification¶

Identification requires three files (1) peak analysis configuration file (2) feature extractor and (3) classifier. The first is a user configurable file that is easy to manipulate and requires only basic information about the sensor, such as the energy resolution. The other two files are created from the training routine.

import barni
import pickle
# load the inputs
spa = barni.loadXml("spa.xml")
featureExtractor = barni.loadXml("roi_flir.xml")
cls = barni.Classifier.load("classifiers_flir_bkg.pic")
# load the algorithm
algorithm = barni.IdentificationAlgorithm()
algorithm.setPeakExtractor(spa)
algorithm.setFeatureExtractor(featureExtractor)
algorithm.setClassifier(cls)
# perform identification
input = barni.loadXml("id_input.xml")
result = algorithm.identify(input)
# print the results
predictions = result.classifications.getPredictions()
print(predictions.toXml())

Training¶

The objective of the training is to produce the feature extractor and the classifier.

Command Line Interface¶

BARNI provides a command line interface for both identification [id] and training [train]. Sample file configuration files can be found in examples/ directory. Both routines require .yml formatted configuration files as positional argument. The following is printed withe the use of the [-h] flag:

usage: barni_cli.py [-h] [-i INPUT] [-o OUTPUT] [-p] {id,train} config

BARNI Command Line Interface

positional arguments:

{id,train} choice of either identify or training routine config yaml configuration file for identification or training

optional arguments:

`-h, --help`	show this help message and exit
`-i INPUT, --input INPUT`
	Barni identification input file
`-o OUTPUT, --output OUTPUT`
	Identification results output file
`-p, --plot`	Plot the results of identification

Identification¶

The identification configuration file contains references to serialized versions:

peakanalysis

feature_extractor

classifier

The first is meant to be manipulated by a user, and provides parameters for peak search and information about the sensor. The second and the third files are generated from the training routine.

The identification routine requires an input [-i], which should is a serialized IdentificationInput. The output [-o] is optional and by be default it is written to a id_results.xml file. The output file contains a list nuclide results which are also printed to the screen. The spectrum plot of the results can be provided with the optional [-p] flag.

Training¶

The training routine requires the training configuration file. The training routine produces two outputs required for identification the feature extractor (regions of interest) and classifier.

The training routine requires TemplateList for each nuclide of interest. A template file must exist for every nuclide specified in the confgiguration file. The templates directory, shown below, should contain a folder for each nuclide with the templates file inside. Both the directory and the file name are specified in the configuration file.

templates
 |-- Cs137
 |    |-- templates.xml.gz
 |-- Co60
      |-- templates.xml.gz

The build directory directory stores the output of each file. The tree-structure below is linked to the BARNI classes. Notice that both the classifier (training) and feature extractor routines (roi) produced samples and peaks which are saved under their respective folders for each nuclide.

build
|-- sources
|    |-- Cs137
|         |-- samples
|         |    |-- roi_samples.xml.gz
|         |    +-- training_samples.xml.gz
|         |-- peaks
|              |-- roi_peaks.xml.gz
|              +-- training_peaks.xml.gz
|
|-- roi.xml
|-- truth.csv.gz
|-- features.csv.gz
|-- classifiers.pic

The classification routine can optionally produce the feature and truth tables. These are stored in compressed comma seperated value filex feature.csv.gz and truth.csv.gz The results needed for identification in the example above are the roi.xml and classifiers.pic files.

Documentation¶

BARNI is documented using Numpy style docstrings and compiled using Sphinx. Documentation lives under the docs directory and can be comiled into HTML by invoking the Makefile:

make html

This creates the documentation under docs/_build/html/index.html.

Developing¶

Please feel free to contribute any tool or module addition you may deem useful. Remember, any code will be read more times than it is written so readability counts. Make sure to supplement your code with adaquate examples to make it user-friendly. Any code you write should be self-explenatory and not require additional interaction with future users.

We generally follow the PEP 8 styleguide, with a few exceptions (like indentation spacing). The important things to keep in mind are:

Use 4 spaces for indentation
Limit lines to a maximum of 80 characters
Use blank lines sparingly
Avoid trailing white space
Use inline comments sparingly
Naming conventions to follow: - Module namse should be lowercase - Class names use the CapWords (aka CamelCase) convention - Function names are all lowercase, with underscores if necessary - Variables should be lowercase except module level constants

Reference¶

The exact API of all functions and classes, as given by the docstrings. The API documents expected types and allowed features for all functions, and all parameters available for the algorithms.

`barni._architecture`
`barni._id`
`barni._bins`
`barni._peak`
`barni._fe`
`barni._class`
`barni._math`
`barni._label`
`barni._plot`
`barni._reader`
`barni._roi`
`barni._sensor`
`barni._smoothing`
`barni._spa`
`barni._spectrum`
`barni._training`