Belle II Software  release-08-01-10
NNWaveFitter Class Reference

The class uses a neural network to find a probability distribution of arrival times for a sextet of APX25 signal samples. More...

#include <NNWaveFitter.h>

Collaboration diagram for NNWaveFitter:

Public Types

typedef std::pair< double, double > nnBoundsType
 Bounds type used to hold network parameter bounds used in training the network. More...
 

Public Member Functions

 NNWaveFitter (std::string xmlData="")
 Constructor constructs the wavefitter from data in xml file. More...
 
void setNetwrok (const std::string &xmlData)
 Set proper network definition file. More...
 
std::shared_ptr< nnFitterBinDatagetFit (const apvSamples &samples, double tau)
 Fitting method Send data and get rseult structure. More...
 
const NNWaveFitToolgetFitTool () const
 Get a handle to a NNWaveFit object. More...
 
const nnFitterBinDatagetBinCenters () const
 Get bin times of the network output. More...
 
const nnFitterBinsgetBins () const
 Get bins of netwrok output. More...
 
nnBoundsType getWaveWidthBounds () const
 Get width bounds Width bounds are minimum and maximum width used in training the network. More...
 
nnBoundsType getAmplitudeBounds () const
 Get amplitude bounds. More...
 
nnBoundsType getTimeShiftBounds () const
 Get time shift bounds. More...
 
bool isValid () const
 Is this fitter working? Return false if the fitter was not initialized properly.
 
bool checkCoefficients (const std::string &dumpname, double tol=1.0e-10)
 Check NN data against a dump from Python. More...
 

Private Types

typedef std::function< double(double)> activationType
 Activation functions type.
 
typedef std::map< size_t, std::pair< Eigen::MatrixXd, Eigen::VectorXd > > networkWeightsType
 We use map to store network layers since we don't know if we'll be reading them in correct order.
 
typedef std::vector< Eigen::VectorXd > layerStatesType
 Storage for internal states.
 

Private Member Functions

Eigen::VectorXd softmax (const Eigen::VectorXd &input)
 Softmax function, normalization for the network's output layer. More...
 
int readNetworkData (const std::string &xmlFileName)
 The method that actually reads the xml file. More...
 

Private Attributes

activationType relu
 Rectifier activation. More...
 
activationType sigmoid
 Sigmoid activation. More...
 
bool m_isValid
 true if fitter was properly initialized
 
std::size_t m_nLayers
 number of NN layers, read from xml
 
nnFitterBinData m_binCenters
 centers of NN time bins
 
nnFitterBins m_bins
 NN time bin boundaries.
 
layerStatesType m_layerStates
 vectors of layer states
 
std::vector< std::size_t > m_layerSizes
 NN layer sizes.
 
networkWeightsType m_networkCoefs
 NN weights and intercepts.
 
activationType m_activation
 Network activation function.
 
nnBoundsType m_amplitudeBounds
 Amplitude range of the network.
 
nnBoundsType m_waveWidthBounds
 Waveform width range of the network.
 
nnBoundsType m_timeShiftBounds
 Time shift range of the network.
 
TauEncoder m_tauCoder
 Tau encoder class instance to scale tau values.
 
WaveformShape m_wave
 Wave function used in training the network.
 
std::shared_ptr< NNWaveFitToolm_fitTool
 FitterTool object allowing calculations on network fits.
 

Detailed Description

The class uses a neural network to find a probability distribution of arrival times for a sextet of APX25 signal samples.

The input to the network are sample S/N ratios, i.e., we expect \sigma^2 = 1, plus width of the waveform from calibration data. The network(s) is currently trained using Python's scikit-learn package and results are saved in a PMML-like xml file. The NNWaveFitter reads the contents of this xml and on request provides the following data to the calling routine:

  1. Signal's arrival time estimate and its error,
  2. Signal's amplitude and its error,
  3. chi2 of the fit
  4. (Binned) probability distribution for arrival time.

The network is a multiclass classifier and the time bin probabilities are its main output. Time and amplitude are calculated from this distribution. The probability distribution is useful by itself in background suppression and u/v hit pairing.

The input xml file has, with a few extensions, the official PMML format (http://dmg.org), which can be created and read by most machine learning libraries.

The fitter generates a NNWaveFit object to aid in computations with bin probabilities, such as shifting, multiplication, calculations of time shift, amplitude and their errors.

Definition at line 61 of file NNWaveFitter.h.

Member Typedef Documentation

◆ nnBoundsType

typedef std::pair<double, double> nnBoundsType

Bounds type used to hold network parameter bounds used in training the network.

Also, this is the range guaranteed network applicability.

Definition at line 70 of file NNWaveFitter.h.

Constructor & Destructor Documentation

◆ NNWaveFitter()

NNWaveFitter ( std::string  xmlData = "")

Constructor constructs the wavefitter from data in xml file.

Parameters
xmlDatastring containing the network definition xml tree

Definition at line 260 of file NNWaveFitter.cc.

261 {
263  if (xmlData != "") setNetwrok(xmlData);
264 }
void setNetwrok(const std::string &xmlData)
Set proper network definition file.
WaveformShape m_wave
Wave function used in training the network.
Definition: NNWaveFitter.h:192
double w_betaprime(double t)
Beta-prime waveform shape, x^alpha/(1+x)^beta.

Member Function Documentation

◆ checkCoefficients()

bool checkCoefficients ( const std::string &  dumpname,
double  tol = 1.0e-10 
)

Check NN data against a dump from Python.

Parameters
dumpnameFilename of a text dump of network coefficients.
tolTolerance for float comparisons
Returns
true if all comparisons pass.

Definition at line 192 of file NNWaveFitter.cc.

◆ getAmplitudeBounds()

nnBoundsType getAmplitudeBounds ( ) const
inline

Get amplitude bounds.

Returns
std::pair of amplitude bounds used in simulation

Definition at line 121 of file NNWaveFitter.h.

121 { return m_amplitudeBounds; }
nnBoundsType m_amplitudeBounds
Amplitude range of the network.
Definition: NNWaveFitter.h:188

◆ getBinCenters()

const nnFitterBinData& getBinCenters ( ) const
inline

Get bin times of the network output.

Returns
array of mean bin times (averaged over training data), properly sorted.

Definition at line 104 of file NNWaveFitter.h.

◆ getBins()

const nnFitterBins& getBins ( ) const
inline

Get bins of netwrok output.

Returns
array of bin edges (length of timebase + 1)

Definition at line 109 of file NNWaveFitter.h.

◆ getFit()

std::shared_ptr< nnFitterBinData > getFit ( const apvSamples samples,
double  tau 
)

Fitting method Send data and get rseult structure.

If the fitter is not properly initialized, empty structure with valid = false will be returned, no warning - warning is only given for unsuccessful initialization.

Parameters
samplesArray of 6 apv samples
tauThe wave width for the current strip (unencoded ns)
Returns
Pointer to array of bin probabilities.

Definition at line 267 of file NNWaveFitter.cc.

◆ getFitTool()

const NNWaveFitTool& getFitTool ( ) const
inline

Get a handle to a NNWaveFit object.

The object provides a set of tools to maniulate probabilities and calculate things from probability distributions.

Definition at line 98 of file NNWaveFitter.h.

◆ getTimeShiftBounds()

nnBoundsType getTimeShiftBounds ( ) const
inline

Get time shift bounds.

Returns
std::pair of time shift bounds used in simulation

Definition at line 126 of file NNWaveFitter.h.

◆ getWaveWidthBounds()

nnBoundsType getWaveWidthBounds ( ) const
inline

Get width bounds Width bounds are minimum and maximum width used in training the network.

The bounds are used to encode width on input to the fitter.

Definition at line 116 of file NNWaveFitter.h.

◆ readNetworkData()

int readNetworkData ( const std::string &  xmlFileName)
private

The method that actually reads the xml file.

Counting things in NN:

Parameters
xmlFileNameName of the source xml file with network data
Returns
0: OK, -1: something went wrong.

Layers: input (hidden layers) output = n_hidden_lyaers + 2 = m_nLayers 0,1,2,... m_nLayers - 1. Layer sizes: input is 6, output is given by time binning in training, so we know terms 0 and m_nLayers - 1, and we can even establish hidden layer sizes beforehand from the repr of the classifier! Weights are about connections between layers, so we have w01, w12,.. w(m_nLayers-2)(m_nLayers-1) so we denote w1, w2, ... w(m_nLayers - 1) Intercepts are related to neurons where connections converge and activation is applied. So we have i1,...i(m_nLayers - 1).

Definition at line 36 of file NNWaveFitter.cc.

◆ setNetwrok()

void setNetwrok ( const std::string &  xmlData)

Set proper network definition file.

Parameters
xmlDatastring containing the network definition xml tree

Definition at line 251 of file NNWaveFitter.cc.

◆ softmax()

Eigen::VectorXd softmax ( const Eigen::VectorXd &  input)
inlineprivate

Softmax function, normalization for the network's output layer.

This is a strange softmax that maps zero values back to zero, but this is what scikit-learn returns.

Definition at line 155 of file NNWaveFitter.h.

Member Data Documentation

◆ relu

activationType relu
private
Initial value:
=
[](double x) -> double { return std::max(double(0.0), x); }

Rectifier activation.

Definition at line 145 of file NNWaveFitter.h.

◆ sigmoid

activationType sigmoid
private
Initial value:
=
[](double x) -> double { double e = std::exp(x); return e / (1.0 + e); }

Sigmoid activation.

Definition at line 148 of file NNWaveFitter.h.


The documentation for this class was generated from the following files: