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

  isis> fit_counts;

  s = fit_counts ([&info_struct] [,response_type])

Interactive Documentation

• 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

        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
                        list_data
                        list_arf
                        list_rmf
                        list_fit_methods
                        list_model

        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)
                        set_par

        thaw            thaw(par-list)
                        set_par

        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
                        ylog
                        xlin
                        ylin

        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

• 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:

     get_data*
     put_data*
  
     get_model*
  
     get_arf
     put_arf
  
     get_par*
  

• Intuitive programming capability:
  Instead of:

      XSPEC> set i 1 ; set product 1
      1
      XSPEC> while {$i <= 5} {
      XSPEC> set product [expr $product * $i]
      XSPEC> incr i
      XSPEC> }
      XSPEC> set product
      120
  

  This is possible:

      isis> i=1; product=1;
      isis> for (i=1; i<=5; i++) product *= i;
      isis> product;
      120
  

  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);
  

  Then

      isis> ()=evalfile ("tst.sl");
      product=120
  

• 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");