
Writing your own statistic for use in Sherpa
--------------------------------------------

Unlike user models, there is only one way to write your own statistic
in Sherpa, and that is to use the ascfitUserStat interface.

The directory stat/ contains an example of how to do this. Note that
you must also provide routines for the ascfitUserModel and
ascfitUserMethod interfaces, otherwise the dynamic library will not be
loaded by Sherpa. In the example we use dummy routines for these
interfaces.

The file stat.c contains the user-defined routines:

  ascfituserstatfunction_
  ascfituserstaterror_

The bodies of these routines should be changed to match your needs (the
routine names and argument lists must not be changed).

The ascfituserstatfunction routine is used by Sherpa to calculate how
well each point matches the model. The routine is called for each data
point and Sherpa sums the resultant value to get the overall statistic
fit for the current model and parameter set. In the example file we
implement the formula

  statistic = weight * (data-model)^2 / error^2

The ascfituserstaterror function is used to estimate the error on a
data point (so this is used when an error value has not been
explicitly read in using 'READ ERRORS' or 'set_errors()'). In the example
file we implement the following algorithm:

  if the data value is <= 1e-10
    return 1e-10
  otherwise 
    return the square-root of the absolute value of the data

This is used to illustrate the interface and should not be used in your
data analysis!

To build and use the example (run from within the stat/ directory):

a)  ./configure

This creates a link to the correct Makefile.

b)  make

(or 'make -f Makefile.<os>' if step a has not been run)

This compiles the code and creates the libascfitUser.so shared library
(libascfitUser.dylib on OS-X).

d)  add the current directory to the start of the library path

On Solaris and Linux

  setenv LD_LIBRARY_PATH `pwd`:$LD_LIBRARY_PATH

On OS-X

  setenv DYLD_LIBRARY_PATH `pwd`:$DYLD_LIBRARY_PATH

The directory containing the libascfitUser.so/dylib file must be
placed at the start of this list, otherwise Sherpa will use the
default library from the CIAO distribution rather than your own
version. To check this try on Solaris or Linux

  ldd `which sherpa` | grep ascfitUser
        libascfitUser.so => <pwd>/libascfitUser.so

which should report the current working directory rather than the CIAO
installation firectory for the library. The 'otool -L' command can be
used on OS-X, but it does not seem to report the directory location in
the same manner as ldd.

e)  start Sherpa

The directory contains a simple test script (test.shp) which can be
loaded into Sherpa by saying

  sherpa> use test.shp

This script just sets up two small 1D datasets without errors, and
then shows the error estimates calculated by the Chi Gehrels, Chi Data
Variance. The expected output is given in the file test.log.
