NAME

niprelflaregti - estimate GTI of PREL flares

USAGE

niprelflaregti infile outfile

DESCRIPTION

niprelflaregti estimates a GTI that can be used in NICER screening, based upon precipitating electron events.

Precipitating electrons are detected when a reconnection or electron scattering event occurs in the earth's magnetosphere, which causes electrons to flow to NICER's orbital location. Unlike trapped charges, precipitating electrons are not trapped, and will likely end their lives when they reach the earth's atmosphere just below NICER's orbit.

Precipitating electrons that NICER detects are largely low energy (<20 keV) and enter through NICERs optical pathway like X-rays do. They are difficult to predict because they do not produce large numbers of high energy charge depositions (>20 keV), which are recorded as overshoot events. Precipitation events tend to occur in the polar horn regions, are highly variable, and can produce very high count rates, hence the name "flares."

Instead of modeling precipitation events as background, the NICER team currently recommends to screen them out.

To do this, the worflow consists of two parts.

It is unlikely the user will need to run this task. Instead they can run the standard tools nicerl2/niprefilter2/nimaketime, which creates the recommended columns and applies the recommended screening.

The task will search for PREL flares by searching for time intervals (or GTIs) where the PREL index exceeds prelthresh. This is the starting point for PREL flares.

Then, the flare GTIs are expanded using the enlarge and dilateerodeo operators of the ftadjustgti task. These tend to expand the GTIs by a set amount (default 10 seconds), as sell as to coalesce any GTIs that are neighboring.

Finally, the task checks the filter file. While certain column values in the filter file are high compared to a nominal threshold the flare interval is expanded. By default, the flare interval is expanded until either the overshoot rate goes below 1.5 ct/s/FPM, or the PREL index value goes below 1.5, or the COR value exceeds 2.5 GeV/c. Note that these are the default values, they can be changed as specified below.

The user can also choose to keep the flare intervals or the non-flare intervals using the "keep" parmeter.

PARAMETERS

infile = "" [string]
File name of input filter (MKF) file. The file is required to have the columns listed below.

outfile = "" [string]
File name of output GTI file.

(keep="NONFLARE") [string]
What the GTI will "keep", either FLARE or NONFLARE. If you are interested in "good" data, set keep=NONFLARE.
(prelcol="PREL_FLARE_INDEX") [string]
Name of the PREL flare index column in the MKF file.

(overcol="FPM_OVERONLY_COUNT") [string]
Name of the overshoot column in the MKF file.

(corcol="COR_SAX") [string]
Name of the COR column in the MKF file.

(prelthresh=4.5) [real]
Threshold PREL index value to detect a PREL flare.

(prelmin=1.5) [real]
Minimum value to search for in PREL index after detecting a PREL flare, used to extend an existing PREL flare.

(overmin=1.5) [real]
Minimum value to search for in overshoots after detecting a PREL flare, used to extend an existing PREL flare.

(cormax=2.5) [real]
Maximum allowed value of COR when extending a GTI.

(enlarge=10) [real]
Amount of time in seconds to add to existing PREL flare before enlarging.

(dilateerode=500) [real]
Amount of "dilate erode" time in seconds to apply to GTI before enlarging. This tends to coalesce neighboring flares into a single one. This operation is done by ftadjustgti.

(cleanup="YES") [boolean]
If yes, then clean up temporary files. If no, temporary files remain. This is typically for debugging.
(clobber = NO) [boolean]
If the output file already exists, then setting "clobber = yes" will cause it to be overwritten.
(chatter = 2) [integer, 0 - 5]
Controls the amount of informative text written to standard output.

EXAMPLES

Estimate a non-flare GTI from the specified filter file.


     niprelflaregti n1234567890.mkf nonflare.gti keep=NONFLARE clobber=YES

SEE ALSO

nicerl2

niprefilter2

niprelflarecalc

nimaketime

ftadjustgti

LAST MODIFIED

Jul 2023