
      ┌──────────────────────────────────────────────────────────────┐
      │      Propagation Forecast Bulletin Graphic Plot Utility      │
      │                        Version 2.5                           │
      │                                                              │
      │                 Program HELP File GRAPH.HLP                  │
      └──────────────────────────────────────────────────────────────┘


      ┌──────────────────────────────────────────────────────────────┐
      │              Background and General Information              │
      └──────────────────────────────────────────────────────────────┘

I don't claim to be an expert on solar activity; in fact, that was why I
wrote this program.  I really enjoy reading Tad Cook's PROPAGATION FORECAST
BULLETIN each week (transmitted on W1AW and available on many Packet BBS's)
but I needed some way to put his sunspot and solar flux values into a
format I could relate to my on-the-air experience.  This little program
lets me do that by plotting the sunspot and solar flux values from the
PROPAGATION FORECAST BULLETINS in a graphic format.  I can look at the plot
and look at my logbooks and see why the band was dead on a particular day,
or why propagation was so good on a particular day.

This is not a real fancy program.  It doesn't do MUF plots or anything like
that.  It is just a utility that puts things into perspective for you, and
makes them easier to visualize.  It will hold up to about 2400 daily entries
for sunspot and 10.7cm solar flux values.  The data is displayed graphically
on two screens; one is an overall view showing all of the data from day one
to day "x".  The second is a close-up view of 196 entries.  When the data
file gets quite large the entries get so close together that it is difficult
to see anything on the "Overall" screen.  Also, when you are viewing just a
portion of the data it is difficult to get the "Big Picture".  Therefore, I
give you two screen modes. The overall is generally used for getting an
overall view of the data and the close-up screen is used for looking at more
precise information.  The close-up screen may be "Panned" left or right to
scroll through the data file month-by-month.

The vertical divisions on the screen correspond to days and weeks.  The
days are drawn in gray dotted lines and the weeks are in blue dotted lines.
Monthly divisions (every 28 days starting at the beginning of the file) are
drawn in solid lines.  On the overall screen, the "Day" lines have been
omitted since they are normally too close together to see.

The program was designed to use a Microsoft(tm) compatible mouse as a
pointing device.  It does not require one, but you really need one to get
the most out of the software.  When a mouse is in use, you can "Click" on an
area of the overall screen and the software will automatically switch to the
close-up screen with the selected area in the center of the screen.  Also,
when a Mouse is used, the current position of the Mouse cursor is displayed
on the screen.  This allows you to measure values from the screen.

      ┌──────────────────────────────────────────────────────────────┐
      │                     Hardware Requirements                    │
      └──────────────────────────────────────────────────────────────┘

This program was designed for the IBM-PC(tm) and compatible computers with
the MS-DOS(tm) operating system, Version 2.1 or later with at least 128
Kbytes of available memory.  An EGA or VGA video adapter and monitor are
required, and a Microsoft(tm) compatible Mouse is recommended but not
required.  A hard disk drive with enough capacity to store the program and
data files is highly recommended.

      ┌──────────────────────────────────────────────────────────────┐
      │                        Program Use                           │
      └──────────────────────────────────────────────────────────────┘

Once activated, the program will read the data from the specified data file
and generate a set of averages. The initial display will be on the close-up
screen with the LAST day in the file at the right side of the screen.
Vertical bars denote the days (dotted lines), weeks (bright dotted lines),
and months (solid lines) within the file.  Months as used here are defined
as 4 weeks or 28 days.  The day, week, and month lines are all blue.  The
number of sun-spots for each day are plotted as a green line with the sun
spot average plotted as a dotted cyan (light blue) line.  The 10.7cm solar
flux values are plotted as a violet line with the averages plotted as a
dotted red line.

Those of you with slower machines (especially the old 8086 machines like I
have) should be aware that it may take around a minute to do the average
calculations.  When the program is started, a bar on the title screen will
show the amount of data read, and the amount of the averages that have been
calculated. When the average interval or "Lag" days (see below) are changed
the averages have to be recalculated, so the percentage completed is shown
again during the recalculation.  With faster machines the average
calculations only take a few seconds; my 40 mHz 386 machine only takes
about 8 seconds as opposed to 55 seconds on my 10 mHz 8086 machine.  A math
coprocessor speeds it up to less than 2 seconds on a fast machine.

Both the sunspot and flux values have the same scale.  A sunspot value of
100 will be exactly the same height as a solar flux value of 100.  The
higher on the screen, the higher the value.

The overall screen uses a reduced scale.  I initially wrote the program
without any scaling of the overall data, but it was so difficult to see
that I decided to scale it.  The vertical lines were so high in comparison
to the horizontal divisions that it was impossible to see anything.  With
the reduced scale, the more entries you have in the data file, the smaller
the height of the data.  In other words, as the data is compressed across
the screen, it is also compressed vertically to make it easier to see.

At the top of the screen is displayed the data for the currently selected
day. The "Currently Selected Day" is shown by an arrow at the bottom if the
screen if a Mouse is not in use, or by the Mouse cursor if a Mouse is used.
The data that is displayed is the date, number of sun spots, and the solar
flux from the data file.  If you are using a Mouse, the current vertical
position of the Mouse cursor is also shown so that you may "Measure" a
value from the screen.

The left side of the screen shows:

    o  The number of entries in the data file
    o  The number of days to be displayed on the close-up screen
    o  The number of days in the averaging period
    o  The number of days lag in the averaging period

There are only a few keyboard commands to remember.  Here is a summary of
of them:

[S] ......... Toggles between the OVERALL screen and the CLOSE-UP screen.
              If you are in one screen mode, the program will switch to the
              other mode.

[A] ......... Select a different averaging period.  By default, the program
              uses a 28-day averaging period (since the solar rotation
              period is 27.5 days, this works pretty well), however you may
              set the period for any desired value between 1 and the number
              of days in the file.  More about the averaging later!

[L] ......... Changes the number of "Lag" days in the averaging period.
              This is explained in the section below!

[C] ......... Defines whether cumulative averages for the first and last
              part of the data file are displayed or not.

[D] ......... Changes the number of days displayed on the close-up screen.
              By default the program uses 196 days (or 28 weeks).  This
              gives a pretty good display with enough room between the days
              to see them.  If for some reason, you wish to use a larger or
              smaller number of days, you may set the value by pressing the
              [D] key and then entering the desired number of days to be
              displayed.

[PG UP] ..... This is used to "Pan" the display left (or toward the TOP of
              the data file). It is only active in the Close-up screen.

[PG DN] ..... This is used to "Pan" the display right (or toward the BOTTOM
              of the data file). It is only active in the Close-up screen.

[LT ARR] .... The left arrow key moves the "Current Day" marker to the left
              one day.  The data for the current day (shown at the top of
              the screen) is updated to reflect the new day.  This key is
              active only when a Mouse is not used.

[RT ARR] .... The right arrow key moves the "Current Day" marker to the
              right one day.  The data for the current day (shown at the
              top of the screen) is updated to reflect the new day.  This
              key is active only when a Mouse is not used.

[?] ......... Displays this HELP file!

[ESC] ....... Exits the program and returns to DOS command level.

If you are using a Microsoft(tm) Compatible Mouse, your Mouse buttons can
be used like the [PG UP] and [PG DN] keys in the close-up screen.  When you
are in the overall screen, you can select an area to look at on the close
up screen by placing the Mouse cursor on the desired area and pressing the
LEFT Mouse button.  The program will then switch to the close-up screen
with the identified day at the center of the screen.

There are four "User-definable" parameters; the number of days on the close
up screen, the number of days in the averaging period, the number of "Lag"
days, and whether "Cumulative Averaging" is on or off.  As described above,
all of these values have defaults that are used until you change one.  When
you change one (or more) of the defaults, a configuration file is created
to retain the new default values so that they will be in effect the next
time you run the program. The file is named GRAPH.CFG, and if you want to
edit this file you can, it is just an ASCII file.  The first line is the
number of days on the close-up screen, the second is the number of days in
the averaging period, the third is the number of lag days, and the fourth
line is either a one or a zero to define whether cumulative average display
is on or off.  To just reset everything to the default values, you can just
delete the file GRAPH.CFG.


      ┌──────────────────────────────────────────────────────────────┐
      │                     More About Averaging                     │
      └──────────────────────────────────────────────────────────────┘

Tad Cook (KT7H) has been a great help in getting me straightened out on how
averages should be done. The averaging in this program uses a moving-window
average where each day on the average line represents a value that is the
average of a number of days before and after the current day.  The sketch
below may help you visualize this:

           <-------------- 28 Day Averaging Period -------------->
           ┌─────────────────────────┬───────────────────────────┐
            13 Days Before + Current         14 Days After
  ─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─
  <------------------------- Days in Data File --------------------------->

The average for the current day is calculated by adding the values for a
certain number of days before and including the desired day and a certain
number of days after, then dividing by the number of days in the period.
This means that the "Window" from which the average is calculated "Moves"
as the days progress through the data file.  The number of days in the
averaging period may be defined using the [A] key.

Now, as shown in the following sketch, the number of days "Lag" also comes
into play.  Another method of averaging uses the number of days in the
period BEFORE the desired day to calculate the average.  For a 28 day
period, the average value for any particular day uses the values for the
previous 27 days, along with the current day's value to calculate the
average.

           <-------------- 28 Day Averaging Period -------------->
           ┌─────────────────────────────────────────────────────┐
                        27 Days Before + Current Day             
  ─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─
  <------------------------- Days in Data File --------------------------->

The number of "Lag" days, or the number of days BEFORE the current day,
used to compute the average is variable.  Some people like it one way, some
like it another.  Therefore, it is also user-definable.  You may set the
number of "Lag" days to any value between 1 and the number of days in the
period by pressing the [L] key and entering the desired number of days.
The program will use this value as it's lag value.  The number of days in
the period minus this value will be the number of days AFTER the current
day used to calculate the average.  In other words, if you want the average
to be based on the PREVIOUS 27 days plus the current day, enter 28 as the
lag value. If you want the average to be based on the previous 13 days plus
the current day, and the following 14 days (assuming a 28 day averaging
period) enter 14.

Now, since the averaging period has a certain number of LAG and LEAD days,
the first part of the file and the last part of the file will not have an
average since part of the data required to calculate the averages is not
there.  If you need the previous 14 days to calculate an average, the first
day in the file doesn't have 14 days previous.  Likewise, if you need 14
days past the current day to calculate the average the last day in the file
doesn't have them.  So what do you do about it?  One recommendation is to
just not display this data since anything there would not be a correct
average.  Personally, I prefer to see a cumulative average up to the point
where the moving average can take over.  The choice is yours.  If you want
to see the cumulative average, it is there, displayed in WHITE instead of
the normal color.  If you don't want to see the cumulative averages, they
can be turned off with the [C] key.

      ┌──────────────────────────────────────────────────────────────┐
      │                    Data File Structure                       │
      └──────────────────────────────────────────────────────────────┘

The data that is displayed graphically is stored in a data file on disk.  By
default this file is named GRAPH.DAT but you can name the file anything that
you want to.  You may want to have a file for each year, such as GRAPH.92 or
PFB.93 or whatever you decide.  To run the program with a file different
from the default, just supply the file name on the command line when you
start the program.

Examples ... C>GRAPH .......... Starts the program using GRAPH.DAT
             C>GRAPH PFB.93 ... Starts the program using PFB.93

The structure of the data file is simple.  It is just an ASCII file that may
be edited with any text editor.  Don't use a word processor unless you can
do so in ASCII mode since most word processing software puts special control
characters in the file that would not be understood by this software.

The data file contains three columns of data, all three of which are taken
from Tad Cook's Propagation Forecast Bulletin.  The first is the date,
second is the sunspot value, and third is the 10.7cm Solar Flux value.
Here are some examples:

04/19/91    152   229.0
04/20/91    122   201.0
04/21/91     92   180.0
04/22/91     73   166.0
05/20/93     48    91.1
05/21/93     34    91.0

Notice that the values are right-justified with the columns, or when the
sunspot or solar flux values are less than 100, the right-most characters
line up.  The date starts in column 1.  The sunspot value starts in column
13, and the solar flux value in column 19. If you use the supplied data file
as an example, you won't have any trouble.

      ┌──────────────────────────────────────────────────────────────┐
      │                            Summary                           │
      └──────────────────────────────────────────────────────────────┘

That's about it.  As I said, the program is easy to use, and not too fancy.
I wrote it initially for my own use, but at the request of Tad Cook, I
decided to let it become available to anyone that wants a copy.

If you want to pass it on to someone else, please feel free to.  While I
retain the copyright on the software, I do release it for NOT-COMMERCIAL
and NON-PECUNIARY distribution as long as the all program, data and help
files are transferred together and in an unmodified and unaltered state.

If you have problems or comments about the program, I'd love to hear from
you.  My address is correct in the 1988 or later callbook or as follows:

     Scott Craig - WA4TTK
     409 Jessie Drive
     Nashville, TN 37211
     WA4TTK @ KC4PRD.TN.USA.NOAM  (All Packet Mail)
     WA4TTK @ AA4DO.TN.USA.NOAM   (Southeast US DX PacketCluster Address)

Please include the version number from your copy of the program.  It can be
found on the first screen when the program is started.

We all owe Tad Cook (KT7H) a vote of thanks for the Propagation Forecast
Bulletins he writes each week.  Speaking for myself, I enjoy reading them,
and look forward to them every week.  I also owe him a big Thank You for
his help in the writing of this program.  We have communicated several
times via Packet Mail, and his input has helped make this program much
more useful.

Thanks also go out to Joel - AA5YA for his help in reformatting my HELP
file into a nice documentation file, and Syd - VE3EGO for compiling
the 1989 through 1991 Solar Flux data.  I really appreciate their help!

73's ... Scott Craig ... WA4TTK
