# Tutorials¶

## Quick-look analysis¶

### Preliminary info¶

This tutorial assumes that you have previous knowledge of timing techniques, so that I don’t repeat concepts as Nyquist frequency, the importance of choosing carefully the binning time and the FFT length, and so on. If you are not familiar with these concepts, this paper by Michiel is a very good place to start. Why in the example below I use the cospectrum instead of the PDS, is written in our timing paper.

This software has a modular structure. One starts from cleaned event files (such as those produced by tools like nupipeline and possibly barycentered with barycorr or equivalent), and produces a series of products with subsequent steps:

1. event lists containing event arrival times and PI channel information
2. (optional) calibrated event lists, where PI values have been converted to energy
3. light curves, choosing the energy band and the bin time
4. (optional) summed light curves if we want to join events from multiple instruments, or just from different observing times
5. power spectrum and/or cross spectrum (hereafter the frequency spectra’‘)
6. rebinning of frequency spectra
7. finally, lags and cospectrum
8. (optional) frequency spectra in XSpec format

Most of these tools have help information that can be accessed by typing the name of the command plus -h or –help:

$MPcalibrate -h usage: MPcalibrate [-h] [-r RMF] [-o] files [files ...] Calibrates clean event files by associating the correct energy to each PI channel. Uses either a specified rmf file or (for NuSTAR only) an rmf file from the CALDB positional arguments: files List of files optional arguments: -h, --help show this help message and exit -r RMF, --rmf RMF rmf file used for calibration -o, --overwrite Overwrite; default: no  Some scripts (e.g. MPreadevents, MPlcurve, MPfspec) have a --nproc option, useful when one needs to treat multiple files at a time. The load is divided among nproc processors, that work in parallel cutting down considerably the execution time. For I/O, MaLTPyNT looks if the netCDF4 library is installed. If it’s found in the system, files will be saved in this format. Otherwise, the native Python pickle format format will be used. This format is much slower (It might take some minutes to load some files) and files will be bigger, but this possibility ensures portability. If you don’t use netCDF4, you’ll notice that file names will have the .p extension instead of the .nc below. The rest is the same. ### Loading event lists¶ Starting from cleaned event files, we will first save them in MaLTPyNT format (a pickle or netcdf4 file). For example, I’m starting from two event lists called 002A.evt and 002B.evt, containing the cleaned event lists from a source observed with NuSTAR’s FPMA and FPMB respectively. $ MPreadevents 002A.evt 002B.evt
Opening 002A.evt
Saving events and info to 002A_ev.nc
Opening 002B.evt
Saving events and info to 002B_ev.nc


This will create new files with a _ev.nc extension (_ev.p if you don’t use netCDF4), containing the event times and the energy channel (PI) of each event

### Calibrating event lists¶

Use MPcalibrate. You can either specify an rmf file with the -r option, or just let it look for it in the NuSTAR CALDB (the environment variable has to be defined!)

$MPcalibrate 002A_ev.nc 002B_ev.nc Loading file 002A_ev.nc... Done. ###############ATTENTION!!##################### Rmf not specified. Using default NuSTAR rmf. ############################################### Saving calibrated data to 002A_ev_calib.nc Loading file 002B_ev.nc... Done. ###############ATTENTION!!##################### Rmf not specified. Using default NuSTAR rmf. ############################################### Saving calibrated data to 002B_ev_calib.nc  This will create two new files with _ev_calib.nc suffix that will contain energy information. Optionally, you can overwrite the original event lists. ### Producing light curves¶ Choose carefully the binning time (option -b). Since what we are interested in is a power spectrum, this binning time will limit our maximum frequency in the power spectrum. We are here specifying 2^-8 =0.00390625 for binning time (how to use the -b option is of course documented. Use -h FMI). Since we have calibrated the event files, we can also choose an event energy range, here between 3 and 30 keV. Another thing that is useful in NuSTAR data is taking some time intervals out from the start and the end of each GTI. This is mostly to eliminate an increase of background level that often appears at GTI borders and produces very nasty power spectral shapes. Here I filter 100 s from the start and 300 s from the end of each GTI. $ MPlcurve 002A_ev_calib.nc 002B_ev_calib.nc -b -8 -e 3 30 --safe-interval 100 300
Done.
Saving light curve to 002A_E3-30_lc.nc
Done.
Saving light curve to 002B_E3-30_lc.nc


To check the light curve that was produced, use the MPplot program:

$MPplot 002A_E3-30_lc.nc  MPlcurve also accepts light curves in FITS and text format. FITS light curves should be produced by the lcurve FTOOL or similar, while the text light curves should have two columns: time from the NuSTAR MJDREF (55197.00076601852) and intensity in counts/bin. Use $ MPlcurve --fits-input lcurve.fits


or

$MPlcurve --txt-input lcurve.txt  respectively. ### Joining, summing and “scrunching” light curves¶ If we want a single light curve from multiple ones, either summing multiple instruments or multiple energy or time ranges, we can use MPscrunchlc: $ MPscrunchlc 002A_E3-30_lc.nc 002B_E3-30_lc.nc -o 002scrunch_3-30_lc.nc
Done.
Done.
Saving joined light curve to out_lc.nc
Saving scrunched light curve to 002scrunch_3-30_lc.nc


This is only tested in safe’’ situations (files are not too big and have consistent time and energy ranges), so it might give inconsistent results or crash in untested situations. Please report any problems!

### Producing power spectra and cross power spectra¶

Let us just produce the cross power spectrum for now. To produce also the power spectra corresponding to each light curve, substitute "CPDS" with "PDS,CPDS". I use rms normalization here, default would be Leahy normalization.

$MPfspec 002A_E3-30_lc.nc 002B_E3-30_lc.nc -k CPDS -o cpds_002_3-30 --norm rms Beware! For cpds and derivatives, I assume that the files are ordered as follows: obs1_FPMA, obs1_FPMB, obs2_FPMA, obs2_FPMB... Loading file 002A_E3-30_lc.nc... Loading file 002B_E3-30_lc.nc... Saving CPDS to ./cpds_002_3-30_0.nc  ### Rebinning the spectrum¶ Now let’s rebin the spectrum. If the rebin factor is an integer, it is interpreted as a constant rebinning. Otherwise (only if >1), it is interpreted as a geometric binning. $ MPrebin cpds_002_3-30_0.nc -r 1.03
Saving cpds to cpds_002_3-30_0_rebin1.03.nc


### Calculating the cospectrum and phase/time lags¶

The calculation of lags and their errors is implemented in MPlags, and needs to be tested properly. For the cospectrum, it is sufficient to read the real part of the cross power spectrum as depicted in the relevant function in plot.py (Use the source, Luke!).

### Saving the spectra in a format readable to XSpec¶

To save the cospectrum in a format readable to XSpec it is sufficient to give the command

$MP2xspec cpds_002_3-30_0_rebin1.03.nc --flx2xsp  ### Open and fit in XSpec!¶ $ xspec
XSPEC> data cpds.pha
XSPEC> cpd /xw; setp ener; setp comm log y
XSPEC> mo lore + lore + lore
(...)
XSPEC> fit
XSPEC> pl eufspe delchi


etc.

## Data simulation¶

To simulate datasets, MaLTPyNT includes the MPfake script. It can simulate event lists with a fixed count rate or from an input light curve. Also, it is able to apply a dead time filter to the simulated event lists.

### Basic operations¶

To simulate a short observation (1025 s) at a given count rate (e.g., 150 ct/s), it is sufficient to call MPfake -c

$MPfake -c 150$ ls
events.evt


To simulate an event list from an input light curve, use the -l (or --lc) option. The light curve can be in FITS or MaLTPyNT native format (or one can use MPlcurve for the conversion from text format):

$MPfake -l lightcurve.fits  To apply dead time to the generated events, use the --deadtime option. deadtime can be supplied as a single number, meaning a constant dead time $ MPfake -l lightcurve.fits --deadtime 2.5e-3


or as two numbers (mean, sigma), meaning a Gaussian distribution of dead times with the specified mean and sigma.

More advanced options are available using the functions in maltpynt.fake.