batbinevt computes mask weighted light curves and spectra for BAT event and detector plane histogram data (DPHs). This tool can use the weights generated by batmaskwtevt or batmaskwtimg to make binned output light curves and spectra. batbinevt can also be used to make raw detector plane images and histograms, and to rebin raw detector plane histograms in time or energy.
The input event file must normally have been processed first by batmaskwtevt for a particular source position. Thus, batbinevt will only extract weighted products for one source at a time, although it can compute many time or energy samples.
batbinevt operates on either event data or BAT DPH data. Event data must have the TIME and energy columns. If weighting is applied, then either the MASK_WEIGHT column must be present, or a separate mask weight image file must be supplied.
batbinevt can also read detector plane histograms (DPHs). BAT DPHs have two spatial dimensions and one energy dimension. They are produced by the BAT flight software, and also perhaps previous runs of batbinevt. They must contain an EBOUNDS extension which describes the energy bin edges.
batbinevt can output several file types. The most common will be
batbinevt can also output histograms and images:
Applying mask weighting is equivalent to background subtraction. Detectors which are fully shadowed are assigned a -1 weight, and fully illuminated detectors a +1 weight, and partially illuminated detectors are assigned an prorated value. Thus, a weighted sum of the counts will automatically subtract the background.
The default of the 'weighted' parameter depends on the output type.
Users can choose to change the default by setting weighted to "yes" or "no."
For event data, the default is to take the mask weighting values for each event from the MASK_WEIGHT column. This can be overridden by using the maskwt parameter, which gives a mask weight map to be used for all events. [This parameter should not be used for event data taken during slews.] For DPHs, the mask weighting is also specified using the maskwt parameter.
The user can choose how to bin the data in time. For "uniform" binning, a non-zero time bin size indicates that every time bin should have the same size. Beginning with the start of the first time interval, time bins edges are placed at times according to the formula T = N*TIMEDEL. A value of timedel=0.0 indicates that all input data should be summed into a single output time bin.
For "gti" binning, the user specifies the desired bins using the gtifile parameter, which is in the standard GTI format. Adjoining good time intervals are not merged when using this method. The timedel bin size is ignored. Note that the 'minfracexp' parameter is always honored. If it is important to preserve all requested bins, even if they have zero exposure, then set minfracexp=0.
For "snr" and "highsnr" binning, the user specifies a signal-to-noise ratio threshold with the snrthresh parameter. While the events in a time bin are being accumulated, and the total signal to noise ratio reaches the threshold, a new time bin is started. When timedel=0, both the "snr" and "highsnr" binning methods behave the same way, but they behave differently when timedel is non-zero, as explained below.
To specify a maximum signal to noise ratio then use "snr" binning and set timedel to the maximum time bin size before a new bin is started. Resulting time bins will never be larger than timedel, but may be smaller if the source is detected within a shorter time interval. When the source is detected, each bin will tend to have the same significance (given by snrthresh); when the source is not detected, each bin will tend to have the same time bin size (given by timedel).
To specify a minimum signal to noise ratio then use "highsnr" binning and set timedel to the minimum time bin size. Resulting time bins will have a duration of at least timedel, but may be larger if the source is fainter and it takes a longer period of time to detect it. When the source is detected above snrthresh, each bin will tend to have the same bin size (given by timedel); when the source is not detected, the time bins will be larger.
The "infile" binning method only applies when the input is a DPH. When the binning algorithm is set to "infile," then the time binning of the input file is preserved in the output file. This may be useful, for example, if each DPH row is to be flattened into a detector image, while otherwise preserving the individual exposures.
The "matchlc" binning method will bin the input data to match an existing light curve. The light curve, which is passed in the 'gtifile' parameter, must be a standard OGIP light curve file with enough information to determine the time binning. If the light curve file has a GTI extension, it is ignored. Note that the 'minfracexp' parameter is always honored. If it is important to exactly match the template light curve time bins, even if they have zero exposure, then set minfracexp=0.
For output light curves, the TIME column may refer to the start or the center of the bin, depending on the setting of the 'timepixr' parameter. Output lightcurves also contain the keyword TIMEPIXR which indicates the reference point for light curve time bins. For spectra and detector images / histograms, the TIME column always refers to the start of the accumulation time. In some cases, a separate keyword or column named TSTOP or TIME_STOP is used to indicate the stop of the accumulation time.
For light curves, the start, stop and center times of each bin can be calculated as:
TIME_START = TIME - TIMEPIXR*TIMEDEL TIME_STOP = TIME + (1-TIMEPIXR)*TIMEDEL TIME_CENT = TIME + (0.5-TIMEPIXR)*TIMEDEL
When the user specifies timepixr=0.5, the TIME column marks the center of each bin, and TIME_START and TIME_STOP are one-half of a bin width away. If variable size time bins are requested, then TIMEDEL will be a column instead of a keyword, but the above expressions still hold.
By default, the input file is selected according to its own internal good time intervals, if any are present.
Crude time selection can be performed using the tstart and tstop parameters to the task, which give the start and stop times of accumulation.
More refined selections can be performed specifying the gtifile parameter. A good time interval file (GTI) describes an arbitrary number of intervals by specifying the start and stop times. The intersection of the input files' GTIs, the user-provided gtifile, and the user-provided tstart/tstop parameters, are used to select input data by time. For input DPH (survey) data, the time interval of each input DPH must overlap with the total good time intervals by a large enough amount, and must never straddle more than one output bin.
The DPH overlap time required is determined by the min_dph_frac_overlap, min_dph_time_overlap and max_dph_time_nonoverlap parameters. Care should be taken when altering the overlap parameters, especially when the properties of the source and the background are not constant with time. For example, if a source becomes earth-occulted during the DPH, and a corresponding occultation GTI was input to batbinevt, then the background will have the full exposure, but the source will only have a fractional exposure, i.e. the exposure is ambiguous. For exposure purposes, batbinevt records the full exposure of all DPHs that pass the overlap tests, including any non-overlap intervals. The output GTI, however, retains the user-requested good time intervals.
batbinevt assumes that detector counts are Poisson-distributed, and propagates the errors to the output. However, if the input is a modeled background (e.g. from batclean), then the output uncertainties will be set to zero. This behavior is governed by the HDUCLAS2 keyword in the input DPH file: modeled background maps should have HDUCLAS2 = 'PREDICTED'.
Generally speaking, the formats of the output files should be compatible with OGIP-standard software, where applicable. The output columns are described below. Some columns appear only with certain output types, indicated by the "Outtype" phrase. The units and data type are also given.
1. Uniform binning of 0.1 seconds in the 15-195 keV energy range (light curve is weighted i.e. background subtracted)
batbinevt infile.evt outfile.lc LC 0.1 uniform 15-195
("uniform" binning means uniformly sampled (=0.1s) bins)
2. Two-band light light curve for 15-50 and 50-195 keV (otherwise same as above)
batbinevt infile.evt outfile.lc LC 0.1 uniform 15-50,50-195
(the energy bins can be specified as either an ASCII list or a file name with the energy bins)
3. Binning by constant signal to noise (threshold = 6 sigma)
batbinevt infile.evt outfile.lc LC 0 snr 15-195 snrthresh=6.0
(When the "snr" time binning method is specified, a zero time binning is ignored.)
4. Binning by constant signal to noise (threshold = 6 sigma, maximum bin size of 10 seconds)
batbinevt infile.evt outfile.lc LC 10 snr 15-195 snrthresh=6.0
(When the "snr" time binning method is specified, a non-zero time binning indicates the maximum bin size that is imposed.)
5. Selecting the times by hand (0.1 second uniform bins, 15-195 keV)
batbinevt infile.evt outfile.lc LC 0.1 uniform 15-195 tstart=$START tstop=$STOP
(only include data from $START to $STOP)
6. Applying your own binning (0.1 second uniform bins, 15-195 keV) (must make a Good Time Interval (GTI) named mygti.gti)
batbinevt infile.evt outfile.lc LC 0.1 gti 15-195 gtifile=mygti.gti
(The "gti" time binning means that the bins are taken from the GTI file. When the time binning is not "gti" the GTI file is still useful to select data by time.)
7. Unweighted light curve (with no background subtraction)
batbinevt infile.evt outfile.lc LC 0.1 uniform 15-195 weighted=no
(The weighted parameter decides whether mask weighting is applied or not.)
8. Change output units to counts instead of counts/s.
batbinevt infile.evt outfile.lc LC 0.1 uniform 15-195 outunits=count
(The outunits parameter can be either COUNT or RATE.)
9. Total spectrum, in user-specified energy bins
batbinevt infile.evt outfile.pha PHA 0 uniform 15-25,25-50,50-100,100-195
(A time bin size of 0 means that the entire data set should be accumulated into one total spectrum.
The energy bins can be specified as either an ASCII list or a file name with the energy bins. With a few bins it is easier to give an ASCII list.)
10. Total spectrum, with energy bins given by EBOUNDS extension in myebounds.fits
batbinevt infile.evt outfile.pha PHA 0 uniform myebounds.fits
(Here the energy bins are given in a file with an EBOUNDS extension.)
11. Spectrum every 100 seconds, using EBOUNDS extension
batbinevt infile.evt outfile.pha PHA 100.0 uniform myebounds.fits
12. Binning by constant signal to noise (threshold = 6 sigma)
batbinevt infile.evt outfile.pha PHA 0 snr myebounds.fits snrthresh=6.0
(The threshold applies to total spectrum, not any one bin.)
13. Selecting the times by hand
batbinevt infile.evt outfile.pha PHA 0 uniform myebounds.fits tstart=$START tstop=$STOP
(Only includes data from $START to $STOP)
14. Applying your own binning, say from Bayesian Blocks analysis (must make a Good Time Interval (GTI) named mygti.gti)
batbinevt infile.evt outfile.pha PHA 0 gti myebounds.fits gtifile=mygti.gti
(The "gti" time binning means that the bins are taken from the GTI file. When the time binning is not "gti" the GTI file is still useful to select data by time.)
15. Unweighted spectrum (with no background subtraction)
batbinevt infile.evt outfile.pha PHA 0 uniform myebounds.fits weighted=no
(The weighted parameter decides whether mask weighting is applied or not.)
16. Change output units to counts instead of counts/s.
batbinevt infile.evt outfile.pha PHA 0 uniform myebounds.fits outunits=count
(The outunits parameter can be either COUNT or RATE.)
17. Accumulate mask weighted light curve from DPH (must have generated mask weight image maskwt.img for source position of interest)
batbinevt infile.dph outfile.lc LC 0 infile 14.0-194.9 maskwt=maskwt.img
(Note that energy bins must be exact to within 0.1 keV. The "infile" for the time binning algorithm indicates that the input file binning should be replicated in the output.)
18. Accumulate total mask weighted spectrum from DPH
batbinevt infile.dph outfile.pha PHA 0 uniform infile.dph maskwt=maskwt.img
(Note that EBOUNDS extension from infile is used to generate energy bin edges.)
19. Accumulate total mask weighted spectrum with user-designed bins
batbinevt infile.dph outfile.pha PHA 0 gti infile.dph maskwt=maskwt.img
20. Accumulate raw light curve from DPH (no mask weighting)
batbinevt infile.dph outfile.lc LC 0 infile 14.0-194.9 weighted=no
21. Accumulate raw spectrum from DPH (no mask weighting)
batbinevt infile.dph outfile.pha PHA 0 uniform infile.dph weighted=no
22. Make total DPH from event data
batbinevt infile.evt outfile.dph DPH 0 uniform myebounds.fits
(myebounds.fits should contain the desired energy binning. A time bin size of 0 indicates that the total DPH should be constructed.)
23. Make total DPI from event data (15-195 keV)
batbinevt infile.evt outfile.dpi DPI 0 uniform 15-195
24. Make many DPIs from event data (100 second binning)
batbinevt infile.evt outfile.dpi DPI 100 uniform 15-195
(Output file is stored as one DPI per image extension.) One can also use:
batbinevt infile.evt outfile.dpi DPITAB 100 uniform 15-195
(which will put many DPIs into one extension as a table.)
25. Making DPHs from event data is accomplished with this command
batbinevt infile.evt outfile.dph DPH 0 uniform myebounds.fits
(making more than one or two DPHs in this way is not recommended, since it requires a large amount of computer memory).
batbinevt can be used to "flatten" detector plane histograms in various ways.
26. Make total DPH (add all DPH rows into a single DPH row).
batbinevt infile.dph outfile.dph DPH 0 uniform infile.dph
(The energy binning of infile.dph means that the energy binning of the input file is preserved in the output).
27. Make total DPI (add all DPH rows into a single detector image).
batbinevt infile.dph outfile.dpi DPI 0 uniform 14.0-194.9
(Only energies from 14.0-194.9 are kept in the detector image.)
28. Make one DPI for each DPH (flatten by energy)
batbinevt infile.dph outfile.dpi DPITAB 0 infile 14.0-194.9
("infile" time binning indicates to preserve input file time bins. The output file is a table of DPIs, one per FITS row). This command creates one DPI per image extension.
batbinevt infile.dph outfile.dpi DPI 0 infile 14.0-194.9
(either is compatible with the batfftimage imaging software)
29. Make new DPHs by collapsing some energy bins. This command makes approximate bins from 15-25,25-50,50-100 and 100-200 keV.
batbinevt infile.dph outfile.dph DPH 0 infile 14-26,26-51.1,51.1-101.2,101.2-194.9
(Note energy bins must agree to within 0.1 keV of input binning)
It is not advisable to make more than one full-sized (>80 energy channels) DPH because the memory storage requirements are prohibitive.
extractor, batmaskwtevt, batmaskwtimg