NAME

USAGE

DESCRIPTION

The nicerl2-screen task applies standard NICER-recommended screening to an observation data set that has already been processed by nicerl2. This is a convenience task that helps to apply multiple screenings to an existing dataset without needing to completely re-run nicerl2 again.

As noted, this is a convenience task. The user can still get all the same functionality by running nicerl2 directly with various options; this task helps automate screening.

All of the screening options available to nicerl2 are available to this task. In addition, nicerl2-screen as several standard screening criteria sets which help perform repeatable analysis. Especially after the NICER light leak, starting in May 2023, the NICER team recommends separating data into orbit day and orbit night sections, and this task can aid with that effort.

The standard screening sets are specified on the comand line using the "stdfilter" parameter,

• "night" - after the light leak, orbit night data only with conservative screening
  before the light leak, all data
• "day" - after the light leak, orbit day data only with looser screening
  before the light leak, no data are selected
• "all" - selects all of the data, with conservative screening

nicerl2-screen also applies a filename suffix to the cleaned event file to aid in keeping different screened data sets separate. For example, when you select "stdfilter=day" the event file name will be "niNNNNNNNNNN_0mpu7_cl_day.evt", and when you select "stdfilter=night" the event file name will be "niNNNNNNNNNN_0mpu7_cl_night.evt". You can override the default behavior at any time by setting the evtsuffix parameter to any string that you desire, or NONE to have no suffix.

After setting / resetting any screening parameters, nicerl2-screen calls the nicerl2 task with "tasks=SCREEN", indicating that it should only screen the data and not re-calibrate or re-create the filter file. Thus, the operation should be fairly fast. Also, based on this the user could simply run nicerl2 themselves with any non-default screening parameters, but they would lose the automatic setting of standard parameter sets.

STANDARD SCREENING SETS

As noted above, nicerl2-screen can enable a set of screening criteria by choosing specific screening sets with the "stdfilter" parameter. This section describes what happens for each of those standard sets.

stdfilter=ALL or stdfilter=STD

When stdfilter=ALL or stdfilter=STD, all standard nicerl2 screening defaults are used. Any non-default screening parameters specified on the nicerl2-screen command line are also passed along to nicerl2.

The essence of the "ALL" screening is to keep all data, both orbit day and orbit night, but implement fairly strict data quality screening, including low undershoots, low overshoots, nearly no data losses, and well behaved individual detectors.

stdfilter=NIGHT

When stdfilter=NIGHT, the screening for orbit night is used.

For data before the optical light leak of May 2023, this is the standard screening which will select all data, including both orbit day and orbit night. This is because the detector threshold was kept at its "night" value before the onset of the optical light leak.

For data after the optical light leak, this standard screening will select only data with the detector threshold in its "night" setting.

Overall, this standard set implements the same conservative screening as for the "ALL" setting, described above.

• evtsuffix="night" - sets event filename suffix to indicate night
• threshfilter="NIGHT" - selects data with orbit night threshold setting

stdfilter=DAY

When stdfilter=DAY, the screening for orbit day is used.

For data before the optical light leak of May 2023, this screening will produce no good data at all because the "day" detector threshold was not used before the light leak.

For data after the optical light leak, this standard screening will select only data with the detector threshold in its "day" setting.

Overall, this standard set implements a much looser screening that allows higher undershoots, more data losses, and higher noise levels. In addition, this screening set applies autoscreening on a finer time grid (~250 seconds instead of an entire pointing GTI), in order to accomodate rapidly varying lighting conditions.

These loosened screening criteria admit more data during orbit day, and prefer to select individual detectors with some data losses. This allows some data to be recovered at the loss of some data quality and flux calibration.

• evtsuffix="day" - sets event filename suffix to indicate night
• threshfilter="DAY" - selects data with orbit night threshold setting
• autoscreen_tseg=100 - finer segmentation of pointing GTI for autoscreening
• underonly_range=0-1500 - wider tolerance for mean undershoot rate
• underonlyscr=5.0:1000:0:650 - wider tolerance for per-detector undershoots, 0-650 ct/s/FPM hard range
• noise25scr=5.0:1.0 - wider tolerance for noise peak
• noiseextscr=5.0:1.0 - wider tolerance for extended noise peak
• mpugtiscr=3.0:1.0:0:20 - wider tolerance for shredded GTIs (lost data)
• lowmemscr=NONE - do not filter by absolute LOWMEM FIFO data loss counts
• lowmemfrscr=0:1.0:0:0.05 - allow up to 5% fractional losses by LOWMEM FIFO

PARAMETERS

indir [filename]

Input directory name. The directory should be a single NICER observation directory, which in turn contains xti/{events_uf,events_cl,hk,auxil} subdirectories.

ufdir = "$INDIR/xti/event_uf" [filename]

Subdirectory containing per-MPU "uf" event files, which are the input to the task. This parameter is subject to pattern substitutions $INDIR and $CLDIR as described above.

cldir = "$INDIR/xti/event_cl" [filename]

Subdirectory where the output files as listed above are placed. This parameter is subject to pattern substitution $INDIR as described above.

ufafile = "$CLDIR/ni$OBSID_0mpu7_ufa.evt" [filename]

Name of the master "ufa" event file to be created. This parameter is subject to pattern substitutions $INDIR, $CLDIR and $OBSID as described above.

clfile = "$CLDIR/ni$OBSID_0mpu7_cl$EVTSUFFIX.evt" [filename]

Name of the master "cl" event file to be created. This parameter is subject to pattern substitutions $INDIR, $CLDIR and $OBSID as described above. The $EVTSUFFIX field is replaced with any value passed in the 'evtsuffix' parameter.

mkfile = "$INDIR/auxil/ni$OBSID.mkf" [filename]

Name of the MKF filter file, to be used as input. This parameter is subject to pattern substitutions $INDIR, $CLDIR and $OBSID as described above.

(evtsuffix = "NONE") [string]

Suffix to apply to the output cl file. This substitution only occurs if the $EVTSUFFIX shortcut pattern appears in the clfile, which is the default. This is an easy way to give your output file a custom suffix. If evtsuffix=NONE, then no suffix is applied. If the suffix does not have a "_" prefix, then one is added automatically.

(stdfilter= "STD") [string]

Decide which standard filtering set to apply, one of STD ALL DAY NIGHT, as described above.

detlist="launch" [string]

Detector selection expression, as described in the documentation for nifpmsel.

(nicersaafilt = "YES") [boolean]

For nimaketime, apply NICER_SAA filtering? .

(saafilt = "NO") [boolean]

For nimaketime, apply SAA filtering?

(trackfilt = "YES") [boolean]

For nimaketime, apply pointing tracking filtering?

(st_valid = "YES") [boolean]

For nimaketime, require star tracker valid solution?

(ang_dist=0.015) [real]

For nimaketime, apply ANG_DIST filtering (degrees). ANG_DIST must be less than this value.

(elv=15) [real]

For nimaketime, apply ELV filtering (degrees). ELV must be greater than this value.

(br_earth=30) [real]

For nimaketime, apply BR_EARTH filtering (degrees). BR_EARTH must be greater than this value.

(cor_range="*-*") [string]

For nimaketime, apply COR_SAX filtering (GeV/c). Specify a range A-B.

(underonly_range="0-500") [string]

For nimaketime, apply undershoot count rate range per module. Specify a range A-B.

(overonly_range="0-30") [string]

For nimaketime, apply overshoot count rate range per module. Specify a range A-B.

(overonly_expr="NONE") [string]

For nimaketime, apply curve-base overshoot filtering as an expression. The maximum value of overonly_range is substituted for OVERONOLY_NORM (or 1.0 if no maximum is specified).

(min_fpm=7) [integer]

For nimaketime, apply NUM_FPM_ON filtering.

(max_lowmem=0.0) [real]

Maximum value of TOT_LOWMEM_FIFO lost events, in units of events per second, or 0 to disable. The NICER team recommends to use per-detector autoscreening (lowmemfrscr) rather than this parameter.

(thresh_range="-3.0-3.0") [string]

Range of NICER lower-level threshold settings to include. This is the array-average relative threshold setting, where 0.0 indicates the nominal threshold level, and the units correspond to the flight relative threshold offset value. For NICER optical light leak conditions, it would be typical to use a range of "-3.0-38" to include both nominal and "+35" settings, and "32-38" to include just the daytime threshold settings.

(threshfilter="NIGHT") [string]

A shortcut to select a certain desired threshold range One of "ALL", "DAY" or "NIGHT". "ALL" indicates the entire range of thresholds, "NIGHT" is -3.0-3.0 (default) and "DAY" is 32.0-38.0.

(mingti=5.0) [real]

Minimum GTI size in seconds for GTI filtering. This applies to any telemetry-selected filtering criteria (i.e. not user expressions or user GTIs).

(erodedilate=5.0) [real]

Specify the "erodedilate" parameter for GTI filtering of GTI rows. This applies to any telemetry-selected filtering criteria (i.e. not user expressions or user GTIs).

(gtifiles="NONE") [string]

Apply additional GTI filters. If you have done external filtering and produced a GTI file, you can merge with the nimaketime GTI. Either a comma-separated list of files or an @filelist.lis file. All GTIs (including the maketime GTI) are combined using "AND" (intersection) merge. A value of "NONE" indicates no additional GTI filtering.

(pirange="20:1500") [string]

For nicermergeclean, pulse height screening criteria to apply. To select PI values A to B use "A:B" notation. The asterisk can be used to select the endpoints. For example 20:* indicates a PI range of 20 to the maximum. Either low:high or low-high notation is allowed.

(trumpetfilt=YES) [boolean]

Apply standard background PI_RATIO filtering.

(timerange="DEFAULT") [string]

Basic range of TIME column to include from input file, in the form "A-B" where A and B are the min and max values to accept, inclusive. A "*" can be used to mean "to infinity", so the default of "100-*" means only allow through any events with TIME > 100, and no upper limit.

(autoscreen=YES) [boolean]

Automatically apply per-FPM and per-MPU screening criteria? If yes, then the niautoscreen task is used to deselect detectors with problematic conditions during individual pointing snapshots. If no, then niautoscreen is not used, but the other filtering criteria are used to screen out global bad times.

(autoscreen_tseg = DEFAULT) [string]

When performing autoscreening, this setting controls whether data are divided into smaller time segments. For pointing GTI entries that are too large, break entries up into segments of the duration tseg (approximately). A value of 0 disables segmentation.

(underonlyscr="DEFAULT") [string]

Screening criteria for the high undershoot condition. The value is of the form "nsigma:rbuf:min:max". Set to NONE to disable, or DEFAULT to use the niautoscreen default values. See niautoscreen help file for more details.

(overonlyscr="DEFAULT") [string]

Screening criteria for the high overshoot condition. The value is of the form "nsigma:rbuf:min:max". Set to NONE to disable, or DEFAULT to use the niautoscreen default values. See niautoscreen help file for more details.

(noise25scr="DEFAULT") [string]

Screening criteria for the high noise peak rate condition. The value is of the form "nsigma:rbuf:min:max". Set to NONE to disable, or DEFAULT to use the niautoscreen default values. See niautoscreen help file for more details.

(noiseextscr="DEFAULT") [string]

Screening criteria for the 0.3-0.7 keV "X-ray" band. This band may occasionally have high count rates associated with an extended noise peak, which indicates detector problems. The value is of the form "nsigma:rbuf:min:max". Set to NONE to disable, or DEFAULT to use the niautoscreen default values. See niautoscreen help file for more details.

(mpugtiscr="DEFAULT") [string]

Screening criteria for the per-MPU shredded GTI condition. The value is of the form "nsigma:rbuf:min:max". Set to NONE to disable, or DEFAULT to use the niautoscreen default values. See niautoscreen help file for more details.

(roundrobbinscr="DEFAULT") [string]

Screening criteria for the "round robbin" condition. The value is of the form "nsigma:rbuf:min:max". Set to NONE to disable, or DEFAULT to use the niautoscreen default values. See niautoscreen help file for more details.

(lowmemscr="DEFAULT") [string]

Screening criteria for the LOWMEM FIFO loss amount. This is the number of lost events per GTI. The value is of the form "nsigma:rbuf:min:max". Set to NONE to disable, or DEFAULT to use the niautoscreen default values. See niautoscreen help file for more details. The NICER team now recommends to use lowmemfrscr and not this parameter.

(lowmemfrscr="DEFAULT") [string]

Screening criteria for the LOWMEM FIFO fractional loss amount. This is the fraction of LOWMEM FIFO losses compared to the total count rate, in each GTI. The value is of the form "nsigma:rbuf:min:max". Set to NONE to disable, or DEFAULT to use the niautoscreen default values. See niautoscreen help file for more details.

(datamode="so+s+f") [string]

X-ray event type screening, as described in the help for nicerclean.

(keep_overshoots=NO) [boolean]

Set to NO to screen out overshoots, or to YES to permit them.

(keep_undershoots=NO) [boolean]

Set to NO to screen out undershoots, or to YES to permit them.

(keep_forced=NO) [boolean]

Set to NO to screen out forced triggers, or to YES to permit them.

(keep_noisering=NO) [boolean]

Set to NO to screen out noise ringers, or to YES to permit them. Note that if noisering_under is set, then the per-FPM undershoot rate is also required to exceed that value before a noise ringer is excluded.

(noisering_under=80) [real]

The per-FPM undershoot rate, above which events with the noise ringer bit flag set are screened out. If noisering_under=0, then keep_noisering is followed always, regardless of undershoot rate.

(nicerclean_args="NONE") [string]

Any additional arguments to nicerclean, such as "EVENT_FLAGS=bx1x000 fastsig=250.0". See the help file for nicer clean for more information. The gtifile, trumpetfilt, and pirange parameters are automatically passed and there is no need to specify them again with nicerclean_args.

(incremental="NO") [boolean]

If yes, then avoid calibration and other intensive processing where possible. Files are checked for their calibration status keywords and/or software version numbers, and if certain requirements are met, the existing files are used without change.

(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]

Amount of verbosity of the task. For chatter=0, no output is printed. For chatter=5, debugging output is printed.

(history = YES) [boolean]

If history = YES, then a set of HISTORY keywords will be written to the header of the specified HDU in the output file to record the value of all the task parameters that were used to produce the output file.

EXAMPLES

1. Apply NICER calibration and screening to data from observation 1706221428 for orbit day.

  nicerl2-screen indir=1706221428 stdfilter=DAY clobber=YES 

The input directory is a NICER observation number 1706221428. The output files are placed in the observation directory under 1706221428/xti/event_cl/, including the cleaned event file which will be named ni1706221428_0mpu7_cl_day.evt. 2. Apply NICER calibration and screening to data from observation 1706221428 for orbit night

  nicerl2-screen indir=1706221428 stdfilter=NIGHT clobber=YES 

The input directory is a NICER observation number 1706221428. The output files are placed in the observation directory under 1706221428/xti/event_cl/, including the cleaned event file which will be named ni1706221428_0mpu7_cl_night.evt.

SEE ALSO

nicerl2

nimaketime

nicermergeclean

nicerclean

nifpmsel

niautoscreen

LAST MODIFIED