Basic Function Generator  v 1.0 (medium resolution)               05/06/90
      by Allan Zachary                            


  I wrote this program initially to help spot trends in the performance 
of a business, but it is capable of fashioning an equation which can be 
used in a variety of situations.  I have used it, not only for forecasting
sales and growth trends, but for such things as making a time calculator for
my VCR tapes, plotting a 3D landscape, and creating custom conversion
tables.  It is designed to be a programming tool, but you can have a lot of
fun just plotting statistical information out of your favorite almanac, to
analyzing numerical relationships.

  As the name suggests, the program generates a BASIC function & code that
can be merged into the GFA Interpreter and executed.  Since the code that
is generated is in ascii format, it can be read from the desktop and easily
changed to accommodate any of the many dialects of BASIC.  

  Without getting too deep into the actual mathematics, what this program 
does is create an equation of best fit to your numbers using polynomials.
Your numbers should consist of two sets of related figures that you wish
to analyze.  For example:

                     x                           y 

                    age                life expectation
                    
                     0                          72 
                    10                          62.9 
                    20                          53.4 
                    30                          44.2 
                    40                          34.9 
                    50                          26.1 
                    60                          18.2 
                    70                          11.7 
                    80                          6.9  

problem: find the expected average number of years of life left for
         someone 36.5 years old.
         
                                  or
             VCR Tape Count                Time Elapsed 
                                        ( in minutes(specifications) )

                    0                            0 
                  829                           10 
                 1499                           20 
                 2075                           30 
                 2588                           40 
                 3054                           50 
                 3486                           60 
                 3889                           70 
                 4268                           80 
                 4628                           90 
                 4971                          100 
                 5299                          110 
                 5614                          120   

problem: I have recorded up to count 2736 on a video tape.  How much
         blank tape is left at 'sp' speed (in minutes)?  at 'slp' speed??  
 
                                  or                                
                  Month                    OWNERS EQUITY
                                     (from your balance sheet)        
                  
                     1                        14603 
                     2                        13140 
                     3                        15481 
                     4                        16684 
                     5                        15457 
                     6                        14406 
                     7                        17529
                     8                        21091 
                     9                        22215 
                    10                        14360 
                    11                        15731 
                    12                        17547 
                    13                         8444 
                    14                         6288 
                    15                         7705 
                    16                        13264 
                    17                        14667 
                    18                        17957 
                    19                        14599 
                    20                        16063 
                    21                        17563 
                    22                        19316 
                    23                        18882 
                    24                        14039 
                    25                        12462 
                    26                        11332 
                    27                        14826 
                    
problem: what is the trend in growth of this business? 

      (see other examples on disk with the '.BFG' extension)

  When you create an equation to fit this data, you are making a 
mathematical statement:
                           y=f(x)
                           
                            or
                            
                     y is a function of x
                     
                            or 
                            
                  y depends on the value of x   
                  
so, if you let one column of figures represent 'x' and the other column
of figures represent 'y' in this program, you will be stating that for
example:  
                  years of life left = f(age)
                         
                            or
                                  
               years of life left depends on age                         

                            and
                            
               minutes of tape used = f(count)
               
                             or
                             
         minutes of tape used depends on the tape count
     
Once you perform a regression on the figures with the accuracy you are
satisfied with, you can then substitute any tape count value (within 
your pre-defined limits) and the function will calculate the recording
time elapsed.  And, you can easily modify the basic code to calculate
minutes of blank tape left. (see VCRCOUNT.LST)  The user always supplies
the x value to get back a y value.

Now, if you use a little imagination, you can see its uses for goal-
setting in business, or estimating values that are not readily
available.

In the example LANDSCAP.LST, I used two polynomials created by this
program to generate a non-symmetrical terrain.  One equation runs
NORTH-SOUTH, and the other runs EAST-WEST.  The elevation at any point
on the grid is calculated by running the miles north, and the miles 
west through their perspective equations. 

--------------------------------------------------------------------------

Features of the BASIC FUNCTION GENERATOR:

The Screen Layout...

  The layout of the work area on the screen consists of a black graph area,
the limits of the graph area on the top left side if the screen, the y axis
and x axis labels in their proper positions, the PLOT MODE button at the
bottom of the screen, and an indicator for the number of points at the 
lower right side of the screen.  As you perform regressions, you will 
see measures of accuracy of the regression equation printed at the lower
left side of the screen.  These are CONFORMITY, which is a measure of how
well the regression line hit your points (this is actually the correlation
coefficient X 100); STANDARD ERROR, which is the average of the regression
lines' miscalculations in terms of what ever you have on the y axis; the
AVERAGE RATE OF INCREASE/DECREASE will also appear anytime you perform
a first degree regression which is also in terms of y.  This is a measure
of the amount of increase in y value for each unit of x value.  Since the  
last two measures mentioned are in terms of values found on the y axis,
they also use the y axis format (set forth in graph configure utility
discussed later) to help you make the connection of the value of the 
regression.  So, it is possible that the AVERAGE RATE may indicate '0' even 
though the regression line is increasing or decreasing due to a format 
string that only allows for values that are larger than the actual rate.

  To plot or measure points, you can simply click on the plot button and
click on the locations over the graph area. (Note: The program's menu bar
is disabled while the PLOT MODE button is highlighted)  Axis' values are
displayed under their related label in this mode.

Watch for messages or special instructions in the window's title bar for
some of the program's features.
   
Under the FILE menu...

  CONFIGURE GRAPH- will run config.prg (which must be in the same folder as
  basfngen.prg) which allows you to set the default limits of your graph,
  along with the labels for the x and y axis, and the format that the 
  values of the x and y axis will use.  The formats are the same used in
  BASIC's PRINT USING statement. (see example .BFG files on disk) 
    You can reconfigure at any time during your work session without loss
  of data, but your last regression equation will be lost.  The limits
  you define in the configure program become the new 'default' limits.
  Be careful not to define the default limits so large that some of the
  data points require the same screen pixel, as the program will
  automatically delete duplicate points. 
  
  TYPE IN POINT(S)- allows for keyboard input of the data coordinates.
  
  DELETE POINT(S)- allows you to delete selected points.  Select a point
  using the cursor arrows on the keyboard, then press the DELETE key to
  delete the point. The UNDO key returns you to the standard graph mode.
  
  ERASE ALL DATA- will remove all of the points from the graph, but the 
  labels and limits remain.
  
  LOAD DATA FILE- loads a file with the .BFG extension.  BFG files are 
  simply ascii text files in the following form:

"age (white males)","life expectation"          <---x,y labels
"###.# years old","###.# years left"            <---x,y number formats
 80 , 80                                        <---x,y graph maximum
 0 , 0                            _             <---x,y graph minimum
 0 , 72                           |
 10 , 62.9                        |
 20 , 53.4                        | 
 30 , 44.2                        |
 40 , 34.9               up to 450 data points (x,y)
 50 , 26.1                        |
 60 , 18.2                        |
 70 , 11.7                        |
 80 , 6.9                         |
                                  v
                                  
  This makes it easy to create programs that extract raw data from other
  files to create a .BFG file. (for example a spreadsheet saved as text)
  It is also easy to edit/enter data in a word processor as long as it 
  can save the file in ascii format.
 
  The limits that are loaded become the new 'default' limits, which can
  only be changed by re-configuring the graph or loading another file.

 
  SAVE DATA FILE- saves the axis labels, the graph limits, and all of the 
  data points in the format discussed above.  
 
  WRITE GFA EXAMPLE- will write the GFA code in ascii form to a file, which
  can be merged into the GFA Interpreter (either 2.0 or 3.0) and executed.
  Since the generated code uses your last regression equation, you must
  perform a regression analysis on some data before this option is enabled.
  The generated code also utilizes your *current* graph limits, along with
  your axis label and number formats. 
 
  Note: The example code for the actual polynomial could have been coded
        more efficiently using a for-next loop, but I chose to use a style
        that illustrates the actual polynomial form better.
       
  EXIT- leaves the BASIC FUNCTION GENERATOR program, but will alert you if
  the data has been changed and not saved.
 
UNDER THE REGRESSION MENU...

  1st - 10th DEGREE- will perform a regression on the current set of data
  points using a polynomial of the selected size.  You will find that each
  degree of polynomial has its own sort of personality,- the first degree
  straight and tame, and highly suited for showing average trends, but not
  very good at hitting very many of the points on the graph; while the 10th 
  degree polynomial will try to curve as much as possible and is difficult
  to tame without a lot of data points, but is much more likely to hit your
  points exactly.
  
  Be careful about using the higher degree polynomials for forecasting and
  interpolation, they make some wild swings when they become unharnessed!
  
  REDRAW LAST LINE will redraw the last regression line without doing the
  calculations.  This is useful for verifying accuracy.  Do a BLOCK MAGNIFY
  around a few of the data points and redraw the regression line,- the 
  deviation of the regression line is more evident.
  
UNDER THE OPTIONS MENU...

  AUTO-SCALE- moves all data to the center of the graph screen and
  scales the graph for the best resolution of all of the points.
  
  AUTO-CENTER- centers the current visible data points in the screen.
  
  MAGNIFY BLOCK- lets you frame a certain area of the graph with a GEM
  rubber-band box.  The framed area is then enlarged to the size of the
  total graph area.  This is ideal for a closer examination of the 
  coordinate line to regression line accuracy.
  
  ENLARGE GRAPH 10%- enlarges the graph.(the coordinate line will appear
  to shrink)
  
  SHIFT UPWARD- will move your field of vision upward on the graph. (the
  points will move downward)
  
  SHIFT DOWNWARD, LEFT, RIGHT- moves your field of vision in the selected
  direction (as in SHIFT UPWARD).
  
  READ FILE SCALE- will read another .BFG file's limits (only), which is 
  useful for superimposing coordinate lines with the SNAPSHOT/OVERLAY
  features.
  
  USE DEFAULT SCALE- returns you to the default limits after moving around
  on the graph or magnifying.
  
  HIGHLIGHT POINTS- will draw a little yellow circle around each of the
  data points so you can more easily see the accuracy of the regression
  line as it tries to hit the points.
  
  EXCHANGE X AND Y- will swap the x and y axis'.  Since the user will
  always supply x values in the regression equation, you can swap the
  axis' (and perform another regression) which would then allow you
  to supply y values to obtain x.
 
  for example: 
  
      TIME ELAPSED=f(TAPE COUNT) would be altered to...
                                                 TAPE COUNT=f(TIME ELAPSED)
  
     now the user can input time in minutes to obtain a VCR tape count.                                                 

  REDRAW THE GRAPH- clears the graph of all regression lines.
  
  TAKE A SNAPSHOT- saves the image of the current graph screen in memory
  for overlay or superimposing over the graph later.
  
  OVERLAY SNAPSHOT- puts the last snapshot image back on the graph.
  
--------------------------------------------------------------------------
USING THE BASIC FUNCTION GENERATOR TO MAKE A MATHEMATICAL MODEL...

  1. Obtain the measurements...
  
     To get some data on the VCR COUNT vs TIME ELAPSED I simply ran a
     stopwatch while watching the tape counter and wrote down the count
     every ten minutes at 'sp' speed.  I wanted to be able to enter a
     COUNT value and get back a TIME ELAPSED value, so COUNT values were
     going to be on the x axis of the graph.
     
     I thought the graph of this data was going to be linear,- I was
     wrong.  But, for any linear measurement, you only need two points
     to find any value in the conversion. 
     
          For example: If you want to know how many cubic inches your
                       foreign car engine equates to, whip out your
                       trusty almanac and turn to the weights and
                       measures section.  We find that 1 liter is
                       equal to 61.2024 cubic inches.  We know that
                       0 liters is equal to 0 cubic inches, so the
                       two points are:
                       
                                  x                  y
                                  
                                liters          cubic inches

                                  0                  0
                                  1               61.2024
                                  
     Generally, the more complex the shape of data is when it is connected
     by lines, the more points you will need to get a useful mathematical
     model.
                                  
  2. Configure the graph...                      

     Go to CONFIGURE GRAPH under the file menu and simply fill in the
     blanks with your axis labels, limits, and numeric formats.  Use
     the ESC key to erase the edit fields.  For the number formats on
     the VCR data, I can use ##### to reserve 5 places for my COUNT
     numbers.  Because there are no decimal places in the format, I
     will only see integers, which is what I want since my VCR will
     not show tenths, etc.  Why use 5 places instead of 4 since the 
     maximum tape count is four digits?  Because sometimes, when you
     are moving around on the graph plane, you may encounter negative
     values, and since a 4 place format doesn't have enough room for
     a leading "-" minus sign you will get an overflowed format 
     string.  This is no biggie, but it can look messy on the screen.
     When this happens you will see a "%" character next to the number
     that caused the overflow.  It is a good idea to use a format that
     is a little larger than you need, just in case!
     
  3. Type in or plot you data points...
  
     Most of the time you will be using TYPE IN POINT(S) under the file 
     menu to enter your coordinates because the graph usually will not
     have the exact resolution you need to plot the points directly on
     the screen.  However if you wish to plot the points with the mouse,
     simply click on the PLOT MODE button at the bottom of the screen,
     and go to it!
     
     You can enter the points in any order because they are always sorted
     before the coordinate line is actually plotted.  As I stated before,
     any duplicate points are automatically deleted.  If you make an
     error in entering a point,- simply go to DELETE POINT(S) under the
     file menu and delete the offending point.
     
     Once you have entered all of the data, it is probably a good time to
     save it as a .BFG data file (just in case of a crash or Armageddon!),
     using SAVE DATA FILE under the file menu.
     
  4. Do some regression tests...
  
     Linear coordinate lines (like our liter to cubic inch conversion
     above) can be modeled exactly on the first try with a 1st
     degree regression.  You will see the CONFORMITY percentage go to
     100 and the STANDARD ERROR indicate 0, and this is what we are
     striving for with any shape of coordinate line,- though it is 
     harder to achieve with more complex shapes.
     
     If you're not satisfied with the way the regression line attempts to
     duplicate your coordinate line, try a higher degree equation (under
     the DO REGRESSION menu).  If you still can't get a satisfactory  
     result, you may need more points plotted along the coordinate line.
     Each point on the coordinate line attracts the regression line.  
     You can test each regression line by clicking on the PLOT MODE 
     button and running the crosshairs along the line.
     
  5. Save your work...
  
     When you're happy with the regression line, go to WRITE GFA EXAMPLE
     under the file menu.  You will be prompted for a filename (which
     should have a .LST extender), and your regression equation will
     be saved as a BASIC function in an ascii text file, along with 
     enough code to illustrate a simple usage of the equation.  The
     equation's performance statistics are save with the code also.
     
   
   =====================================================================
  
  I used very little error trapping in the program, so it can be crashed
  if you push the program to its limits (i.e. doing a 10th degree 
  regression on two or three points).  To incorporate much more error
  testing would have sacrificed either speed or versatility.  I have 
  used the program on two different 1040s with different versions of
  TOS, and everything seems to be in alignment and working.  Also, I
  have found that it reacts badly to some AUTOrun programs and desk
  accessories, so you may have to experiment a bit.  The program was
  compiled in LDW Basic v. 2.0, and uses no unusual or illegal calls
  to the operating system.
  
I hope you enjoy using this program as much as I have enjoyed writing it.

  The BASIC FUNCTION GENERATOR program is public domain software and free 
to distribute.  
                                                       -Allan
