Synopsis
lc_sigma_clip - remove flares from a light curve using an iterative sigma-clipping algorithm
Syntax
lc_sigma_clip(filename, [outfile=None], [sigma=3.0], [minlength=3], [plot=True], [rateaxis="y"], [pattern="solid"], [gcol="green"], [pcol="red"], [verbose=1])
Description
The lc_sigma_clip() routine uses a simple iterative sigma-clipping routine to detect and remove flares from a lightcurve. For more information see the Filtering Lightcurves thread. The deflare tool can be used to run this algorithm from the command line; see "ahelp deflare" for more information.
Loading the routine
The routine can be loaded into a Python interpreter - such as Sherpa or ipython - by saying:
from lightcurves import *
See "ahelp lightcurves" for more information on the lightcurves module.
Common arguments
The lc_sigma_clip() and lc_clean() routines share a number of common arguments and options. The filename argument - which is the only required argument for either call - is used to specify the name of the light curve to analyze. The required columns for this file are discussed in the "Format of Lightcurves" section below.
Common options between the three routines (i.e. those with the same meaning)
| Option | Default | Meaning |
|---|---|---|
| outfile | None | If set, this gives the name of the GTI file to create. |
| verbose | 1 | Do we display screen output (1) or not (0)? |
| plot | True | Should the light curve be displayed as a plot? |
| pattern | solid | If a GTI file is created as well as a plot, then we indicate the excluded times using regions filled with this pattern. A value of "none" means that the excluded regions will not be shown, otherwise it should be one of: solid, nofill, updiagonal, downdiagonal, horizontal, vertical, crisscross, grid, or polkadot. |
| rateaxis | "y" | Should the light curve (the top plot) be drawn with the count rate along the y axis ("y") or x axis ("x")? |
| gcol | "green" | The color used to display "good" points when drawing the light curve. |
| pcol | "red" | The color used to color regions indicating excluded times (see the pattern argument). |
Although all routines contain an optional sigma argument, the meaning of this parameter is not exactly the same.
Using lc_sigma_clip
The lc_sigma_clip routine performs an iterative sigma-clipping algorithm, removing those points that fall outside the range
mean - n * sigma
to
mean + n * sigma
at each iteration until all data points are within this range. The default value for n is 3.0 but this can be changed using the sigma parameter as described below. This algorithm is robust but not perfect; it can easily "overclean" a noisy lightcurve, or fail to reject any points, and so should not be used blindly.
The two options for lc_sigma_clip are "sigma" and "minlength". The sigma argument determines the value used to clip the count rate data at each iteration, and defaults to 3.0. The minlength option, which defaults to 3, is the minimum number of consecutive bins that must all lie within the final rate limits for that range to be considered good.
How do we use the output GTI file?
If the outfile argument is set, then a GTI file will be created listing those time periods which are considered to be "good" by the algorithm. This file can be used to filter an event file using the following syntax (we assume here that the event file to be filtered is evt2.fits and the output of the routine is called evt.gti):
unix% dmcopy "evt2.fits[@evt.gti]" evt2_filt.fits
A warning about low count-rate lightcurves
The lc_sigma_clip algorithm excludes bins which have a zero count rate, whether it is because the exposure time of the bin is zero or because no counts were detected in this bin. This is because the algorithm is not designed for use with low count-rate data. Therefore the routines should be used with extreme care when applied to data for which zero-rate bins are expected (for example a very-faint source).
A note on times
When run with verbose set to 1, durations are displayed alongside time filters. These values are instructive, but should not be taken as the actual exposure-length of each interval because they may not account for
- the dead-time correction of the observation (DTCOR header keyword);
- exposure variations within the bin due to existing time filters (i.e. the time filters already applied to the observation).
The best way to find out what the final exposure time will be is to create a GTI file, use it to filter the event file, and then look at the EXPOSURE value of the filtered file.
Examples
Example 1
>>> lc_sigma_clip("bg.lc")The default parameters are used to analyze the light curve in the file bg.lc. A plot will be created and information about the calculation, including the final filter range, is printed to the screen.
The plot can be printed using the Matplotlib savefig command: for example
>>> import matplotlib.pyplot as plt
>>> plt.savefig("bg.lc.ps")will create a postscript plot.
Example 2
>>> lc_sigma_clip("bg.lc", outfile="clip.gti")Since the outfile parameter is set, the routine creates a GTI file (clip.gti) that represents the "good" times calculated by the algorithm. After writing out the file the filtered-out times will be displayed on the plot using solid red regions.
The output file can be used to filter an event file (say evt2.fits) like so:
unix% dmcopy "evt2.fits[@clip.gti]" evt2_filt.fits
Example 3
>>> lc_sigma_clip("bg.lc", outfile="bg.gti", pattern="none")Create a GTI file (bg.gti) but do not use regions to indicate the excluded times in the count-rate plot.
Example 4
>>> lc_sigma_clip("bg.lc", outfile="bg.gti", pattern="grid",
pcol="orange")Create a GTI file (bg.gti) and use an orange grid fill to indicate the excluded times in the count-rate plot.
Example 5
>>> lc_sigma_clip("bg.lc", outfile="bg.gti", verbose=0, plot=False)Create a GTI file (bg.gti), but do not create any screen output or a plot.
Format of Lightcurves
The lc_sigma_clip routine is designed to work with light curves that were created using the CIAO dmextract tool, run with the opt parameter set to ltc1. They should however also work with any file which has the following columns:
- TIME
- TIME_MIN and TIME_MAX (both columns are optional)
- COUNT_RATE or, if not present, RATE
If the file contains OBJECT and OBS_ID keywords then these will be used to label the plot.
Changes in the 4.11.4 (2019) release
Labels with underscores in them are now properly displayed by Matplotlib.
Changes in the 4.11.2 (April 2019) release
Switch to Matplotlib
The plots are now created with Matplotlib rather than ChIPS.
Changes in the scripts 4.9.3 (May 2017) release
The lc_sigma_clip routine has been updated so that it will run under Python 3.5 (prior to this it could occasionally fail, depending on the parameters and the input data).
About Contributed Software
This script is not an official part of the CIAO release but is made available as "contributed" software via the CIAO scripts page. Please see this page for installation instructions.
Bugs
See the bugs page for this script on the CIAO website for an up-to-date listing of known bugs.
Refer to the CIAO bug pages for an up-to-date listing of known issues.
See Also
- contrib
- lc_clean, lightcurves
- tools::acis
- acis_detect_afterglow, acis_streak_map, acisreadcorr, destreak, multi_chip_gti
- tools::aspect
- get_dither_parameters, monitor_photom
- tools::core
- dmcopy
- tools::timing
- axbary, deflare, glvary, gti_align, pfold