Changeset 13324 for fact/tools/pyscripts/doc/_build/latex/pyfact.tex

Timestamp:

04/05/12 17:32:54 (13 years ago)

Author:

lusterma

Message:

updated

File:

• fact/tools/pyscripts/doc/_build/latex/pyfact.tex (modified) (3 diffs)

fact/tools/pyscripts/doc/_build/latex/pyfact.tex

@@ -13 +13 @@
 
 \title{pyfact Documentation}
-\date{February 09, 2012}
+\date{April 05, 2012}
 \release{0.1}
 \author{Werner Lustermann}
@@ -135 +135 @@
 \end{itemize}
 
+If you are new to python you need to learn the basics. In any case it would be wise to study the following book:
+
+\emph{A Primer on Scientific Programming with Python - Hans Petter Langtangen}
+
+pyfact is supposed to follow closely the programming style thought in this book.
+
+\href{http://docs.python.org/}{python documentation pages}
+
+\href{http://www.astropython.org/resources}{astropython.org}
+
+
+\section{Python version and modules used}
+\label{introduction:python-version-and-modules-used}
+As long as you work on the ISDC FACT cluster most things should be just fine.
+{\color{red}\bfseries{}\textbar{}}python version: 2.6.6
+{\color{red}\bfseries{}\textbar{}}--- add later: list of modules
+
+
+\section{Style guide and coding conventions}
+\label{introduction:style-guide-and-coding-conventions}
+The code of pyfact follows the {\color{red}\bfseries{}{}`}Style Guide for python code \textless{}\href{http://www.python.org/dev/peps/pep-0008/}{http://www.python.org/dev/peps/pep-0008/}\textgreater{}.
+
+
+\chapter{Getting Started}
+\label{getting_started:getting-started}\label{getting_started::doc}\begin{enumerate}
+\item {} 
+Get an account at the FACT data center at ISDC
+
+\item {} 
+Setup your environment variables
+
+\item {} 
+Checkout the pyfact software repository
+
+\item {} 
+Try a few examples
+
+\end{enumerate}
+
+
+\section{1. Important links}
+\label{getting_started:important-links}\begin{description}
+\item[{\textbf{FACT data center at ISDC} \textless{}\href{http://www.isdc.unige.ch/fact/datacenter}{http://www.isdc.unige.ch/fact/datacenter}\textgreater{}**}] \leavevmode
+here you find instructions how to get an account, how to set it up and how to use it
+
+\item[{\textbf{SVN repository} \textless{}\href{https://fact.isdc.unige.ch/svn/fact/}{https://fact.isdc.unige.ch/svn/fact/}\textgreater{}}] \leavevmode
+hosts all FACT software (including pyfact)
+
+\item[{\textbf{FACT run database} \textless{}\href{https://www.fact-project.org/run\_db/db/fact\_runinfo.php}{https://www.fact-project.org/run\_db/db/fact\_runinfo.php}\textgreater{}}] \leavevmode
+here you find information about all available runs
+
+\item[{\textbf{eLogbook} \textless{}\href{https://www.fact-project.org/logbook/}{https://www.fact-project.org/logbook/}\textgreater{}}] \leavevmode
+telescope logbook used since Dec. 1, 2012; for logbook information before this date have a look here: \textless{}\href{http://fact.ethz.ch/FACTelog/index.jsp}{http://fact.ethz.ch/FACTelog/index.jsp}\textgreater{}
+
+\item[{\textbf{FACT La Palma pages} \textless{}\href{https://www.fact-project.org/}{https://www.fact-project.org/}\textgreater{}}] \leavevmode
+plenty of information concerning the telescope in La Palma
+
+\end{description}
+
+
+\section{2. Environment variables}
+\label{getting_started:environment-variables}
+set the following env variables depending on the SHELL you are using, for instance in .bashrc or .tcshrc
+\begin{itemize}
+\item {} 
+\textbf{ROOTSYS}: /swdev\_nfs/root\_v5.28.00
+
+\item {} 
+\textbf{PATH}: add \$ROOTSYS/bin
+
+\item {} 
+\textbf{PATH}: add /swdev\_nfs/FACT++
+
+\item {} 
+\textbf{LD\_LIBRARY\_PATH}: \$ROOTSYS/lib:/swdev\_nfs/FACT++/.libs
+
+\item {} 
+\textbf{PYTHONPATH}: \$ROOTSYS/lib
+
+\item {} \begin{description}
+\item[{\textbf{PYTHONPATH}: add all directories where python should search for modules. At least:}] \leavevmode\begin{itemize}
+\item {} 
+pyscripts/pyfact
+
+\item {} 
+pyscript/tools
+
+\item {} 
+pyscripts/ecamples
+
+\end{itemize}
+
+\end{description}
+
+\end{itemize}
+
+the absolute path depends on where you have checked (or will check) out the pyscripts repository
+
+
+\section{3. Check out the repository}
+\label{getting_started:check-out-the-repository}
+svn co \href{https://fact.isdc.unige.ch/svn/fact/tools/pyscripts/}{https://fact.isdc.unige.ch/svn/fact/tools/pyscripts/}
+
+
+\section{4. Create pyfits\_h.so library}
+\label{getting_started:create-pyfits-h-so-library}
+FACT data are stored in (gzipped) fits files, but the data files are too large to be read by the existing tools:
+
+\emph{pyfits \textless{}http://www.stsci.edu/institute/software\_hardware/pyfits\textgreater{}} which uses \href{http://heasarc.gsfc.nasa.gov/fitsio/}{cfitsio}.
+
+To mitigate this problem a C++ class defined in fits.h \footnote{
+fits.h (here named pyfits.h) is part of MARS and was written by T.Bretz, it was added to this repository for convienience
+} is used. A simple possibility to create an interface of this C++ class is to use ROOT and later to import it using the
+\href{http://root.cern.ch/drupal/category/package-context/pyroot}{pyroot} module.
+
+got to the directory: pyscripts/pyfact
+
+simple:
+
+\begin{Verbatim}[commandchars=@\[\]]
+@PYGZlb[]lusterma@PYGZat[]isdc-cn02 pyfact@PYGZrb[]@$ root
+ROOT 5.28/00 (trunk@PYGZat[]37585, Dec 14 2010, 15:20:27 on linuxx8664gcc)
+CINT/ROOT C/C++ Interpreter version 5.18.00, July 2, 2010
+Type ? for help. Commands must be C++ statements.
+Enclose multiple statements between { }.
+
+root @PYGZlb[]0@PYGZrb[] .L fits.h++
+Info in @textless[]TUnixSystem::ACLiC@textgreater[]: creating shared library /home@_nfs/isdc/lusterma/pyscripts/pyfact/./fits@_h.so
+root @PYGZlb[]1@PYGZrb[]
+\end{Verbatim}
+
+This might not work for whatenver reason then it should be done like this:
+
+\begin{Verbatim}[commandchars=@\[\]]
+@$rootcint -f my@_dict.C -c fits.h izstream.h
+@$g++ -fPIC -c -I@$ROOTSYS/include my@_dict.C -o my@_dict.o
+@$g++ -o fits@_h.so -shared my@_dict.o
+\end{Verbatim}
+
+Now you can check if the reading rawdata is working:
+
+\$ pyfact.py
+
+this should print some data from a few events
+
+
+\section{5. Run examples}
+\label{getting_started:run-examples}
+
+\chapter{Classes}
+\label{getting_started:classes}
+
+\section{pyfact.py}
+\label{getting_started:pyfact-py}
+
+\subsection{rawdata access}
+\label{getting_started:rawdata-access}\index{RawData (class in pyfact)}
+
+\begin{fulllineitems}
+\phantomsection\label{getting_started:pyfact.RawData}\pysiglinewithargsret{\strong{class }\code{pyfact.}\bfcode{RawData}}{\emph{data\_file\_name}, \emph{calib\_file\_name}, \emph{user\_action\_calib=\textless{}function \textless{}lambda\textgreater{} at 0xab028b4\textgreater{}}, \emph{baseline\_file\_name='`}, \emph{return\_dict=None}}{}
+raw data access and calibration
+\begin{itemize}
+\item {} 
+open raw data file and drs calibration file
+
+\item {} 
+performs amplitude calibration
+
+\item {} 
+performs baseline substraction if wanted
+
+\item {} 
+provides all data in an array:
+row = number of pixel
+col = length of region of interest
+
+\end{itemize}
+
+initialize object
+
+open data file and calibration data file
+get basic information about the data in data\_file\_name
+allocate buffers for data access
+
+data\_file\_name   : fits or fits.gz file of the data including the path
+calib\_file\_name : fits or fits.gz file containing DRS calibration data
+baseline\_file\_name : npy file containing the baseline values
+\index{baseline\_correct() (pyfact.RawData method)}
+
+\begin{fulllineitems}
+\phantomsection\label{getting_started:pyfact.RawData.baseline_correct}\pysiglinewithargsret{\bfcode{baseline\_correct}}{}{}
+subtract baseline from the data
+
+\end{fulllineitems}
+
+\index{baseline\_read\_values() (pyfact.RawData method)}
+
+\begin{fulllineitems}
+\phantomsection\label{getting_started:pyfact.RawData.baseline_read_values}\pysiglinewithargsret{\bfcode{baseline\_read\_values}}{\emph{file}, \emph{bsl\_hist='bsl\_sum/hplt\_mean'}}{}
+open ROOT file with baseline histogram and read baseline values
+file       name of the root file
+bsl\_hist   path to the histogram containing the basline values
+
+\end{fulllineitems}
+
+\index{board\_times (pyfact.RawData attribute)}
+
+\begin{fulllineitems}
+\phantomsection\label{getting_started:pyfact.RawData.board_times}\pysigline{\bfcode{board\_times}}{}
+time when the FAD was triggered, in some strange units...
+
+\end{fulllineitems}
+
+\index{calib\_file (pyfact.RawData attribute)}
+
+\begin{fulllineitems}
+\phantomsection\label{getting_started:pyfact.RawData.calib_file}\pysigline{\bfcode{calib\_file}}{}
+drs calibration file
+
+\end{fulllineitems}
+
+\index{calibrate\_drs\_amplitude() (pyfact.RawData method)}
+
+\begin{fulllineitems}
+\phantomsection\label{getting_started:pyfact.RawData.calibrate_drs_amplitude}\pysiglinewithargsret{\bfcode{calibrate\_drs\_amplitude}}{}{}
+perform the drs amplitude calibration of the event data
+
+\end{fulllineitems}
+
+\index{data (pyfact.RawData attribute)}
+
+\begin{fulllineitems}
+\phantomsection\label{getting_started:pyfact.RawData.data}\pysigline{\bfcode{data}}{}
+1D array with raw data
+
+\end{fulllineitems}
+
+\index{data\_file (pyfact.RawData attribute)}
+
+\begin{fulllineitems}
+\phantomsection\label{getting_started:pyfact.RawData.data_file}\pysigline{\bfcode{data\_file}}{}
+data file (fits object)
+
+\end{fulllineitems}
+
+\index{info() (pyfact.RawData method)}
+
+\begin{fulllineitems}
+\phantomsection\label{getting_started:pyfact.RawData.info}\pysiglinewithargsret{\bfcode{info}}{}{}
+print run information
+
+\end{fulllineitems}
+
+\index{nevents (pyfact.RawData attribute)}
+
+\begin{fulllineitems}
+\phantomsection\label{getting_started:pyfact.RawData.nevents}\pysigline{\bfcode{nevents}}{}
+number of events in the data run
+
+\end{fulllineitems}
+
+\index{next() (pyfact.RawData method)}
+
+\begin{fulllineitems}
+\phantomsection\label{getting_started:pyfact.RawData.next}\pysiglinewithargsret{\bfcode{next}}{}{}
+used by \_\_iter\_\_
+
+\end{fulllineitems}
+
+\index{next\_event() (pyfact.RawData method)}
+
+\begin{fulllineitems}
+\phantomsection\label{getting_started:pyfact.RawData.next_event}\pysiglinewithargsret{\bfcode{next\_event}}{}{}
+load the next event from disk and calibrate it
+
+\end{fulllineitems}
+
+\index{npix (pyfact.RawData attribute)}
+
+\begin{fulllineitems}
+\phantomsection\label{getting_started:pyfact.RawData.npix}\pysigline{\bfcode{npix}}{}
+number of pixels (should be 1440)
+
+\end{fulllineitems}
+
+\index{nroi (pyfact.RawData attribute)}
+
+\begin{fulllineitems}
+\phantomsection\label{getting_started:pyfact.RawData.nroi}\pysigline{\bfcode{nroi}}{}
+region of interest (number of DRS slices read)
+
+\end{fulllineitems}
+
+\index{start\_cells (pyfact.RawData attribute)}
+
+\begin{fulllineitems}
+\phantomsection\label{getting_started:pyfact.RawData.start_cells}\pysigline{\bfcode{start\_cells}}{}
+slice where drs readout started
+
+\end{fulllineitems}
+
+
+\end{fulllineitems}
+
+
+
+\subsection{fnames of a data run}
+\label{getting_started:fnames-of-a-data-run}\index{fnames (class in pyfact)}
+
+\begin{fulllineitems}
+\phantomsection\label{getting_started:pyfact.fnames}\pysiglinewithargsret{\strong{class }\code{pyfact.}\bfcode{fnames}}{\emph{specifier={[}`012', `023', `2011', `11', `24'{]}, rpath='/scratch\_nfs/res/bsl/', zipped=True}}{}
+organize file names of a FACT data run
+\begin{description}
+\item[{specifier}] \leavevmode{[}list of strings defined as:{]}
+{[} `DRS calibration file', `Data file', `YYYY', `MM', `DD'{]}
+
+\end{description}
+
+rpath     : directory path for the results; YYYYMMDD will be appended to rpath
+zipped    : use zipped (True) or unzipped (Data)
+\index{info() (pyfact.fnames method)}
+
+\begin{fulllineitems}
+\phantomsection\label{getting_started:pyfact.fnames.info}\pysiglinewithargsret{\bfcode{info}}{}{}
+print complete filenames
+
+\end{fulllineitems}
+
+\index{make() (pyfact.fnames method)}
+
+\begin{fulllineitems}
+\phantomsection\label{getting_started:pyfact.fnames.make}\pysiglinewithargsret{\bfcode{make}}{\emph{specifier}, \emph{rpath}, \emph{zipped}}{}
+create (make) the filenames
+
+names   : dictionary of filenames, tags \{ `data', `drscal', `results' \}
+data    : name of the data file
+drscal  : name of the drs calibration file
+results : radikal of file name(s) for results (to be completed  by suffixes)
+
+\end{fulllineitems}
+
+
+\end{fulllineitems}
+
+
 
 \chapter{Classes}
@@ -146 +491 @@
 
 \subsection{fnames of a data run}
-\label{classes:fnames-of-a-data-run}
+\label{classes:fnames-of-a-data-run}\index{fnames (class in pyfact)}
+
+\begin{fulllineitems}
+\phantomsection\label{classes:pyfact.fnames}\pysiglinewithargsret{\strong{class }\code{pyfact.}\bfcode{fnames}}{\emph{specifier={[}`012', `023', `2011', `11', `24'{]}, rpath='/scratch\_nfs/res/bsl/', zipped=True}}{}
+organize file names of a FACT data run
+\begin{description}
+\item[{specifier}] \leavevmode{[}list of strings defined as:{]}
+{[} `DRS calibration file', `Data file', `YYYY', `MM', `DD'{]}
+
+\end{description}
+
+rpath     : directory path for the results; YYYYMMDD will be appended to rpath
+zipped    : use zipped (True) or unzipped (Data)
+\index{info() (pyfact.fnames method)}
+
+\begin{fulllineitems}
+\phantomsection\label{classes:pyfact.fnames.info}\pysiglinewithargsret{\bfcode{info}}{}{}
+print complete filenames
+
+\end{fulllineitems}
+
+\index{make() (pyfact.fnames method)}
+
+\begin{fulllineitems}
+\phantomsection\label{classes:pyfact.fnames.make}\pysiglinewithargsret{\bfcode{make}}{\emph{specifier}, \emph{rpath}, \emph{zipped}}{}
+create (make) the filenames
+
+names   : dictionary of filenames, tags \{ `data', `drscal', `results' \}
+data    : name of the data file
+drscal  : name of the drs calibration file
+results : radikal of file name(s) for results (to be completed  by suffixes)
+
+\end{fulllineitems}
+
+
+\end{fulllineitems}
+
+
+
+\section{FIR filter functions}
+\label{classes:fir-filter-functions}
 
 \chapter{Examples}