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.