# 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.