\hypertarget{Tutorials_EventReconstruction}{}\subsection{Event reconstruction required}\label{Tutorials_EventReconstruction}
The vertex finder and flavour tagging software expects a set of tracks -\/ usually the tracks belonging to one jet in an event -\/ as input. Initially, it is therefore necessary to 
\begin{DoxyItemize}
\item obtain digitized hits  
\item reconstruct tracks  
\item run the jet finder  
\item reconstruct the event vertex / I\-P, if running the flavour tagging code  
\item determine the M\-C true jet flavour if studying flavour tag purity, efficiency  
\item determine the M\-C true quark charge to study performance of quark charge reconstruction  
\end{DoxyItemize}The performance presented at the \href{http://events.lal.in2p3.fr/conferences/ILCSoftware/}{\tt I\-L\-C software workshop, Orsay, May 2007} was obtained with the digitization and track cheating code developed by Alexei Raspereza. For the jet finding the Durham algorithm with a y-\/ cut of 0.\-04 was used, as implemented in the Satoru jet finder within Marlin\-Reco.

An example of the steering for the first three of the above event reconstruction steps, used to obtain the shown results, is given in the steering file \href{../cheattracks+jetfind.xmlsteer}{\tt cheattracks+jetfind.xml}. {\bfseries  This example assumes that the detector geometry L\-D\-C01\-\_\-05\-Sc is used -\/ hit collection names will need to be changed in the steering file when running with a different geometry. }

The event vertex or I\-P is needed for calculating the default flavour tag inputs. Since no code to do this was yet available in Marlin\-Reco, the L\-C\-F\-I group implemented a procedure similar to the one used in the \href{http://berggren.home.cern.ch/berggren/sgv.html}{\tt S\-G\-V fast M\-C }. This should only be considered as spaceholder for a future improved procedure in which for the vertex position in the x-\/y-\/plane one would average over tracks from a number of consecutive events. The current algorithm is implemented in the \hyperlink{classPerEventIPFitterProcessor}{Per\-Event\-I\-P\-Fitter\-Processor} and run by calling Marlin with the steering file \href{../ipfit.xmlsteer}{\tt ipfit.\-xml}.

The true flavour of a jet is based on the M\-C record in the event. It searches the event for the leading hadron, and if this is a heavy flavour particle determines which of the jets in the event is closest in angle. For heavy flavour jets, based on the leading hadron M\-C information also the quark charge of the heavy flavour hadron is determined. Further details can be found in the documentation of the \hyperlink{classTrueAngularJetFlavourProcessor}{True\-Angular\-Jet\-Flavour\-Processor}. This part of the reconstruction is performed by running Marlin with the \href{../truejetflavour.xmlsteer}{\tt truejetflavour.\-xml} steering file.\hypertarget{Tutorials_ZVTOPHowTo}{}\subsection{How to run the vertex finder Z\-V\-T\-O\-P}\label{Tutorials_ZVTOPHowTo}
Make sure the necessary \hyperlink{Tutorials_EventReconstruction}{event reconstruction steps} have been run in advance. The vertex finder Z\-V\-T\-O\-P has two branches\-: the standard branch \hyperlink{classZVTOPZVRESProcessor}{Z\-V\-R\-E\-S}, based purely on topological information, and the more specialized branch \hyperlink{classZVTOPZVKINProcessor}{Z\-V\-K\-I\-N}, which uses kinematic information from heavy flavour decay chains in addition. Flavour tagging for I\-L\-C physics simulation so far has been performed using Z\-V\-R\-E\-S only. The use of Z\-V\-K\-I\-N for this purpose is yet to be explored. It should also be noted that Z\-V\-K\-I\-N parameters have not yet been tuned for I\-L\-C conditions. This vertexing algorithm is generally less tested and optimised in terms of runtime than the Z\-V\-R\-E\-S branch.

For each of the two branches, a dedicated steering file is provided, named \href{../zvres.xmlsteer}{\tt zvres.\-xml} and \href{../zvkin.xmlsteer}{\tt zvkin.\-xml}, respectively. The output of Z\-V\-T\-O\-P consists of one collection storing the vertices that were found, one collection holding the corresponding Reconstructed\-Particles decaying at these vertex positions and one collection containing one Reconstructed\-Particle per jet which gives access to the full decay chain. Further details on the storage of the output can be found in the \hyperlink{LCIO}{L\-C\-I\-O Interface}.\hypertarget{Tutorials_FlavourTag}{}\subsection{How to flavour tag jets}\label{Tutorials_FlavourTag}
Before running the flavour tag, make sure the necessary \hyperlink{Tutorials_EventReconstruction}{event reconstruction processors} and \hyperlink{Tutorials_ZVTOPHowTo}{Z\-V\-T\-O\-P} have been run. In the default flavour tagging algorithm information from the vertex finder is both directly used as input for the tagging neural networks and to determine, which set of neural networks is used. You can either begin by \hyperlink{Tutorials_NetworkTraining}{training new neural nets} or use pre-\/trained nets. One set of nets, trained with input from the fast M\-C S\-G\-V, is provided with the Vertex Package. These nets are available from the new repository {\bfseries \href{http://www-zeuthen.desy.de/lc-cgi-bin/cvsweb.cgi/?sortby=file&hideattic=1&hidenonreadable=1&logsort=date&f=u&cvsroot=tagnet&path=}{\tt tagnet } } for flavour tag neural nets in the \href{http://www-zeuthen.desy.de/linear_collider/}{\tt Zeuthen C\-V\-S repository }.

Flavour tag inputs are calculated by running Marlin with the steering file \href{../fti.xmlsteer}{\tt fti.\-xml}. As input it requires the L\-C\-I\-O file with information from Z\-V\-T\-O\-P and the I\-P fit processor (default filename zvresout.\-slcio). The flavour tag inputs are written out into collections of L\-C\-Float\-Vec's as described in more detail in the \hyperlink{LCIO}{L\-C\-I\-O Interface}.

The neural network output values are obtained from an independent Marlin processor; the corresponding example steering file is \href{../ft.xmlsteer}{\tt ft.\-xml}. It requires the L\-C\-I\-O file written out in the Marlin run with \href{../fti.xmlsteer}{\tt fti.\-xml}, which is by default called ftiout.\-slcio. The default algorithm is based on nine neural networks, three for each of the three classes of jets, namely those with 1, 2 and 3 or more vertices found by Z\-V\-T\-O\-P. It thus provides three output values for each jet\-: a b-\/tag value, a c-\/tag value for arbitrary jet sample composition and a c-\/tag value assuming the background is known to consist of b-\/jets only (yielding improved c-\/tag purity). These are stored as components \char`\"{}\-B\-Tag\char`\"{}, \char`\"{}\-C\-Tag\char`\"{} and \char`\"{}\-B\-C\-Tag\char`\"{} of an L\-C\-Float\-Vec collection. The collection name -\/ Flavour\-Tag by default -\/ can be specified in the steering file. This collection, along with the information from the input-\/\-L\-C\-I\-O file, is written into an L\-C\-I\-O output file, named flavourtagout.\-slcio in the example.\hypertarget{Tutorials_PurityEfficiency}{}\subsection{How to evaluate and plot flavour tag purity vs efficiency}\label{Tutorials_PurityEfficiency}
Flavour tag purity as function of efficiency is a measure of how well the flavour tag performs for a certain mix of jet flavours. The Vertex Package provides two processors to calculate purity and efficiency\-: the \hyperlink{classPlotProcessor}{Plot\-Processor} and the \hyperlink{classLCFIAIDAPlotProcessor}{L\-C\-F\-I\-A\-I\-D\-A\-Plot\-Processor}. An example how to call these processors is given in the steering file \href{../ftplot.xmlsteer}{\tt ftplot.\-xml}.

The \hyperlink{classPlotProcessor}{Plot\-Processor} writes out a table with the resulting efficiency and purity values as well as the cut values on the neural net outputs these correspond to, into a comma separated value file. Additionally, if the root library is linked in at compile time by defining the preprocessor flag U\-S\-E\-R\-O\-O\-T, the corresponding graphs are written out into a root-\/file. These graphs can be plotted using the root-\/macro Make\-Purity\-Vs\-Efficiency\-Root\-Plot.\-C provided in the macro directory. This macro also allows to plot the resulting graphs from two different runs onto the same canvas to compare performance.

The \hyperlink{classLCFIAIDAPlotProcessor}{L\-C\-F\-I\-A\-I\-D\-A\-Plot\-Processor} provides further diagnostic tools for the flavour tag. Since different neural networks are used for the cases that 1-\/, 2-\/ or at least 3 vertices are found, purity and efficiency are calculated separately for these cases. Graphs in A\-I\-D\-A format are created for purity vs efficiency and for the flavour leakage (i.\-e. the \char`\"{}efficiency\char`\"{} of tagging the wrong flavour) as function of efficiency -\/ e.\-g. the leakage of usd-\/jets into the c-\/tagged sample. Also, distributions of all flavour tag input variables, the vertex charge and of the neural net output variables are created separately for the 1-\/, 2-\/ and 3 or more vertex case. Optionally information can be written out into an A\-I\-D\-A tuple and in text format, for further details see the \hyperlink{classLCFIAIDAPlotProcessor}{L\-C\-F\-I\-A\-I\-D\-A\-Plot\-Processor} documentation. Output from the \hyperlink{classLCFIAIDAPlotProcessor}{L\-C\-F\-I\-A\-I\-D\-A\-Plot\-Processor} can be plotted using the python script Flavour\-Tag\-Inputs\-Overlay.\-py from the macro directory.\hypertarget{Tutorials_NetworkTraining}{}\subsection{How to train new neural networks for flavour tagging}\label{Tutorials_NetworkTraining}
The Vertex Package is very flexible, so it is straightforward to entirely change the flavour tagging procedure. This is just an overview of changes possible, pointing out where to find further details.

In the simplest case that requires retraining, the tagging procedure itself is not changed. For example, one might want to retrain the networks after tuning Z\-V\-T\-O\-P, or changing other boundary conditions, such as track selection or composition of the input sample (as may happen when studying a specific physics channel). For this purpose, an example steering file \href{../trainNeuralNets.xmlsteer}{\tt train\-Neural\-Nets.\-xml} showing how to run the network training processor, is provided. You may choose to retrain only some of the networks -\/ each can be enabled in the steering file independently of the others.

Changes to the tagging algorithm will require writing new processors and recompiling Marlin. A simple example would be the change of the network architecture, such as number or type of nodes and / or internal layers. Please refer to the \hyperlink{NeuralNet}{neural network documentation} for details on how networks can be defined. As long as the number and choice of input variables remains unchanged, only the training processor \hyperlink{classNeuralNetTrainerProcessor}{Neural\-Net\-Trainer\-Processor} will have to be modified (or a new one added).

More complex modifications of processors are necessary when changes of the input variables are involved. This will require changes to at least three processors\-: the \hyperlink{classFlavourTagInputsProcessor}{Flavour\-Tag\-Inputs\-Processor} calculating the inputs, the \hyperlink{classNeuralNetTrainerProcessor}{Neural\-Net\-Trainer\-Processor} for training and the \hyperlink{classFlavourTagProcessor}{Flavour\-Tag\-Processor} for obtaining the network outputs in the subsequent analysis. If further variables are to be added, this might additionally require some familiarity with the internal structure of \hyperlink{ZVTOP}{Z\-V\-T\-O\-P}. The current way of writing out the inputs into an L\-C\-Float\-Vec collection permits further variables to be added in a straightforward way -\/ make sure to also update the section of the processor called at the start of the Marlin run, where the variable names are defined.

Changes to the input variables used in the training processor obviously require that the corresponding changes also be made in the processor obtaining the network outputs. In order to keep track of networks used and to allow shared use of networks within the community, a new \href{http://www-zeuthen.desy.de/lc-cgi-bin/cvsweb.cgi/?sortby=file&hideattic=1&hidenonreadable=1&logsort=date&f=u&cvsroot=tagnet&path=}{\tt cvs repository tagnet }has been set up in the \href{http://www-zeuthen.desy.de/linear_collider/}{\tt Zeuthen cvs area }. {\bfseries We strongly recommend submission of networks used for your studies to this repository}, along with a description of the boundary conditions for training -\/ make sure these descriptions are as complete as possible,including details on training sample and any changes to the defaults made (track selection, Z\-V\-T\-O\-P settings, addition of input variables, if possible with a reference to the code, with which these have been obtained). Providing this information will save time when it comes to comparisons of analyses made within different frameworks / detector concepts etc.\hypertarget{Tutorials_VertexCharge}{}\subsection{How to determine the vertex charge}\label{Tutorials_VertexCharge}
From version v00-\/02-\/02 onwards, the vertex charge is reconstructed in a dedicated processor, the \hyperlink{classVertexChargeProcessor}{Vertex\-Charge\-Processor}, and stored in its own L\-C\-Float\-Vec collections. Two vertex charge variables are calculated, one assuming the jet is a b-\/jet, the other assuming it is a c-\/jet. Two steering files are provided\-: \href{../Bvertexcharge.xmlsteer}{\tt Bvertexcharge.\-xml}, to be run first, producing an output L\-C\-Float\-Vec collection which is by default named Bcharge, and \href{../Cvertexcharge.xmlsteer}{\tt Cvertexcharge.\-xml}, to be run subsequently and producing an output L\-C\-Float\-Vec collection with default name Ccharge.\hypertarget{Tutorials_TrackSelection}{}\subsection{How to apply track selection cuts}\label{Tutorials_TrackSelection}
The various track selection criteria used in the code -\/ which differ between I\-P determination (cf \hyperlink{Cuts_IPCuts}{I\-P Fitting Cuts}), Z\-V\-T\-O\-P (cf \hyperlink{Cuts_ZVTOPCuts}{Z\-V\-T\-O\-P Cuts}) and the calculation of the flavour tag inputs (cf \hyperlink{Cuts_FlavourTagInputsCuts}{Flavour\-Tag\-Inputs Cuts}) -\/ are implemented by a flexible \hyperlink{classRPCutProcessor}{R\-P\-Cut\-Processor} that runs on reconstructed particles, containing the tracks in question. 