Home

XiP: XSPEC Interactive Plotting Tool

Welcome to the XiP wiki! Created and handled by Aditya Pandya.

Overview

XiP (XSPEC Interactive Plotting Tool) is a Python-based interactive visualization tool designed for XSPEC spectral analysis workflows. It enables users to explore, fit, and visualize X-ray spectral data and models interactively within Jupyter Notebooks. XiP leverages ipywidgets for real-time parameter adjustment and plotting, making it easier to understand the impact of model parameters on spectral fits.

Note: XiP is primarily tailored for eROSITA data but can be adapted for other X-ray datasets with minor modifications.

Use Cases

• Interactive Model Exploration: Adjust model parameters using sliders and instantly see the effect on the fit and residuals.
• Rapid Model Prototyping: Quickly test different model configurations and parameter values before running the MCMC XSPEC fits.
• Simultaneous Source and Background Fitting: Fit source and background spectra together, including support for filter wheel closed (FWC) background models.

Input Parameters

XiP is configured using two main dictionaries: data_config and model_config, along with several optional attributes for customizing the analysis and plotting.

1. data_config (dict)

Defines the data files and directory structure for the analysis.

• Dir: Directory containing the spectral and response files.
• src_file: Filename for the source spectrum (FITS format).
• bkg_file: Filename for the background spectrum (FITS format).
• src_rmf: (Optional) Source response matrix file (RMF).
• src_arf: (Optional) Source ancillary response file (ARF).
• bkg_rmf: (Optional) Background response matrix file (RMF).
• bkg_arf: (Optional) Background ancillary response file (ARF).
• fwc_data: (Optional) FWC model file for instrumental background.

2. model_config (dict)

Defines the XSPEC model(s) and initial parameter values.

• model_name: String specifying the XSPEC model(s). For simultaneous source and background fitting, separate models with a | (e.g., 'TBabs*(vapec+powerlaw)|constant*(apec+TBabs(apec+apec+powerlaw))').
• param_defaults: List of initial values for each free parameter. Each entry can either be:
  • A float: Initial value (parameter is free).
  • A tuple: (initial_value, flag) where flag = -1 freezes the parameter, any other value leaves it free.
• label_list: (Optional) List of legend labels for model components in the plot.

3. Other Parameters and Attributes

Set as attributes on the XSPECInteractivePlot instance after initialization:

• xspec_type: Specifies the analysis mode. Options:
  • 'src': Source only
  • 'bkg': Background only
  • 'src_bkg': Simultaneous source and background
• energy_range: Tuple specifying the energy range (in keV) for analysis (e.g., (0.2, 8.0)).

Example Usage

from XiP import XSPECInteractivePlot

# Data configuration
data_config = {
    'Dir': 'Data/',
    'src_file': 'SRC_spec820_SourceSpec_00001_corr.fits',
    'bkg_file': 'BKG_spec820_SourceSpec_00001_corr.fits',
    'fwc_data': 'TM8_FWC_c010_mod_customized_src.dat',
}

# Model configuration
model_config = {
    'model_name': 'TBabs*(vapec+powerlaw)|constant*(apec+TBabs(apec+apec+powerlaw))',
    'param_defaults': [0.55, 0.1, 1, 1, 1, 1, (0.112061, -1), ...],
}

# Initialize and run
plotter = XSPECInteractivePlot(data_config, model_config, xspec_type='src_bkg', energy_range=(0.2, 8.0))
plotter.run()

Internal Parameters (self.* attributes in XSPECInteractivePlot)

The XSPECInteractivePlot class maintains several internal attributes to manage data, models, and plotting state. Here is a list and description of the most important ones:

1. Data and File Configuration

Attribute	Description
self.Dir	Directory containing the data files.
self.srcfile	Source spectrum file name.
self.bkgfile	Background spectrum file name.
self.src_rmf	Source response matrix file (RMF).
self.src_arf	Source ancillary response file (ARF).
self.bkg_rmf	Background response matrix file (RMF).
self.bkg_arf	Background ancillary response file (ARF).
self.fwc_data	FWC (Filter Wheel Closed) model file for instrumental background.

2. Model Configuration

Attribute	Description
self.model_name	XSPEC model string (or source + background for src_bkg mode).
self.param_defaults	List of initial values (and freeze flags) for model parameters.
self.label_list	List of legend labels for model components.

3. User/Session Settings

Attribute	Description
self.xspec_type	Mode: 'src', 'bkg', or 'src_bkg'.
self.energy_range	(tuple) specifying energy range (keV).
self.chatter	(int) XSPEC verbosity level.
self.perform_fit	(bool) Whether to perform XSPEC fit on the initial parameters set by the user.
self.show_bkg_data	(bool) Whether to show background data in plots.
self.minSig	(int) Minimum significance for spectral binning.
self.maxBins	(int) Maximum number of bins for spectral data.

4. XSPEC Model/Data Objects

Attribute	Description
self.AllData	Reference to XSPEC AllData object.
self.AllModels	Reference to XSPEC AllModels object.
self.m_src	XSPEC Model object for source.
self.m_bkg	XSPEC Model object for background.
self.m_fwc	XSPEC Model object for FWC (if present).
self.model_obj	Temporary reference to current model object.

5. Model Parameter State

Attribute	Description
self.values	List of current parameter values.
self.model_type	List of model types for each parameter (e.g., 'm_src', 'm_bkg', 'm_fwc').
self.comp_names	List of component names for each parameter.
self.param_names	List of parameter names.
self.filtered_model_comp_names	Filtered list of model.component names for legend/plotting.
self.bkg_model_comp_len	Number of astrophysical background model components.
self.bounds	List of tuples of parameter bounds.
self.logmask	Boolean mask for logarithmic priors.

6. Data Arrays, model lines and sliders for Plotting

Attribute	Description
self.plotdata	Dictionary holding arrays for energy, data, and errors for plotting.
self.fig, self.ax1, self.ax2	Matplotlib figure and axes for plotting.
self.total_model	Model array for the total model.
self.total_src_model	Model array for the total source model.
self.total_bkg_model	Model array for the total astrophysical background model.
self.Pib_model	Model array for the Particle Induced Background.
self.total_model_line	Plot line for the total model.
self.total_src_line	Plot line for the total source model.
self.total_bkg_line	Plot line for the total astrophysical background model.
self.component_lines	List of plot lines for model components.
self.PiB_line	Plot line for the Particle Induced Background (PIB) model.
self.residuals	Array of residuals from the fit.
self.residuals_err	Array of errors on residuals.
self.res_points	Errorbar object for residuals plot.
self.sliders	List of ipywidgets sliders for parameter control.

7. Fit Statistics

Attribute	Description
self.C	Fit statistic (C-statistic).
self.dof	Degrees of freedom for the fit.

These attributes are managed internally and updated as you interact with the plot, change parameters, or re-fit the model.

Further Reading

• See the XiP_demo.ipynb notebook for a step-by-step guide and more advanced usage examples.
• Refer to the README.md for installation.