Event-2D: Home Examples Install Documenation News & Pubs


These pages describe and make available the "Event-2D" software and related routines that can be used in ISIS to do forward folding and comparison of 3D spatial-spectral models with 2D event-based data sets.

The 2 axes used for analysis can be chosen from the available event-file columns; commonly useful 2D spaces include: X-Y Sky images ("X","Y"), Wavelength--Cross-dispersion grating images ("TG_LAM","TG_D"), or RADIUS-ENERGY 'images' ("RADIUS","ENERGY").

Note that the data required for Chandra grating observations are the evt2 and ARF files; nominally processed versions of these can be conveniently acessed from the TGCat archive.

How this Event-2D work fits into the overall scheme and goals of advanced spatial-spectral analyses and a brief description of some of the implementation choices are given below.

Send comments to dd@space.mit.edu above last updated 5/9/2012

Figure above: Overview of the components and flow in the Event-2D system

Event-2D and the Big Picture

The Event-2D code presented here implements most of the facets of a multi-dimensional analysis system; in the sections below brief comments are given about the specifics of Event-2D in the context of the various analysis components.

Source Models

The Source-3D routines defined in source3d.sl allow the construction and viewing etc. of source models. These models are the union (optically thin) of geometric components and their associated emission spectra. The components are 3D arrays of values a la the Volumetric 3D library, and the spectra are defined by ISIS .par or MARX .dat files.

The user "input" to the Source-3D routines is through an S-Lang file, e.g., mysource_model.sl, which defines the model parameters, spectra, geometric components, and updating rules for them; see the various example 'model.sl files linked in the demo table above. The user has direct access to the two strucutures that define the spectra (s3d_spec[index]) and the geometric components (s3d_comp[index]).

The main "output" of the source library is created by s3d_xray_photons which returns Sky-X, Sky-Y, energy and time values for Monte-Carlo generated photons. The X,Y are in arcseconds w.r.t. the field center and Energy is in keV.

The source can include a foreground absorption component which is applied in the observer rest frame -- this will correctly treat Doppler shifts due to source velocity. Note that an ARF (or pre-ARF) can also be provided and is included in the observer frame; this allows the photon MC generation-detection to be more efficient.

Note that it should be possible to incorporate the s3d software and models into other S-Lang/ISIS-based uses, e.g., through the s3d_xray_photons routine that generates and returns random source photons from the model.

Missions & Instruments

Data to be analyzed are loaded into internal structures from the nominally processed data files, currently Chandra FITS event files are supported. Again it is convenient to create a script, mysource_data.sl to do this. Several structures keep track of the instrument properties (e2d_meta[idata]), the event data (e2d_data[idata]) and the viewing and binning parameters for the dataset (e2d_view[idata].) Since these structures are user accessible, custom analyses are facilitated in addition to the nominally provided ones.

The instrument simulation knowledge is contained in the routine e2d_inst_xray in the Event-2D library. This routine takes as input the MC source photons and a structure that defines the instrument (the coresponding e2d_meta[idata] structure) and returns X, Y, Energy, and Time as seen by the detector with X,Y in arcseconds, Energy in keV. This is effectively an observatory simulation or raytrace, e.g., what MARX does in the case of Chandra.

Currently this instrument simulation is coarse but useful: an arf specifies effective area vs energy, a 2-Gaussian approximation to the on-axis PSF is applied, and the detector (e.g., CCD) energy resolution is specified by a simple equation. Grating simulation includes period variation and cross-dispersion blurs.

The routine e2d_inst2mod then selects and loads the simulated events properly into the Model x and y events to be in agreement with the Data x,y event descriptions.


Visualizations implemented include: 3D solid models, 2D model images, 2D data and simulation images and residuals, 1D K-S and histogram plots, plots if fit parameter values during fit process, etc.

Statistics & Fitting & MCMC

The datasets and their models are stored as x and y arrays of event values. These event values are loaded from FITS event files. In this simple implementation the 2D event pairs (x,y) of the Data and Model can be compared by i) using a K-S test along either axis, or ii) binning the events in a regular 2D grid and calculating the chi2 between the histograms (analogous to 1D PHA methods.) For both of these methods, the viewing parameters for a dataset ( [xlo, xh, xdelta], [ylo, yhi, ydelta] ) are used to select the events to consider and set the binning parameters. The 1D case can be realized with an appropriate 2D binning choice.

A simple nonlinear conjugate gradient fitting method (Wikipedia) is available to do fitting, e2d_cg_fit. One tricky aspect of fitting here is the "noisy chi-square" evaluations that result from using a Monte-Carlo model simulation. The CG fitting here accomodates this through i) having the user explicitly set a "should make a noticable difference", smand, scale size for each parameter, and ii) measuring the variation in the gradient and chi-squared values and setting completion criteria based on their levels.

A simple Markov Chain Monte Carlo (.pdf) parameter exploration routine is also available, e2d_mcmc_explore, and runs with the same setup as the CG fitting. In this case the "smand" values are used to set the "q distribution" width for each parameter.

The steps taken by the parameter exploration (parameter scans and mcmc) and fitting (C-G) routines are saved in "FOM-log" variables in memory and can be viewed as plots of FOM (chi-squared) vs iteration (e2d_fomlog_plot), and as paths in parameter space with points of low chi-squared indicated. See the Abel 1068 C-G fitting and MCMCM demonstration page for some example FOM-log plots.

High Performance

No high-performance aspects have been investigated or explicitly included in the coding so far - and the execution times show it! There are many improvements that can be made in the code and its distribution over multiple machines and cores.


The Event-2D s/w demonstrates the usefulness of using S-Lang to give the user a large amount of control and customization of the model definition and data analysis and fitting.

Send comments to dd@space.mit.edu above last updated 11/18/2009