The Swift Reduction Package - TNG - Users' Manual

by Stefano Covino, 21 Feb 2017, v. 1.0.0

Background

The Swift Reduction Package (hereafter SRP) is a packet of tools executable on the command line to make everyday astronomer’s life easier.

For any specific comment the main documentation for SRP is the reference source. Here we refer to a sub-package, SRPAstro.TNG, devoted to the analysis of data from the PAOLO instrument at the TNG telescope.

Installation

If you are just updating SRPAstro.TNG the simplest and suggested solution is to download the package from the PyPI archive with:

sudo easy_install -U -s /usr/local/bin -U -N SRPAstro.TNG

or:

sudo pip --install-scripts=/usr/local/bin -U --no-deps SRPAstro.TNG

provided of course you are connected to the web, and that you want your executable files in “/usr/local/bin”.

However, some of the required libraries can (will) require more concerned actions for their installation. In essentially all cases, browsing the web you can quickly find the solution to any problem. 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.

Step by step “how to”

This are just examples of what you can do with SRPAstro.TNG. As mentioned above, this sub-package, at present, contains tools to work with the PAOLO instrument, an optical polarimeter at one of the Nasmyth foci of the TNG.

Our purpose here is not to provide a general introduction to the general topic of optical polarimetry, and not even to discuss the subtle problems related to polarimetry at a Nasmyth focus. For all of the above topics there are many publications and textbooks, and we refer any user to specific publications (for Nasmyth polarimetry, i.e., Giro et al., 2003, SPIE, 4843, 456; Tinberger, 2007, PASP, 199, 1317; Joos et al., 2008, SPIE, 7016, 48; Witzel et al., 2011, A&A, 525, 130 or Covino et al., 2014, AN, 335, 117).

The procedure has been tested for linear polarization and not yet for circular polarization.

PAOLO data analysis

• Frame extraction

• Only a fraction of the frame is important for polarimetry. You can extract the important section(s) for photometry or spectroscopy with SRPTNGPAOLOCut -i inputfile -f.

• Frames photometry

• Photometry can be derived with any tool you like. Tests have been carried out withe the GAIA tool photom or with DAOPHOT. What it is assumed is that the final photometry table is an ASCII file with one row per object, with information about the position in pixel of the object on the frame available (i.e. X, Y). The order is unimportant.

• A possible example is the following:

• 1 200.34 500.32 15.456 0.012 ...

• 25 173.23 900.31 16.236 0.026 ...

• The output of many tools is not following this requirement. Within SRP you have tools to convert photometric output to tables as required here (SRPGAIA2Sky, SRPDao2Sky).

• Source matching

• After having derived a reliable instrumental photometry you need to associate objects observed in each of the four areas of the detector. This task can be carried out by SRPTNGPAOLOSourceMatch -f photo.fits -i photo.dat -o pol.fits -I 1 2 3 4 5. You need to provide the photometry table, information about the columns to consider, the output file and the original input FITS file because the command collects a lot of information important for later use (coordinates, epoch, etc.). In case you are averaging many frames please check that the various information reported in the FITS header as exposure time, and observation starting time are updated correctly. Again, if you need to modify FITS header you can use the SRP command SRPFitsHeader.

• Spectral matching

• In case you obtained spectro-polarimetric observations, once you have properly reduced and extracted your spectra, you can associate them with SRPTNGPAOLOSpectrumMatch -f 2Dspectrum.fits -s spec1.fits spec2.fits spec3.fits spec4.fits -o pol.fits.

• Table management

• All the output files generated by these commands are FITS files. It is possible to convert these tables to ASCII format or simply show on the terminal the table content with SRPFitsTableViewer -f input.fits -o output.dat. You can extract selected entries from a table with SRPTNGPAOLOSelectRow -f input.fits -o output.fits -r 1 3 4 or SRPTNGPAOLOSelectCoord -f input.fits -o output.fits -c 450.3 230.4. You can also merge tables with consistent parameters with SRPTNGPAOLOMergeTables -f tab1.fits tab2.fits -o mergedtab.fits.

• Instrumental Stokes parameters

• Instrumental Stokes parameters are then derived with SRPTNGPAOLOInstrStokes -f inpphot.fits -o istokes.fits. You can provide Stokes parameters for standard star observations and to calibrate the system.

• TNG polarization model parameter

• Once you have a table with standard star polarimetric observations you can compute the TNG polarization model parameters with SRPTNGPAOLOParamFit -i obspol.fits -o fit.fits. You can provide first guesses for all parameters (complex refractive index of the M3 TNG mirror reflective surface, detector offsets, transparency biases) and save results in output files to be later used for a refined fitting or for deriving calibrated scientific data. You can also choose which parameters to fit and which to keep frozen or coupled to other parameters. For instance the complex refractive index is expressed as a multiplicative factor of the Aluminum complex refractive index. It is possible to fit separately the real and imaginary part of the refractive index.

• Instrumental polarization corrected results

• Once you have derived a satisfactory instrumental polarization model you can correct the observed Stokes parameters for the instrumental effects with SRPTNGPAOLOCalStokes -i inputstokes.fits -f fitpars.fits -o calibstokes.fits.

• Simulated observations

• It is possible to simulate how polarized/unpolarized sources would have been observed by PAOLO applying the polarization model for a given source, observed at a given time for a given duration. For instance SRPTNGPAOLOStokesSim -c 10:10:10 10:10:10 -e 3600 -o simout.fits -s 0.1 0.01 0.0 -t ‘2012/12/12 12:12:12‘ -f firpars.fits.

Miscellanea

• SRP.TNG running version

• You can know the present SRP.TNG version with SRPTNGVersion

List of commands

1. SRPTNGPAOLOCalStokes

- Its purpose is to correct observed Stokes parameters for the instrumental polarization.

SRPTNGPAOLOCalStokes [-h] -f file -i file -o file [-v] [--version]

-f Input fit FITS file

-i Input normalized instrumental polarimetry FITS file

-o Output fit parameter FITS file

2. SRPTNGPAOLOCut

- Its purpose is to extract PAOLO polarimetric frames for an easier analysis.

SRPTNGPAOLOCut [-h] [-f] -i file [-q] [-v] [--version]

-f Cut full PAOLO polarimetric frame

-i Input FITS file list

-q Cut PAOLO polarimetric quadrants

3. SRPTNGPAOLOInstrStokes

- Its purpose is to compute instrumental Stokes parameters.

- SRPTNGPAOLOInstrStokes [-h] [-a] [-c Q eQ U eU V eV] -f file -o file

[-v] [--version] [-w wave]

-a Append data to output

-c Calibration Q, U and V values

-f Input FITS photometry/spectroscopy file

-o Output FITS file

-w Observation wavelength (micron)

4. SRPTNGPAOLOMergeTables

- Its purpose is to merge tables with consistent parameters.

- SRPTNGPAOLOMergeTables [-h] -f [file [file ...]] -o file [-v]

-f Input FITS file(s)

-o Output FITS file

5. SRPTNGPAOLOParamFit

- Its purpose is to compute the best-fit parameters for the TNG polarization model.

- SRPTNGPAOLOParamFit [-h] [-a n k] [-c n k detoff q0 u0 v0] [-d detoff] [-f file] -i file [-o file] [-s syst] [-v] [--version] [-z q0 u0 v0]

-a Aluminium refractive and extinction coefficient multiplicative factors

-c Choices for fitting: n, k, detoff, q0, u0, v0 [default=(1,-1,1,1,1,1)]

-d Detector offset (deg)

-f Input FITS Stokes parameter file

-i Input normalized instrumental Stokes parameter file

-o Output fit parameter FITS file

-s Systematic error to be added

-z Normalized instrumental polarization

6. SRPTNGPAOLOSelectCoord

- Its purpose is to select specific entries in a table.

- SRPTNGPAOLOSelectCoord [-h] -c coord coord -f file -o file [-q quad] [-t tol] [-v] [--version]

- c X, Y coordinates to search for (pixel)

-f Input PAOLO FITS file

-o Output FITS file

- q Quadrant with sources

-t Tolerance for matching (pixel)

7. SRPTNGPAOLOSelectRow

- Its purpose is to select specific entries in a table.

- SRPTNGPAOLOSelectRow [-h] -f file -o file [-r [rows [rows ...]]] [-v] [--version]

-f Input FITS photometry file

-o Output FITS file

-r Rows to select

8. SRPTNGPAOLOSourceMatch

_ Its purpose is to match objects observed in different areas of the detector.

SRPTNGPAOLOSourceMatch [-h] [-b offset] -f file -i file

-I col col col col col -o file

[-q row row row row row row row row]

[-s shift shift shift shift shift shift]

[-S seq seq seq seq] [-t tol] [-v] [--version]

-b Offset from bottom frame

-f Input FITS file

-i Input photometry file

-I Positions of Id, X, Y, mag, emag columns in input file

-o Output FITS file

-q Limits for each quadrants

-s Shifts (x and y) between quadrant 1 (the lowest) and the others

-S Sequence of quadrants (1 is the lowest)

-t Tolerance in source matching

9. SRPTNGPAOLOSpectrumMatch

_ Its purpose is to match spectra observed in polarimertic mode.

_ SRPTNGPAOLOSpectrumMatch [-h] [-e errspec errspec errspec errspec] -f file -o file -s spec spec spec spec [-S seq seq seq seq] [-v] [--version]

-e Input FITS error spectra

-f Input FITS file

-o Output FITS file

-s Input FITS spectra

-S Sequence of quadrants (1 is the lowest [Qo Uo Qe Ue])

-x Cross correlate input spectra

10. SRPTNGPAOLOStokesSim

- Its purpose is to simulate the effect of the TNG instrumental polarization on real observations.

- SRPTNGPAOLOStokesSim [-h] [-a n k] -c RA DEC [-d detoff] -e Exp

[-f file] [-l lambda angle] -o file [-p pos] -s Q

U V -t 'YYYY/MM/DD HH:MM:SS' [-v] [--version]

[-w wave] [-z q0 u0 v0]

-a Aluminium refractive and extinction coefficient multiplicative factors

-c Object coordinates

-d Detector offset (deg)

-e Observation length (sec)

-f Input FITS file with fit parameters.

-l lambda2 or lambda4 (2, 4) and angle

-o Output FITS file

-p Detector position angle

-s Object normalized Stokes parameters

-t Observation time

-w Observation wavelength (micron)

-z Normalized instrumental polarization

11. SRPTNGVersion

- its purpose is to show the running SRP.TNG version.

- SRPVersion [-h] [-v]

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.