source: fact/tools/pyscripts/doc/getting_started.rst@ 13325

===============
Getting Started
===============

1) Get an account at the FACT data center at ISDC
2) Setup your environment variables
3) Checkout the pyfact software repository
4) Try a few examples

1. Important links
=================================

**FACT data center at ISDC** <http://www.isdc.unige.ch/fact/datacenter>**
    here you find instructions how to get an account, how to set it up and how to use it

**SVN repository** <https://fact.isdc.unige.ch/svn/fact/>
    hosts all FACT software (including pyfact)

**FACT run database** <https://www.fact-project.org/run_db/db/fact_runinfo.php>
    here you find information about all available runs

**eLogbook** <https://www.fact-project.org/logbook/>
  telescope logbook used since Dec. 1, 2012; for logbook information before this date have a look here: <http://fact.ethz.ch/FACTelog/index.jsp>

**FACT La Palma pages** <https://www.fact-project.org/>
  plenty of information concerning the telescope in La Palma

2. Environment variables
========================
set the following env variables depending on the SHELL you are using, for instance in .bashrc or .tcshrc

* **ROOTSYS**: /swdev_nfs/root_v5.28.00
* **PATH**: add $ROOTSYS/bin
* **PATH**: add /swdev_nfs/FACT++
* **LD_LIBRARY_PATH**: $ROOTSYS/lib:/swdev_nfs/FACT++/.libs
* **PYTHONPATH**: $ROOTSYS/lib
* **PYTHONPATH**: add all directories where python should search for modules. At least:
    * pyscripts/pyfact
    * pyscript/tools
    * pyscripts/ecamples

the absolute path depends on where you have checked (or will check) out the pyscripts repository

3. Check out the repository
===========================
svn co https://fact.isdc.unige.ch/svn/fact/tools/pyscripts/

4. 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: 

`pyfits <http://www.stsci.edu/institute/software_hardware/pyfits>` which uses `cfitsio <http://heasarc.gsfc.nasa.gov/fitsio/>`_.

To mitigate this problem a C++ class defined in fits.h [#f1]_ is used. A simple possibility to create an interface of this C++ class is to use ROOT and later to import it using the
`pyroot <http://root.cern.ch/drupal/category/package-context/pyroot>`_ module.

got to the directory: pyscripts/pyfact

simple::

  [lusterma@isdc-cn02 pyfact]$ root
  ROOT 5.28/00 (trunk@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 [0] .L fits.h++
  Info in <TUnixSystem::ACLiC>: creating shared library /home_nfs/isdc/lusterma/pyscripts/pyfact/./fits_h.so
  root [1]

This might not work for whatenver reason then it should be done like this::

  $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

Now you can check if the reading rawdata is working:

$ ./pyfact.py

this should print some data from a few events

5. Run examples
===============

*datafilepath* and *calibfilepath* should be adjusted in case you are not working
on the ISDC cluster. 

explore class RawData::

  import pyfact
  datafilepath = '/data00/fact-construction/raw/2012/03/04/20120304_018.fits.gz'
  calibfilepath = '/data00/fact-construction/raw/2012/03/04/20120304_012.drs.fits.gz'
  run = pyfact.RawData( datafilepath, calibfilepath, return_dict = True)
  event = run.next()
  
  type(event)
  
  print 70*'*'
  for key in event:
    print 'key  :', key
    print 'value:', event[key]
    print 70*'*'

loop over RawData::

  import pyfact
  datafilepath = '/data00/fact-construction/raw/2012/03/04/20120304_018.fits.gz'
  calibfilepath = '/data00/fact-construction/raw/2012/03/04/20120304_012.drs.fits.gz'
  run = pyfact.RawData( datafilepath, calibfilepath, return_dict = True)
  
  for event in run:
    print 'event_id:', event['event_id'] 
    # the data can be found in event['acal_data']

.. rubric:: Footnotes
.. [#f1] fits.h (here named pyfits.h) is part of MARS and was written by T.Bretz, it was added to this repository for convienience