
    External preparation of input files for HYBALL and HYFAC


    File HYCODE is no longer a schematic program for putting an externally
computed factor pattern into a file that HYBALL or HYFAC accept as input,
but an ordinary-language description of the form this needs to take.  If
your pattern and factor correlations - or any rescaling of these by a
global constant to omit decimal points - are in a textfile, you can easily
use a text-editor to shape that into HYBALL-readable form.  >>> NOTE:  You
must name this file as described next or HYBALL (HYFAC) will not recognize
its existence.

    HYBALL can upload any ASCII file in the currently active directory whose
basename begins with INHY or whose name's extension starts with one of
letters B, C, H, K, M, Q.  In contrast, HYFAC requires the basenames of
files it will load to start with the letters FAC.  Apart from this difference
in name requirements, both HYBALL and HYFAC can process a factor pattern from
an appropriately named ASCII file so long as its contents consist of one to
three blocks of consecutive lines, detailed below, that can include or be
separated by blank lines.  (To clarify any obscurities you may find in the
descriptions here, examine the form of a FAC*.H* or HYF*.C* file written by
HYBALL.)


1st block (optional): One or more header lines describing this file's
    contents. No header line may begin with a numeral, but otherwise
    can say anything you want.  (Additional information that usually
    follows on this line is optional.)

2nd block: The first line of this must start with the number NV of
    variables in the pattern, followed after a space or comma by its
    number NF of factors.  Immediately below that comes each row of
    the to-be-rotated factor pattern just as the pattern is orthodoxly
    printed.  If necessary, each pattern row can be wrapped.

      NOTE: The complete 1st line of this block has form
                     NV  NF  NX  KODE  MTH  F2
      where NX is number of X-set variables, KODE is a code number, MTH
      codes certain method variants, and F2 names the originating COV-file.
      Lacking input on the latter, HYBALL defaults to NX = KODE = MTH = 0
      and F2 = '?'.  If the first NX factors in your pattern are to be
      treated as X-set (exogenous input) factors, the first line of Block 2
      must include the numerical value of NX immediately after NV and NF.
      Lacking F2, which should be given extension ".COV", HYBALL cannot
      name the variables or enable TWOLOGS comparsons with rotations of a
      different input pattern.

3rd block (sometimes optional):
    If the input factors are orthonormal and the pattern is correctly
    scaled, this can be left entirely blank.  Otherwise:

      (Only for input to HYBALL.) If the input factors are orthonormal but
      each pattern element in Block 2 has been multiplied by a scaling
      integer K (say 100 or 1000) to eliminate need for decimals in the
      input, block 3 can be a single line consisting of 1 followed after a
      space or comma by integer K.  (If for some reason you prefer, you can
      substitute any integer less than the number of factors for the first
      term in this line.)

      If the input factors are NOT orthonormal you must enter the factor
      covariance matrix, which HYBALL presumes to contain correlations
      rescaled by the same multiplier K, if any, that has rescaled the
      pattern coefficients in Block 2.  You may enter this either as a
      square symmetric matrix containing NFNF terms, or its lower triangle
      that contains NF(NF+1)/2 terms.  If you opt for the full square,
      this must be preceded by a line containing NF followed by the integer
      that equals NF.  If you enter the lower triangle, this must
      be preceded by a line containing NF followed by the integer that
      equals NF(NF+1)/2.

UPLOADING ITEM NAMES (optional):
      If you want names for the variables, these must be listed in a separate
      file whose name is the F2 entered in sixth place in the optionally
      extended first line of your HYBALL-input file described above.  Fake
      COV-file F2 can begin with any documentation you wish so long as no
      line commences with a number.  The first line following that must
      start with the number of names provided (this should be the number
      NV of variables in the factor pattern), optionally followed by some
      information in standard COV-files not needed here.  Next comes a header
      line that standardly reads "Names assigned to the variables" albeit
      only its initial "N" is required.  Finally, list your variable's names
      in order of their occurrence in the factor pattern.  Names must be
      separated only by spaces (no commas or other intervening punctuation),
      and entered in a line that can be wrapped however you wish.  (See
      MODCODE.TXT in this package for constraints on permissible names.)
      An example of this construction is shown below.

      In general, names for the variables are optional for Hyball rotation.
      You will, however, need them if you want to make TWOLOGS comparisons
      between rotations of this input pattern and rotations of another
      uploaded by HYBALL from an H-file different from the one constructed
      here.  TWOLOGS compares rotations just on pattern lines that can be
      paired either by item names or by item indexes in a common rawdata
      file.  (Telling how to simulate the latter serves no purpose here,
      but email me if you really want to know.)


A fake COV-file to pass namelist is shown between the dashed lines.  It is
only a fragment of a proper COV-file, but suffices to keep HYBALL happy.
---------------------------------------------------------------------------
[ Documenation allowed here, but not required and probably pointless ]

5 [ Number of names; additional material standardly listed on this line isn't needed ]
Names assigned to the variables:
  John Mary Tom Dick Harry
---------------------------------------------------------------------------

