The Swift Reduction Package Users' Manual

 

by Stefano Covino, 21 Feb 2017, v. 4.2.0

 

 

Background

The Swift Reduction Package (hereafter SRP) is a packet of command line tools to solve problems (e.g. basic reduction and analysis tasks of optical/NIR astronomical data, quick cosmological computations, units conversions, etc.) often met in astronomical research activities.

 

SRP was originally developed in the context of the Swift follow-up activities of the Milan GRB team at the INAF/Brera Astronomical Observatory. The package is designed to be an aid to any researcher to drive further observation of a followed-up GRB counterpart and ÒswiftÓ can therefore be read simply as ÒrapidÓ, ÒagileÓ, etc.

The package is continuously upgraded and improved. Within the limits of our basic project choice (i.e. to provide an as simple as possible tools rather than a very powerful but complex reduction/analysis/computation environment) any help is absolutely welcome.

 

Some technical comment

This package, written in Python (v. 3.x), has been widely tested only on PC-Linux and on Mac OS X workstations. You are anyway absolutely free to use, modify, redistribute this package as you like.

Of course, in any case, we decline any responsibility for the use of this package. Given that the sources are available, and the algorithm public, the results are entirely under your own responsibility.

 

Mailing-List

Due to the nature of the SRP project it quite likely to have frequent update and improvements of the various routines as well as a continuous bug fixing (and new bugs are definitely introduced after any feature additions...). Therefore, if you want to be warned each time a new version is delivered, please send an e-mail to the following address: stefano.covino@brera.inaf.it with subject simply SRP.

 

Installation

If you are just updating SRP the simplest solution is to download the package from the PyPI archive with:

 

sudo easy_install -U -N SRPAstro

 

or, for pip supporters:

 

sudo pip install -U --no-deps SRPAstro

 

If you, instead, are installing SRP for the first time or maybe you are upgrading to a new Python release, it is likely you need to install the many different libraries SRP relies on.

 

In principle the command:

 

sudo easy_install SRPAstro

 

or

 

sudo pip  SRPAstro

 

should again do the job. You might also consider to install the package in a virtual python environment if you do not want to interfere with the system python installation.

 

However, some of the required libraries can (will) ask for more concerned actions for their installation. Indeed, in essentially all cases, browsing the web you can quickly find the solution to any problem. However, an alternative and strongly advised procedure is to install one of the available open-source self-contained scientific python installations as the Anaconda distribution (first choice). Most of the required libraries would then available with no further efforts and SRP is installed smoothly.

 

In addition to the ÒcoreÓ SRP package there are additions to cover specific tasks or applications:

a.         SRP.FITS, providing general tools to handle FITS files usually, but not necessarily, obtained by optical/NIR telescopes.

b.         SRP.REM, providing a few commands to work with REM telescope data.

c.          SRP.TNG, providing a few commands to work with TNG telescope instruments.

d.         SRP.NOT, providing a few commands to work with NOT telescope instruments.

e.         SRP.GW, providing tools to manage big catalogues to look for gravitational wave electromagnetic counterparts.

f.           SRP.SRPPipelines, general tools to develop pipelines for massive data reduction

g.         SRP.SRPPipelines.REM, REM telescope pipeline command.

h.         SRP.SRPPipelines.TNG, TNG telescope pipeline commands.

 

Only the ÒcoreÓ SRP, the SRP.FITS, SRP.REM and SRP.TNG sub.packages are distributed for general use.

 

 

Step by step Òhow toÓ

This are just examples of what you can do with SRP. Please, pay attention that the main emphasis in developing these tools is put in the rapidity and friendly use rather than in getting the very best solution for any possible case. However, experience says that in most cases the results are fully acceptable.

 

 

 

Spectroscopy data analysis

1.        Air / Vacuum wavelength conversion

_           This is a simple tool to convert air wavelength to/from vacuum wavelength. SRPAirVacuum -A 6562.801.

2.        DLA , IGM, and line profiles

_           We can also derive the absorption factor due to Dumped Lyman_ systems with SRPDLA -l 0.4 -n 1e21 -z 1.0 and due to IGM with SRPIGM -l 1.1 -x 0.9 -t 7.8. For a general transition and a more accurate modeling you can derive the absorption factor with SRPLineProfile -n 1e20 -b 1 -l 1300 -t TiII_3073. This function compute a Voigt profile taking into account both Dšppler and intrinsic broadening.

3.        Solar abundances

_           Element abundances in the Sun can be retrieved i.e. with SRPSolarAbundance -e Ne. Data are from Asplund et al. (2009, ARA&A, 47, 481).

 

 

Magnitude, flux, frequency, absorption and reddening

1.        Magnitude to/from flux conversion

_           It is quite common to have to convert magnitudes to physical units. To do that it is enough to run SRPMagFlux -b R -m 18.0 0.03. You will get the effective frequency, flux and 1-_ error for magnitude, 1-_ error and band reported. The output unit is Jansky or erg s-1cm-2A-1. It is of course possible to derive magnitudes from fluxes with the same command: SRPMagFlux -b R -j 1e-5 2e-7.

2.        Reddening determination and absorption factors

_           Assuming to know the color excess EB-V it is possible to estimate the amount of reddening at a given wavelength with SRPDustAbs -g MW -w 0.7. The wavelength unit is micron and the output is expressed in magnitudes. Extinction curves for the MW, the LMC and the SMC (Pei, 1992, ApJ, 395, 130) and a generic starburst galaxy (Calzetti et al., 2000, ApJ, 533, 682). It is also possible to know the absorption factor due to neutral gas in the X-rays (Morrison & McCammon, 1983, ApJ, 270, 119) with SRPNhAbs -e 1 -n 1e21.

3.        Flux density and energy-frequency conversion 

_           SRPPLFluxDensity allows you to compute the flux density at any given energy assuming to have a power-law spectrum and the integrated flux, i.e. SRPPLFluxDensity -f 2.4e13 -s 1.7. The integrated flux is supposed to be expresses in erg/s*cm2, the energy in keV, and the flux density is expressed in Jy. With SRPEnergyFreqFlux -e 1 -j 1e-6 you can convert energy to frequency or wavelength and vice-versa and flux densities from Jy to erg/s cm2 and viceversa. Energy is expressed in eV, frequency in Hz and wavelength in micron.

4.        Atmospheric absorption

-           Atmospheric extinction coefficients for a few observing sites can be derived with SRPAtmExtinction -w 0.55 -s LaSilla.

 

 

Tables and catalogues

1.        Catalogue query

_           Given a position in the sky and a radius with the command SRPQuery -a 01 23 45 -d 23 32 00 -c BS -r 120 you find objects in a catalogue among those available. The radius unit is arcmin. With SRPNameResolver -n "Sirius" you can obtain, from SIMBAD, the coordinates of a known astrophysical source.

2.        Table extraction

_           This command helps you to extract only selected columns from a table for further analyses. It is also possible to skip header rows as in SRPTabExtract -t table.txt -c '2 3 4 5' -o _output.txt -j 2.

3.        Object extraction

_           You can select a single, or more, objects in a table basing on their coordinates with SRPGetTabEntry -i table.dat -c 2 3 -C 240.45 312.23 -t 1. It is possible to work with angular or Cartesian coordinates. You can also filter selected objects from a table with the same command.

4.        Table match

_           This command allows you to find the common objects between two tables (i.e. the SRPPhotometry output). You must provide the file names of the table, shifts in both axes, and the maximum tolerance (first match and fine tuning) for object matching: SRPMatch -r refile.dat -m matchfile.dat -t 5 2.5 -o _outfile.dat. Same table scale and orientation is assumed. If, on the contrary, you want to find common objects with the same angular coordinates in two tables, you can try SRPMatchCoord -r refile.dat -m matchfile.dat -t 1 -o _outfile.dat.

 

 

Observation management

1.        Target visibility

_           Providing geographic position of the observer, target coordinate and a time reference you can know the azimuth and altitude of the target and the Moon and Sun separation. It is thought as a simple aid for observation planning: SRPVisibility -o 10:11:12 -20:21:22. In case you do not provide any input apart from target coordinate the ESO-La Silla site and the present date are assumed.

2.        Date conversion

_           It could be useful to quickly convert from/to dates in "regular" format (yyyy/mm/dd hh:mm:ss.dd) to Julian Date of Modified Julian Date. This can be done with SRPCalendar -v -d 2009/4/8 10:51:00.

3.        Finding-chart creation

_           In order to quickly generate nice-looking (hopefully) finding charts you can use SRPFindingChart -f fitsfilename.

 

 

Statistics

1.        Gaussian distribution

_           Providing mean and standard deviation you can generate an arbitrary number of values following a given Gaussian distribution: SRPGaussDistrib -m 3 -s 0.1 -n 10.

2.        Gaussian probability

_           You can compute Gaussian 1-tail or 2-tail probability distribution given a value in units of sigma: SRPGaussProb -s 3 -2.

3.        Chi square surface

_           You can easily derive the increment for the chi square function given some degrees of freedom at a given probability with SRPChiSqIncrement -p 90 -d 5. Else, you can compute the probability to have a chisquare higher than the obtained value by chance with SRPChiSqIncrement -c 10 -d 7.

4.        Sigma-clipped average

_           It is often useful to can evaluate a sigma-clipped average for input data from a file. You can do that with SRPAverSigmaClipping -i inputtab.txt -d 4 -k 5.

5.        Histogram creation

_           This command takes a column from a file as input and computes an histogram. The output is a table with bin center, bin size, and number of objects in the bin. Histogram parameters as minimum (i.e. 1), maximum (i.e. 10) and bin size (i.e. 0.2) can be chosen as in SRPHistogram -c 2 -t table.txt -o _output.txt -b 1 10 0.2.

6.        F-Test computation

_           You can check the improvement of a fit quality adding parameters with the F-test: SRPFTest -n  14.45 12 -o 16.34 14.

 

 

Afterglow data and cosmology

1.        Afterglow flux and frequencies

_           SRPAftTypSynchrFluxConst(Wind) allows you to compute the cooling (typical)(self absorption) synchrotron frequency (Hz) in case of constant ISM (wind). You compute the flux (Jy) at the typical synchrotron frequency and the flux for a typical afterglow spectrum at any frequency. From Zhang & Meszaros, IJMPA A19, 2385 (2004) and Hurley, Sari and Djorgovski, in "Compact Stellar X-ray Sources" (Cambridge University Press).

2.        Cosmological parameter computation 

_           This command allows one to compute the Hubble, angular diameter, comoving and luminosity distances from a minimum to a maximum redshift in any expanding universe. The distance modulus is also derived. Universe parameters, i.e. matter density, cosmological constant, etc. can be provided. SRPCosmology -v -z 1.5 you get the various distances for the default "concordance" cosmological model. 

 

 

 

 

Miscellanea

1.        SRP running version

-           You can know the present SRP version with SRPVersion.

2.        Polarization data

-           Polarization data can be converted to/from Stokes parameters with SRPStokesPol -s 0.1 0.01 -0.1 0.01 0.0 0.0.

 

 

 

 

List of commands

3.        SRPAftSynchrSpectrumConst

_           Its purpose is to compute the afterglow synchrotron spectrum in case of constant density ISM.

           

4.        SRPAftSynchrSpectrumWind

_           Its purpose is to compute the afterglow synchrotron spectrum in case of wind.

 

5.        SRPAirVacuum

_           Its purpose is to convert air wavelength to vacuum wavelength and viceversa.

 

6.        SRPAtmExtinction

_           Its purpose is to derive atmospheric extinction coefficients.

     

7.        SRPAverSigmaClipping

_           Its purpose it to compute a sigma-clipped average for input data.

 

8.        SRPCalendar

_           Its purpose is to convert dates from/tom various formats.

 

9.        SRPChiSqIncrement

_           Its purpose is to compute increment for chi squares.

                        The routine allows one to compute the increment for the chi square having a probability 100-prob% to occur randomly. Typical usage is for deriving uncertainties for multiparametric fits. Typical usage is for deriving uncertainties for multiparametric fits. Alternatively, one can compute the probability to have randomly a higher chisquare than the one obtained in a fit.

10.    SRPCosmology

_           Its purpose is to derive cosmological data.

 

11.    SRPDLA

_           Its purpose is to derive the absorption factor due to DLA systems.

_           DLA modeling performed according to Totani et al. (2006, PASP

                        58, 485)

 

12.    SRPDustAbs

_           Its purpose is to compute the amount of reddening at a given wavelength.         Extinction curves for the MW, LMC and SMC galaxies following Pei

                        (1992, ApJ, 395, 130) and starburst galaxies following Calzetti et

                        al. (2000, ApJ, 533, 682)

 

13.    SRPEnergyFreqFlux

_           Its purpose is to convert energy to frequency or wavelength and vice-versa.

 

14.    SRPGaussDistrib

_           Its purpose is to generate number following the Gaussian distribution.

15.    SRPGaussProb

_           Its purpose is to compute probability for Gaussian distributions.

 

16.    SRPGetTabEntry

_           Its purpose is to find selected objects in a table.

           

17.    SRPHistogram

_           Its purpose is to compute an histogram of input data.

 

18.    SRPIGM

_           Its purpose is to derive the absorption factor due to IGM systems.

 

19.    SRPLineProfile

_           Its purpose is to compute line profile for a specific transition.

_           Line profile computed by Voigt function computation.

 

20.    SRPMagFlux

_           Its purpose is to convert magnitudes to/from fluxes.

 

21.    SRPMatch

_           Its purpose is to find common objects between two tables.

 

 

22.    SRPMatchCoord

_           Its purpose is to find common objects, with the same angular coordinates, in two tables.

_            

23.    SRPNameResolver

_           Its purpose is to find the coordinates of a known astrophysical source from SIMBAD.

 

24.    SRPNhAbs

_           Its purpose is to compute the amount of absorption at a given energy.

_           Based on photoelectric absorption cross sections in Morrison &

                        McCammon (1983, ApJ, 270, 119)

 

25.    SRPPLFluxDensity

_           Its purpose is to derive flux density known a power-law spectrum and integrated flux.

 

26.    SRPQuery

_           Its purpose is to extract a region from a catalogue.

_           For several catalogues you need a working internet connection.Other catalogues are local.

 

27.    SRPSelect

_           Its purpose is to allow to create list of frames satisfying some criterion.

 

28.    SRPSessionName

_           Its purpose is to define a new session name.

 

29.    SRPSolarAbundance

_           Its purpose is to derive the Solar abundance of various chemical elements.

                        Data are from Asplund et al. (2009, ARA&A, 47, 481)

 

30.    SRPStokesPol

_           Its purpose is to convert from polarization to Stokes parameter and viceversa.

 

31.    SRPTabExtract

_           Its purpose is to extract selected columns from a table.

 

32.    SRPVersion

-          its purpose is to show the running SRP version.

 

33.    SRPVisibility

_           Its purpose is to compute the visibility of a sky object.

 

 

Bugs, comments, etc.

Of course, as already stated, any contribution from anyone is welcome. In case you find bugs, have improvements to suggest, would like to contribute to the code, etc. Please send an e-mail to Stefano Covino, stefano.covino@brera.inaf.it. We can not promise to take into account all your comments, but we will anyway try to improve the package to meet your needs.

 

 

 

Credits, thanks, etc.

A lot of people gave some contribution to the SRP and among them I want to quote Nino Cucchiara, Paolo D'Avanzo, Luca Di Fabrizio, Dino Fugazza, Auvet Harutyunyan, Nauzet Hernandez, Domenico Impiombato, Gianluca Israel, Daniele Malesani, Emilio Molinari and Ruben Salvaterra. I also thank ESO and TNG since part of this code was developed during visitorships in Garching and La Palma.