Light Curves

lightcurve() fits the charateristics of a source (flux, TS, etc.) in a sequence of time bins. This method uses the data selection and model of a baseline analysis (e.g. the full mission) and is therefore restricted to analyzing time bins that are encompassed by the time selection of the baseline analysis. In general when using this method it is recommended to use a baseline time selection of at least several years or more to ensure the best characterization of background sources in the ROI.

When fitting a time bin the method will initialize the model to the current parameters of the baseline analysis. The parameters to be refit in each time bin may be controlled with free_background, free_sources, free_radius, free_params, and shape_ts_threshold options.

Examples

# Generate a lightcurve with two bins
lc = gta.lightcurve('sourceA', nbins=2)

# Generate a lightcurve with 1-week binning
lc = gta.lightcurve('sourceA', binsz=86400.*7.0)

# Generate a lightcurve freeing sources within 3 deg of the source
# of interest
lc = gta.lightcurve('sourceA', binsz=86400.*7.0, free_radius=3.0)

# Generate a lightcurve with arbitrary MET binning
lc = gta.lightcurve('sourceA', time_bins=[239557414,242187214,250076614],
                    free_radius=3.0)

Optimizing Computation Speed

By default the lightcurve method will run an end-to-end analysis in each time bin using the same processing steps as the baseline analysis. Depending on the data selection and ROI size each time bin may take 10-15 minutes to process. There are several options which can be used to reduce the lightcurve computation time. The multithread option splits the analysis of time bins across multiple cores:

# Split lightcurve across all available cores
lc = gta.lightcurve('sourceA', nbins=2, multithread=True)

# split lightcurve across 2 cores
lc = gta.lightcurve('sourceA', nbins=2, multithread=True, nthread=2)

Note that when using the multithread option in a computing cluster environment one should reserve the appropriate number of cores when submitting the job.

The use_scaled_srcmap option generates an approximate source map for each time bin by scaling the source map of the baseline analysis by the relative exposure.

# Enable scaled source map
lc = gta.lightcurve('sourceA', nbins=2, use_scaled_srcmap=True)

Enabling this option can speed up the lightcurve calculation by at least a factor of 2 or 3 at the cost of slightly reduced accuracy in the model evaluation. For point-source analysis on medium to long timescales (days to years) the additional systematic uncertainty incurred by using scaled source maps should be no more than 1-2%. For analysis of diffuse sources or short time scales (< day) one should verify the systematic uncertainty is less than the systematic uncertainty of the IRFs.

Output

The following tables describe the contents of the method output:

lightcurve Output
Key Type Description
name str Name of Source,
tmin ndarray Lower edge of time bin in MET.
tmax ndarray Upper edge of time bin in MET.
fit_success ndarray Did the likelihood fit converge? True if yes.
config dict Copy of the input configuration to this method.
ts_var float TS of variability. Should be distributed as \(\chi^2\) with \(n-1\) degrees of freedom, where \(n\) is the number of time bins.
lightcurve Source Output
Key Type Description
param_names ndarray Names of spectral parameters.
param_values ndarray Spectral parameter values.
param_errors ndarray Spectral parameters errors.
ts float Source test statistic.
loglike float Log-likelihood of the model evaluated at the best-fit normalization of the source.
loglike_scan ndarray Log-likelihood values for scan of source normalization.
dloglike_scan ndarray Delta Log-likelihood values for scan of source normalization.
eflux_scan ndarray Energy flux values for scan of source normalization.
flux_scan ndarray Flux values for scan of source normalization.
norm_scan ndarray Normalization parameters values for scan of source normalization.
npred float Number of predicted counts from this source integrated over the analysis energy range.
pivot_energy float Decorrelation energy in MeV.
flux float Photon flux (\(\mathrm{cm}^{-2}~\mathrm{s}^{-1}\)) integrated over analysis energy range
flux100 float Photon flux (\(\mathrm{cm}^{-2}~\mathrm{s}^{-1}\)) integrated from 100 MeV to 316 GeV.
flux1000 float Photon flux (\(\mathrm{cm}^{-2}~\mathrm{s}^{-1}\)) integrated from 1 GeV to 316 GeV.
flux10000 float Photon flux (\(\mathrm{cm}^{-2}~\mathrm{s}^{-1}\)) integrated from 10 GeV to 316 GeV.
flux_err float Photon flux uncertainty (\(\mathrm{cm}^{-2}~\mathrm{s}^{-1}\)) integrated over analysis energy range
flux100_err float Photon flux uncertainty (\(\mathrm{cm}^{-2}~\mathrm{s}^{-1}\)) integrated from 100 MeV to 316 GeV.
flux1000_err float Photon flux uncertainty (\(\mathrm{cm}^{-2}~\mathrm{s}^{-1}\)) integrated from 1 GeV to 316 GeV.
flux10000_err float Photon flux uncertainty (\(\mathrm{cm}^{-2}~\mathrm{s}^{-1}\)) integrated from 10 GeV to 316 GeV.
flux_ul95 float 95% CL upper limit on the photon flux (\(\mathrm{cm}^{-2}~\mathrm{s}^{-1}\)) integrated over analysis energy range
flux100_ul95 float 95% CL upper limit on the photon flux (\(\mathrm{cm}^{-2}~\mathrm{s}^{-1}\)) integrated from 100 MeV to 316 GeV.
flux1000_ul95 float 95% CL upper limit on the photon flux (\(\mathrm{cm}^{-2}~\mathrm{s}^{-1}\)) integrated from 1 GeV to 316 GeV.
flux10000_ul95 float 95% CL upper limit on the photon flux (\(\mathrm{cm}^{-2}~\mathrm{s}^{-1}\)) integrated from 10 GeV to 316 GeV.
eflux float Energy flux (\(\mathrm{MeV}~\mathrm{cm}^{-2}~\mathrm{s}^{-1}\)) integrated over analysis energy range
eflux100 float Energy flux (\(\mathrm{MeV}~\mathrm{cm}^{-2}~\mathrm{s}^{-1}\)) integrated from 100 MeV to 316 GeV.
eflux1000 float Energy flux (\(\mathrm{MeV}~\mathrm{cm}^{-2}~\mathrm{s}^{-1}\)) integrated from 1 GeV to 316 GeV.
eflux10000 float Energy flux (\(\mathrm{MeV}~\mathrm{cm}^{-2}~\mathrm{s}^{-1}\)) integrated from 10 GeV to 316 GeV.
eflux_err float Energy flux uncertainty (\(\mathrm{MeV}~\mathrm{cm}^{-2}~\mathrm{s}^{-1}\)) integrated over analysis energy range
eflux100_err float Energy flux uncertainty (\(\mathrm{MeV}~\mathrm{cm}^{-2}~\mathrm{s}^{-1}\)) integrated from 100 MeV to 316 GeV.
eflux1000_err float Energy flux uncertainty (\(\mathrm{MeV}~\mathrm{cm}^{-2}~\mathrm{s}^{-1}\)) integrated from 1 GeV to 316 GeV.
eflux10000_err float Energy flux uncertainty (\(\mathrm{MeV}~\mathrm{cm}^{-2}~\mathrm{s}^{-1}\)) integrated from 10 GeV to 316 GeV.
eflux_ul95 float 95% CL upper limit on the energy flux (\(\mathrm{MeV}~\mathrm{cm}^{-2}~\mathrm{s}^{-1}\)) integrated over analysis energy range
eflux100_ul95 float 95% CL upper limit on the energy flux (\(\mathrm{MeV}~\mathrm{cm}^{-2}~\mathrm{s}^{-1}\)) integrated from 100 MeV to 316 GeV.
eflux1000_ul95 float 95% CL upper limit on the energy flux (\(\mathrm{MeV}~\mathrm{cm}^{-2}~\mathrm{s}^{-1}\)) integrated from 1 GeV to 316 GeV.
eflux10000_ul95 float 95% CL upper limit on the energy flux (\(\mathrm{MeV}~\mathrm{cm}^{-2}~\mathrm{s}^{-1}\)) integrated from 10 GeV to 316 GeV.
dnde float Differential photon flux (\(\mathrm{cm}^{-2}~\mathrm{s}^{-1}~\mathrm{MeV}^{-1}\)) evaluated at the pivot energy.
dnde100 float Differential photon flux (\(\mathrm{cm}^{-2}~\mathrm{s}^{-1}~\mathrm{MeV}^{-1}\)) evaluated at 100 MeV.
dnde1000 float Differential photon flux (\(\mathrm{cm}^{-2}~\mathrm{s}^{-1}~\mathrm{MeV}^{-1}\)) evaluated at 1 GeV.
dnde10000 float Differential photon flux (\(\mathrm{cm}^{-2}~\mathrm{s}^{-1}~\mathrm{MeV}^{-1}\)) evaluated at 10 GeV.
dnde_err float Differential photon flux uncertainty (\(\mathrm{cm}^{-2}~\mathrm{s}^{-1}~\mathrm{MeV}^{-1}\)) evaluated at the pivot energy.
dnde100_err float Differential photon flux uncertainty (\(\mathrm{cm}^{-2}~\mathrm{s}^{-1}~\mathrm{MeV}^{-1}\)) evaluated at 100 MeV.
dnde1000_err float Differential photon flux uncertainty (\(\mathrm{cm}^{-2}~\mathrm{s}^{-1}~\mathrm{MeV}^{-1}\)) evaluated at 1 GeV.
dnde10000_err float Differential photon flux uncertainty (\(\mathrm{cm}^{-2}~\mathrm{s}^{-1}~\mathrm{MeV}^{-1}\)) evaluated at 10 GeV.
dnde_index float Logarithmic slope of the differential photon spectrum evaluated at the pivot energy.
dnde100_index float Logarithmic slope of the differential photon spectrum evaluated at 100 MeV.
dnde1000_index float Logarithmic slope of the differential photon spectrum evaluated evaluated at 1 GeV.
dnde10000_index float Logarithmic slope of the differential photon spectrum evaluated at 10 GeV.

Reference/API

GTAnalysis.lightcurve(name, **kwargs)

Generate a lightcurve for the named source. The function will complete the basic analysis steps for each bin and perform a likelihood fit for each bin. Extracted values (along with errors) are Integral Flux, spectral model, Spectral index, TS value, pred. # of photons. Note: successful calculation of TS:subscript:var requires at least one free background parameter and a previously optimized ROI model.

Parameters:
  • name (str) – source name
  • binsz (float) – Set the lightcurve bin size in seconds. (default : 86400.0)
  • free_background (bool) – Leave background parameters free when performing the fit. If True then any parameters that are currently free in the model will be fit simultaneously with the source of interest. (default : False)
  • free_params (list) – Set the parameters of the source of interest that will be re-fit in each time bin. If this list is empty then all parameters will be freed. (default : None)
  • free_radius (float) – Free normalizations of background sources within this angular distance in degrees from the source of interest. If None then no sources will be freed. (default : None)
  • free_sources (list) – List of sources to be freed. These sources will be added to the list of sources satisfying the free_radius selection. (default : None)
  • make_plots (bool) – Generate diagnostic plots. (default : False)
  • max_free_sources (int) – Maximum number of sources that will be fit simultaneously with the source of interest. (default : 5)
  • multithread (bool) – Split the calculation across number of processes set by nthread option. (default : False)
  • nbins (int) – Set the number of lightcurve bins. The total time range will be evenly split into this number of time bins. (default : None)
  • nthread (int) – Number of processes to create when multithread is True. If None then one process will be created for each available core. (default : None)
  • outdir (str) – Store all data in this directory (e.g. “30days”). If None then use current directory. (default : None)
  • save_bin_data (bool) – Save analysis directories for individual time bins. If False then only the analysis results table will be saved. (default : True)
  • shape_ts_threshold (float) – Set the TS threshold at which shape parameters of sources will be freed. If a source is detected with TS less than this value then its shape parameters will be fixed to values derived from the analysis of the full time range. (default : 16.0)
  • systematic (float) – Systematic correction factor for TS:subscript:var. See Sect. 3.6 in 2FGL for details. (default : 0.02)
  • time_bins (list) – Set the lightcurve bin edge sequence in MET. This option takes precedence over binsz and nbins. (default : None)
  • use_local_ltcube (bool) – Generate a fast LT cube. (default : True)
  • use_scaled_srcmap (bool) – Generate approximate source maps for each time bin by scaling the current source maps by the exposure ratio with respect to that time bin. (default : False)
  • write_fits (bool) – Write the output to a FITS file. (default : True)
  • write_npy (bool) – Write the output dictionary to a numpy file. (default : True)
Returns:

LightCurve – Dictionary containing output of the LC analysis

Return type:

dict