t-tools.0.7.1.source-code.FACT-API.tex Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of fact-tools Show documentation
The FACT telescope is a Cherenkov telescope on the island of La Palma. This set of tools is dedicated to read, parse and process raw data produced by the FACT telescope.
The newest version!
\documentclass[german,a4,11pt]{scrartcl}

\usepackage{hyperref}
\hypersetup{
  linktoc=all
}

\usepackage{afterpage}
\usepackage{tikz}
\usetikzlibrary{shapes} 
\usetikzlibrary{decorations,arrows} 
\usetikzlibrary{decorations.pathmorphing} 
\usepgflibrary{decorations.pathreplacing} 

\usepackage{algorithm}
%\usepackage{algorithmicx}
\usepackage{algpseudocode}
\usepackage{tocvsec2}
\usepackage{color}
\definecolor{rapidi}{RGB}{240,176,0}
\definecolor{rapidiText}{RGB}{102,51,0}
\definecolor{darkGreen}{RGB}{67,101,0}
\DeclareRobustCommand{\pointer}[1]{\tikz\node[draw,circle,draw=darkGreen,thick,fill=darkGreen!70,inner sep=1pt] at (0,-0.1) {\scriptsize\color{white}\textsf{#1}};} 

\usepackage{listings}
\lstset{language=XML,
%  otherkeywords={stream,container,process,service},
  basewidth={0.5em,0.45em},
  fontadjust=false,
  basicstyle=\footnotesize\ttfamily,
  keywordstyle=\color{blue},          % keyword style
  commentstyle=\ttfamily\color{black!60},       % comment style
  stringstyle=\color{darkGreen}
}
\input{streams.pkg}


\title{FACT API Documentation}
\author{\large Christian Bockermann, Kai Br\"{u}gge \\ \large{\{{\ttfamily firstname.lastname}\}{\ttfamily @tu-dortmund.de}}}

\begin{document}
\maketitle

\section{FACT Processors}
The FACT tools is a collection of processors that can be used with the
{\em streams} framework to process FACT events in a streaming
fashion. {\em streams} is a high-level abstraction for data stream
processing that allows for defining data stream processes in XML
\cite{streams:tr}. This document provides an auto-generated
documentation of the processors that have been implemented to handle
FACT telescope data with {\em streams}.

\subsection{Reading FACT Data}
The {\em fact-tools} library is an extension of the {\em streams}
framework that adds domain specific implementations such as
stream-sources and specific processors to process FACT data stored in
FITS files. These processors provide the code for calibrating the data
according to previously observed parameters, allow for camera image
analysis (image cleaning) or for extracting features for subsequent
analysis.

The XML snippet in Figure \ref{fig:readFACTxml} defines a simple process to
read raw data from a FITS file and apply a calibration step to transform that
data into correct values based upon previously recorded calibration parameters.

\begin{figure}[h!]
\begin{lstlisting}{language=XML}
    
        

        
             
             
        
    
\end{lstlisting}
\caption{\label{fig:readFACTxml}Basic process definition for reading raw FACT data
and calibrating that data.}
\end{figure}

Each single event that is read from the event stream, contains the
full raw, calibrated measurements of the telescope. 
%As with all other
%data stream implementations, the {\em FactEventStream} emits a sequence
%of {\em data items}, each of which contains the data of a single FACT
%event.
The attributes of the data items reflect the image data, event
meta information and all other data that has been recorded during the
observation. Table \ref{tab:factEventKeys} lists all the attributes of
an event that are currently provided by the {\ttfamily FactDataStream}
class.
\begin{table}[h!]
\renewcommand{\arraystretch}{1.25}
{\footnotesize
  \begin{center}
    \begin{tabular}{l|l} \hline
      \textsf{\textbf{Name (key)}} & \textsf{\textbf{Description}} \\ \hline \hline
      {\ttfamily EventNum} & The event number in the stream \\ \hline
      {\ttfamily TriggerNum} & The trigger number in the stream \\ \hline
      {\ttfamily TriggerType} & The trigger type that caused recording of the event \\ \hline
      {\ttfamily NumBoards} & \\ \hline
      {\ttfamily Errors} & \\ \hline
      {\ttfamily SoftTrig} & \\ \hline
      {\ttfamily UnixTimeUTC} & \\ \hline
      {\ttfamily BoardTime} & \\ \hline
      {\ttfamily StartCellData} & \\ \hline
      {\ttfamily StartCellTimeMarker} & \\ \hline
      {\ttfamily Data} & The raw data array ($1440\cdot 300 = 432000$ float values) \\ \hline
      {\ttfamily TimeMarker} & \\ \hline
      {\ttfamily @id} & A simple identifier providing date, run and event IDs \\ \hline
      {\ttfamily @source} & The file or URL the event has been read from \\ \hline
    \end{tabular}
  \end{center}}
  \caption{\label{tab:factEventKeys} The elements available for each event.}
\end{table}

The {\ttfamily @id} and {\ttfamily @source} attributes provide
meta-information that is added by the FACT-stream implementation
itself, all the other attributes are provided within the FITS data
files. The {\ttfamily @id} attribute's value is created from the
{\ttfamily EventNum} and date when the event was recorded,
e.g. {\ttfamily 2011/11/27/42/8}, denoting the event 8 in run 42 on
the 27th of November 2011.


\subsection{Processors for FACT Data}
Any of the existing core processors of the {\em streams} library can
directly be applied to data items of the FACT event stream. This
already allows for general applications such as adding additional data
(e.g. whether data from a database) or filtering of events using
processors such as {\ttfamily stream.flow.Skip}:
\begin{figure}[h!]
\begin{lstlisting}{language=XML}
    ...
        
             
             
        
    ...
\end{lstlisting}
%\caption{\label{fig:readFACTxml}Basic process definition for reading raw FACT data
%and calibrating that data.}
\end{figure}

\subsection{The general FACT processors}
As outline in table \ref{tab:factEventKeys}, a FACT event is a data item (hash map)
of several keys, the most central one being the {\ttfamily Data} entry. This key
provides access to the full pixel data over all time slices and can be viewed as
a linearized matrix.

\include{API_fact_data_index}
\include{API_fact_image_index}

\end{document}