Jump to Content
Version 1.6.2-41  

Comparing ISIS with XSPEC


This page is intended to provide a brief comparison between ISIS and xspec, which is currently the most widely used software package for data analysis in X-ray astronomy. It includes a guide to map xspec commands to equivalent ISIS functions. Fully commented examples of xspec and ISIS scripts are also available.

ISIS was Designed to be Programmable

The fundamental difference between xspec and ISIS is that ISIS was designed to be programmable. Because ISIS embeds the S-Lang scripting language, most ISIS commands are functions which may take arguments and return values. In some cases, the design hides this. For example, the fit_counts function can be invoked as:

  isis> fit_counts
Or, if the line-ending semicolon (;) is not suppressed in the user's startup configuration, this could be:
  isis> fit_counts;
For scripting use, the full form may be used:
  s = fit_counts ([&info_struct] [,response_type])
Here we have indicated optional function arguments by enclosing them in square brackets ([]).

Interactive Documentation

In addition to the formatted manual, there are three interactive documentation mechanisms in ISIS which can be used to determine the arguments and return values of a function:
  • Usage messages
    If a function requiring one or more arguments is invoked with no arguments, a usage message is usually printed.
  • apropos
    The apropos function lists all function names which contain a given substring.
  • help
    The help function retrieves detailed documentation for the specified function.

ISIS Analogues for Common XSPEC Functions

The following table gives the most commonly needed functions for basic interactive analysis. Note that optional ISIS function arguments are enclosed in square brackets ([]), and that if all arguments are optional, then a typical interactive use is to simply type the command name followed by a semicolon (;<RETURN>). Function return values are not shown; in interactive mode, they will be echoed to the terminal.

        XSPEC                          ISIS
        data            load_data ("pha_filename", [row_num])

        arf             load_arf ("filename")
                        assign_arf (arf_index, hist_index[])
                        unassign_arf (hist_index[])

        resp            load_rmf ("filename[;name]" [, init_args])
                        assign_rmf (rmf_index, hist_index[])
                        unassign_rmf (hist_index[])
                        assign_rsp (arf[], rmf[], hist_index[])

        ignore          ignore (hist_index[] [, lo, hi])
                        ignore_bad (hist_index[])
                        ignore_en (hist_index[] [, lo, hi])
                        ignore_list (id, where)

        notice          notice (hist_index[] [, lo, hi])
                        notice_en (hist_index[] [, lo, hi])
                        notice_list (id, where)
                        xnotice (hist_index[] [, lo, hi])
                        xnotice_en (hist_index[] [, lo, hi])

        model           fit_fun ("function")

        statistic       set_fit_statistic (name)

        show            list_par

        newpar          set_par (idx, value [,freeze, [ min, max]])

        renorm          renorm_counts ([response_type])
                        renorm_flux ([response_type])

        method          set_fit_method (name)
                        load_fit_method (file, name)

        fit             fit_counts([&info_struct][,response_type])
                        fit_flux ([response_type][, &info_struct])

        error           conf(param_index [, level [,tolerance]])
                        fconf (param_index [, flevel [, tolerance]])
                        vconf (param_index [, level [, tolerance]])

        fakeit          fakeit ([&noise_fun])

        flux            region_flux (hist_index, xmin, xmax [,ymin, ymax])
                        region_counts(hist_index, rmin, rmax [, ymin, ymax])

        dummy           (implicit)

        freeze          freeze (par-list)

        thaw            thaw(par-list)

        newpar          set_par
                        edit_par (["filename"])

        editmod         fit_fun

        delcomp         fit_fun

        eqwidth          -

        cpd             plot_device (device_string)
                        open_plot (["device" [, nxpanes, nypanes]])
                        multiplot (relative_size_list)
                        window (pid)

    plot data           plot_data(hist-index [, style])
         counts         plot_data_counts(hist-index [, style])
         residuals      rplot_counts(hist_index)
         model          rplot_flux(hist_index)
                        plot_model_counts (hist-index [, style])
                        plot_model_flux (hist-index [, style])

        label           label ("x-label", "y-label", "title")
                        xylabel (x, y, text [, angle [, justify]])

        rescale         xrange[ ([xmin], [xmax])]
                        yrange[ ([xmin], [xmax])]

        log             xlog

        set mission     n/a

        set instru      n/a

        set datadir     cd(dir)

        clear           delete_data (hist_index[])
                        delete_arf (index[])
                        delete_rmf (index[])

        quit            exit

Within the restrictions imposed by syntax, it is also possible to alias ISIS functions to more directly map to the xspec equivalent. For example,

  isis> alias ("load_arf", "arf");
  isis> arf ("arf.fits");             % cf.  xspec> arf arf.fits

What ISIS can do better

The most important feature of ISIS is that it was designed to be programmable and extensible. As a result, it is often the case that, when there is a useful feature that ISIS does not have, it is possible for anyone to add that feature without either modifying or recompiling ISIS(!).
  • ISIS can be extended, without recompiling or linking ISIS itself.
    For example, all xspec models are available in a module which can be imported; that part is compiled as a shared library, and S-Lang bindings are provided.

  • Dynamic grouping and rebinning:
       group_data (hist_index[], factor)
       rebin_data (hist_index[], min_counts | rebin_index[])
       rebin_dataset (hist_index, lo, hi)
    Note that rebinning data in ISIS is true rebinning -- it includes propagation of uncertainties and appropriately modifies the statistics of the model fit. The rebinning is also completely reversible, allowing one to easily experiment with different approaches. In contrast, rebinning in XSPEC affects only the way the data are plotted and does not alter the statistics of the model fit.

  • Define user models, without recompilation or linking:
      add_slang_function (function_name[, parameter_names [, norm_indices]] )
  • Operate on variables:
       new_value[] = rebin (new_lo[], new_hi[], lo[], hi[], value[]);
       new_y[] = interpol (new_x[], old_x[], old_y[]);
    (and large set of generic programming and math ability)

  • Read data into variables, write variables to data tables:
  • Intuitive programming capability:
    Instead of:
        XSPEC> set i 1 ; set product 1
        XSPEC> while {$i <= 5} {
        XSPEC> set product [expr $product * $i]
        XSPEC> incr i
        XSPEC> }
        XSPEC> set product
    This is possible:
        isis> i=1; product=1;
        isis> for (i=1; i<=5; i++) product *= i;
        isis> product;
    Or in a script file, tst.sl:
        variable i=1, product=1;
        for (i = 1; i <= 5; i++)
           product *= i;
        vmessage ("product = %4.0f\n", product);
        isis> ()=evalfile ("tst.sl");
  • Instead of using Tcl scripts like this example from the xspec manual:
      # Get the values specified for parameter 4.
         tclout param 4
         set par4 [string trim $xspec_tclout]
      # Turn it into a Tcl list.
         regsub -all { +} $par4 { } cpar4
         set lpar4 [split $cpar4]
      # Print out the result to the file.  Parameter value is
      # the 0th element of the list `lpar4'.
         puts $fileid "$i [lindex $lpar4 0]"
    Do this:
      % Get the param by name; a number also works.
         p4 = get_par ("wabs(1).nH");
      % open a file
         fp = fopen (filename,"w");
      % print to file
         () = fprintf (fp, "nH = %12.4e\n", p4);
    Alternatively, to save all parameters in a file:
      save_par ("params.par");
To add or modify functions, one can use the define statement. For example, this pileup modeling script uses an ISIS grouping intrinsic to write a function which more closely resembles grppha (from ftools).

Made with JED  |  Best Viewed with a Browser  |  Valid HTML 4.01  |  Valid CSS ]
This page is maintained by John C. Houck.   Last updated: Apr 20, 2018