Summary

Readme.txt for Simfit Version 7



  
  Simfit Version 7 (for MS Windows, Mac, and Linux)

  CONTENTS : 1) General Information
             2) Configuration
             3) Upgrading
             4) Help and advice 

   1) General Information
   ======================

  Summary:  Simfit is a free software Open Source package for
            simulation, curve fitting, statistical analysis and
            graph plotting. There are now two versions.

             i) The free standing Academic version does not use
                the NAG library for numerical analysis, but it
                does use some very reliable and robust public
                domain numerical analysis code (e.g., blas, linpack,
                lapack, minpack, dvode, lbfgsb, quadpack, slatec,
                Applied Statistics algorithms, and ACMTOMS).

            ii) The NAG library version has extra features, but it
                can only be used by those who already have the NAG
                library DLLs Mark >= 20 installed on their PC.

  Users:    Simfit is free for teaching and research purposes from
            the web site at http://www.simfit.org.uk, but it
            must not be sold on, or used for profit. The Spanish 
            version can be obtained from http://simfit.usal.es

  Versions: The mainframe and PC versions up to version 5.7 are no
            longer supported. Version 7 for Windows, Mac, and Linux 
            is the only version that is currently being supported
            and developed. No email help will be given for any
            versions except for version 7. To avoid confusion with
            some previous versions of Simfit, version 7 files
            files all have a w_ prefix, e.g., w_simfit.exe in the
            32-bit version, but a x64_ prefix, e.g. x64_simfit.exe
            in the 64-bit version. The file version7.txt has details. 

  Install:  Get the self extracting setup executable file, available
            in a zip file from http://www.simfit.org.uk, and double
            click from Explorer. Windows users who want PostScript 
            options for superior quality graphics should also install
            the GSview/Ghostscript package, and should have the
            Adobe Acrobat Reader. Linux users have such utilities
            built-in. The file install.txt has details.

  Problems: The only known problem is when users have inconsistent
            binaries, for which the remedy is to remove/re-install.
            The file errors.txt has details.

  Running:  Make a desk-top shortcut to the Simfit driver w_simfit.exe
            (or x64_simfit.exe). This is a special program-manager type
            file designed to make it easy for you to use Simfit as
            if all of the forty odd separate independent programs
            were just one big program. Of course you can run any of
            the individual programs from the command line, or by
            executing from Explorer.

  Testing:  There are test data files *.tf? to use for each program
            and the reference manual has worked examples showing
            you how to use these.

  Files:    There are special editors to prepare data files, results
            are always saved to file, and the package is configured by
            .cfg files. Formats are described in the w_readme.f? files.
            Clipboard tables can be pasted into Simfit, or used by
            program Maksim to create correctly formatted data files.

  Graphs:   Image files are Postscript (eps, for top quality), and
            also pdf, svg, png, emf, pcx, tif, jpg, or bmp.
            Plots can be transformed interactively in the usual ways,
            and a facility exists to transfer data interactively from
            any default graphs into the advanced plotting routines.
            Simfit graphics are described in the w_readme.g? files.

  Interface:To transfer data from Excel into Simfit, write out tables
            of data to CSV (ASCII comma-delimited files), XML, or HTML,
            export files. These can be imported directly into Simfit or
            read into the program Maksim. Otherwise use the clipboard.
            Alternatively, use one of the special macros, like simfit4.xls
            or simfit6.xls, to make correctly formatted files from Excel.
            Enhanced metafiles (emf) or png files can be used to import
            graphs into those programs (e.g. Word) that do not support
            PostScript. To strip margins, re-size, rotate, make collages, 
            etc., from Simfit eps files, use program Editps.

  Manuals:  There is a reference manual in PS (monochrome), pdf
            (colour with hyperlinks), pdf (monochrome, and LaTeX source
            together with a set of PS files. If you want to see how to 
            create a document, like the Simfit user manuals including 
            figures, hyperlinks etc., use LaTeX with the *.tex, .wgb, 
            and *.eps files distributed from the website.

  Help:     There is a help program, but every program has a built in
            tutorial. Please read these before running any program.

  Fitting:  Most of the models used in data analysis can be fitted by
            dedicated routines. In addition, there are programs that
            use a library of models to fit differential equations, or
            one or more functions of one or several independent variables.
            Users can supply models as dynamic link libraries, or in
            the form of special ASCII text files (see w_readme.f4).

  Stats:    All the usual statistical tests are supported.

  Code:     The file source.txt has details.

  2. Configuration
  ================

  Simfit is configured by a set of temporary files with extension
  .cfg as in w_ps.cfg, w_simfit.cfg, etc. These are all edited as
  you use Simfit but, if you want to fix a particular default, you
  can use archived versions to overwrite the defaults.
  Typical uses for .cfg files would be storing paths to program
  files, saving file search patterns, altering the colour palette,
  archiving graph titles and graphical objects. If you learn how to
  manipulate the .cfg files you can customise Simfit to your own
  requirements. Simfit does not use the Windows registry.

  3: Upgrading
  ============
  Each release of Simfit has internal identifiers to make sure that
  the executables and dynamic link libraries are self-consistent.
  If you forget to upgrade w_simfit.exe or salflibc.dll, for
  instance, you will get error messages. When you upgrade, make sure
  you uninstall previous editions, or overwrite all executables and
  dlls by upgraded versions.

  4. Help and advice for Simfit users
  ===================================

  What can Simfit do ?
  ====================
  The Simfit package can do most simulations, statistics, curve fits
  and graph plots needed in data analysis. Inevitably there will
  always be things you want to do that can't be done, but it has been
  designed for versatility so, to get the most from it, there are
  some things you have to bear in mind.

  What assumptions are made about typical users ?
  ===============================================
  I have assumed a much higher degree of scientific competence and
  computer literacy than is assumed by commercial packages. Thus, I
  presumed the user would know that 1.234E+3 is 1234, and I assumed
  users would know the difference between a binary and an ASCII text
  file. Any user who wants to get to grips with Simfit should learn
  how to browse the readme.? files, test files *.tf? and PostScript
  .PS files. Furthermore, I have assumed that users will know
  how to make subfolders, name files sensibly, and use some sort
  of systematic naming convention to facilitate file access.
  Simfit does not use or add any reserved filename extensions.

  What sort of error messages does Simfit give ?
  ==============================================
  I have not told you when to use particular mathematical models but
  have assumed you would know when to choose between Mmfit, Hlfit or
  Sffitt in order to fit your binding data. If this is asking too much
  then perhaps you should not be using a curve fitting approach as a
  black box procedure. Nonlinear regression is a very difficult area
  which needs great caution to avoid over-interpetation such as, for
  instance, claiming that three exponentials fit better than two. If
  you ignore the advice that Simfit pours out, and long for a silent
  package that just gives you the answer, just bear in mind that if
  Simfit warns you about anything, the other packages should too, as
  they all face the same computational problems. Error messages from
  Simfit are all put there to help you avoid mistakes, and guide you
  into making sensible decisions. If you ignore them, please be aware
  that they were put there as the result of much experience.

  Why are there so many files and programs in Simfit ?
  ====================================================
  You may be infuriated by the large number of separate programs in
  Simfit and the seemingly endless number of data and graphics files
  and wonder why you can't save a complete graph as a single file. Of
  course you can. You can make a PostScript file. This can be saved
  as a metafile, printed out, incorporated into a document, viewed
  on the screen, transformed into other formats, etc. What you cannot
  do is recompose a saved PS graph with several data sets, or perhaps
  error bars, with one or more best-fit curves from alternative fits
  and different symbols and line types, since it is too complicated
  to re-interpret graphics files in this way. On the other hand, as
  long as you keep track of the appropriate ASCII text files you can
  easily create the composite graph using Simplot then Editps. Again
  you might wonder why you have to supply all your data for fitting
  instead of just mean-y's and standard-deviations. After all, most
  people plot means with error bars, not the whole data set. There is
  a very good reason for this. If every design point has exactly the
  same number of replicates, and this information is made available
  to the fitting program, then there are fewer points to fit and the
  standard errors, and other statistics, can be calculated using the
  correct number of degrees of freedom. This is impossible when the
  design points do not have equal numbers of replicates. In any case,
  users should always inspect the best-fit and residuals plots using
  all replicates.

  How should I make data files ?
  ==============================
  This is my recommendation when making data files. Always fit the
  total data set, never means of replicates. Simfit is designed to
  do this, and it never has to re-calculate the deterministic model
  more than once at any given x-design point, since it uses logical
  variables and look-up to avoid this. This is particularly valuable
  with programs like deqsol which fit sets of differential equations.
  To make sure starting estimates are calculated accurately and data
  are plotted correctly, curve fitting data files must be in order
  of increasing independent variable, i.e. x or t.

  What editors are provided with Simfit ?
  =======================================
  Again you might wonder why you should use Editfl or Editmt, rather
  than a normal text editor. By all means use a full screen editor
  to change the odd data point: I do. The full power of the Simfit
  editors will only become evident when you learn how easy it is to
  join up files, change data weighting, calculate error bars and means
  for plotting, put data into order, check data sets for consistency
  before fitting, transform coordinate systems, e.g. from seconds to
  minutes and so on. The Simfit editor can be used in cell mode or
  line mode and can be used as a viewer with the editing functions
  disabled to prevent you from altering a file format. If you want
  to browse any test file, data file, results file, etc., then use
  the Simfit editor in view-only mode from the menu in the program
  manager w_simfit.exe. To print a Simfit results file or any text
  file use the Edit/Save/Print function from the file view controls.

  What graphical functions does Simfit have ?
  ===========================================
  Graphics causes an endless source of problems. It is trivial to get
  any particular plot on screen, or to transfer it to a printer. The
  real problem is to save graphs, make collages, add insets, change
  titles, incorporate into documents, send by email, etc. The trouble
  arises since bit-maps are easy to manipulate on screen but are too
  large to store, and yield poor resolution when expanded. A vector
  format is best for scientific graphs, which narrows the choice to
  eps, svg, or emf, or possibly compressed bitmaps such as png, but 
  definitely excludes .jpg, tif, .pcx, and especially bmp.

  How can I get Simfit graphs into documents ?
  ============================================
  Windows users with no PostScript facilities can create enhanced
  metafiles (.emf) or portable network graphics file (.png), as these
  are compact with fairly good  resolution, and can be imported into
  all Windows programs.
  PostScript users will be able to use LaTeX/Dvips and import eps
  files directly to get the highest possible quality. 
  The best way to get the most out of the Simfit graphics is to
  save the appropriate ASCII text graphic files with data and
  best fit curves as library files, or in your graphics project 
  archive, then read them into Simplot and make PostScript files.
  Edit these for re-sizing, rotating, making collages or insets etc.
  using Editps. If you don't use LaTeX/Dvips, you will be faced with
  the problem of getting hardcopy from the final PostScript file, or
  incorporating it into a document. If you want to view the file on
  a PC screen, send it to a non-Postscript printer, transform it into
  another form, e.g. a bit map, etc. then use GSview/Ghostscript.
  If you don't have PostScript printing, or use a word processor that
  doesn't support PostScript, make PS files then use GSview/Ghostscript
  to drive your printer or transform the files into acceptable format.
  to use. Most modern word-processing packages will accept Simfit
  PS files directly, if they are configured correctly, since they are
  consistent with the EPS convention. GSview/Ghostscript can be used
  to add a preview if you insist on seeing included graphics on screen
  
  What documentation is supplied with Simfit ?
  ============================================

  1) The manual is in three versions as follows:
     a) w_manual.ps : monochrome PS version
     b) w_manual.pdf: coloured PDF version with hyperlinks
     c) mono_manual.pdf: monochrome pdf version

  2) Every individual program starts with a brief tutorial and
     there is a set of test data files which can be as examples
     for your own data or for practise. The first time you use a
     Simfit program you should run it with the test files provided.
     This is easy since each program is linked to specially
     selected example data files.

  3) There is a set of w_readme.* files covering technical details,
     but these mostly datae from an earlier era and do tend to use a
     fair bit of computer-speak.

  4) The file ms_office.pdf covers all aspects of the integration of
     Simfit with MS Office and OpenOffice.