lightcurves

Context: contrib

Synopsis

lightcurves - routines to remove periods of anomalously high (or low) count rates in a lightcurve

Syntax

from lightcurves import *

The module provides the lc_clean() and lc_sigma_clip() routines.
Please see the deflare tool ("ahelp deflare") if you want to run these
routines from the command line.

Description

The lightcurves module provides two Python routines that can be used to remove periods of high (or low) count rates in a lightcurve. The first - lc_clean() - is designed for use with the ACIS background files and is based on the lc_clean program created by Maxim Markevitch. The second - lc_sigma_clip() - is a simple sigma-clipping routine. See "ahelp lc_clean" and "ahelp lc_sigma_clip" for more information about the individual routines.

The routines are usable from the command line using the deflare tool, as described by "ahelp deflare".

Loading the module

The module can be loaded into a Python interpreter - such as Sherpa or ipython - by saying:

from lightcurves import *

This only needs to be done once per session. Loading the module will make available the lc_clean and lc_sigma_clip routines.

The two routines use different algorithms to detect flares in a light curve. Both are intended to be used with data that has relatively high count rates (i.e. ones in which bins are not expected to have no counts in them). The default mode is to create a plot showing the selected periods of the light curve, and to display the filter on screen. They can also be used to create a GTI file which encodes this information and can be used to filter the event file to remove these periods.

Examples

Example 1

>>> import matplotlib.pyplot as plt
>>> lc_clean("bg.lc")
>>> plt.figure()
>>> lc_sigma_clip("bg.lc")

Display the results of the two algorithms in two windows to aid comparison of the results.

Example 2

>>> lc_clean("bg.lc", outfile="clean.gti")

Filter the light curve in the file bg.lc using the lc_clean algorithm and create a GTI file (clean.gti). This file can then be used to filter the event file (here assumed to be called evt2.fits) using dmcopy:

unix% dmcopy "evt2.fits[@clean.gti]" evt2.cleaned.fits

Example 3

>>> lc_sigma_clip("bg.lc", outfile="clip.gti")

Filter the light curve in the file bg.lc using the lc_sigma_clip algorithm and create a GTI file (clip.gti). This file can then be used to filter the event file (here assumed to be called evt2.fits) using dmcopy:

unix% dmcopy "evt2.fits[@clip.gti]" evt2.cleaned.fits

Format of Lightcurves

The routines are 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 (optional)
COUNT_RATE or, if not present, RATE
EXPOSURE (optional for lc_sigma_clip, required for lc_clean)

If the file contains OBJECT and OBS_ID keywords then these will be used to label the plot.

Changes in the 4.12.1 (December 2019) release

The plots have been updated to work with Matplotlib version 3.

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 December 2011 release

The routines have been updated to work with CIAO 4.4.

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.