1 NTUPLE
  Syntax: NTUPLE DUMP|MERGE|PLOT|PROJECT|EPROFILE|SPROFILE|FILTER|SCAN

  Does an  operation on an  Ntuple. If you  want to apply  cuts you should
  first  define  them using  `CUT  NEW' or  `CUT FILE',  and  `CUT USE' to
  specify which cuts  should be used. Cuts will  be applied when using the
  `PLOT', `PROJECT', `EPROFILE', `SPROFILE' and `FILTER' commands.

  ColumnWise Ntuples (CWN's) are supported, but do not yet work with
  the `FILTER' or `MERGE' commands.
  If you use a COMIS function for a cut on a CWN
  then you have to give the list of variables that you want to use in
  the COMIS function using the `SET NTUPLE VARIABLE' command. For
  general help on CWN's see HELP ColumnWise_Ntuples.

  Each time you project or scan an Ntuple that is stored with the disk
  option, it is usually refetched from the HBOOK file. This ensures
  that everything is synchronised properly. However, for very large
  Ntuples, this can take a long time.
  You can use the `SET AUTOFETCH OFF' command to suppress the extra
  fetches. In this case you have to make sure that you have not opened
  another file and that the HBOOK directory is set properly.

  Ntuple   commands are  still  under   development. It  is  possible that
  syntaxes will change and very  likely that new commands and options will
  be added.

  When you use a Comis function five common blocks are available to
  you. `MNTPL2' is only available from version 4.03 onwards:

  COMMON /PAWIDN/ IDNEVT,VIDN1,VIDN2,VIDN3
   , X1, X2, ...
  COMMON /MNTPL1/ ID,NVAR,ALO(NVAR),AHI(NVAR)
  COMMON /MNTPL2/ TITLE,TAGS(NVAR)
  COMMON /MNREGI/ REGIS(0:300)
   , VAR1, VAR2, ...
  COMMON /MNDBG/  QDEBUG,NDEBUG
!=

  IDNEVT is the current Ntuple event number
  VIDN1,VIDN2,VIDN3 are the values of the variables you are projecting onto
  X1,X2...          are the Ntuple variables for the current event
  ID                is the Ntuple identifier
  NVAR              is the number of variables
  ALO               are the lower limits for each variable
  AHI               are the upper limits for each variable
  TITLE             is the Ntuple title
  TAGS              are the variable names
  REGIS             are Mn_Fit registers
  VAR1,VAR2         are user defined Mn_Fit variables
  QDEBUG            is a logical set with the SET DEBUG command
  NDEBUG            is the printout level for DEBUG output

  Note that the `PAWIDN'  common block is  compatible with PAW so that you
  should be  able to use the  same functions  in Mn_Fit  and PAW.

  For CWN's the variables are also available in the same common blocks
  as for PAW:

  COMMON /PAWCR4/ rvar1, rvar2
  COMMON /PAWCR8/ zvar1, zvar2
  COMMON /PAWCCH/ cvar1, cvar2

  where `PAWCR4' contains `REAL',`INTEGER' and `LOGICAL' variables,
  `PAWCR8' contains `DOUBLE PRECISION' variables, and `PAWCCH'
  contains `CHARACTER' variables.

  When you specify a Comis function as a cut it will be a real
  function. For a cut and `SCAN' the name of the function will be the
  name of the file without the header and type.  When you give the cut
  to use you can give an argument for the function.

  User variables  are stored in  registers >300.  Therefore you can either
  use the   variable  names or   `REGIS(301)'  etc. in  the  subroutine or
  function. These function as a  substitute for KUIP vectors which are not
  available.

2 Menu
  The following is a list of the available commands.
  For more details see HELP NTUPLE and the individual subtopics:

  DUMP      Dumps the contents of an Ntuple.
  EPROFILE  Makes a profile plot from an Ntuple - errors are error on mean.
  FILTER    Filter an Ntuple by applying cuts.
  MERGE     Merges Ntuples from different files into a single Ntuple.
  PLOT      Projects and plots the projection of an Ntuple.
  PROJECT   Projects an Ntuple.
  SCAN      Calls a Comis subroutine for every Ntuple event.
  SPROFILE  Makes a profile plot from an Ntuple - errors are r.m.s. spread.

2 DUMP
  Syntax: NTUPLE DUMP id [&idb] Y|N|npnt1 [npnt2]
  where   id   is the ntuple identifier
  and     idb  is the (optional) secondary identifier

  Dumps the contents of an Ntuple.
  If you omit the secondary identifier the default is used. If you
  answer `Y' when asked whether you want to see the points they will
  all be dumped. You can also give the range of point numbers that
  should be dumped.

2 EPROFILE
  Syntax: NTUPLE EPROFILE id[&idb] var1 var2 &idb2
          nbinx [xlo xhi]
          ylo yhi [nevt1 nevt]
  where   id       is the ntuple identifier
          var1     is the x-axis variable or expression to project onto
          var2     is the y-axis variable or expression
          idb2     is the secondary identifier of the projection
          nbinx    are the number of bins for the x-axis of the profile
                   plot if the input is an Ntuple.
                   -1 means automatic binning
          xlo      is the lower limit for the x-axis
          xhi      is the upper limit for the x-axis
          ylo      is the lower limit for the y-axis
          yhi      is the upper limit for the y-axis
          nevt1    is the first event to scan
  and     nevt     is the number of events to scan

  Makes a profile plot from an Ntuple. Either variables or expressions can
  be used for both axes. The mean of the y-axis variable is calculated.
  The error on the y-axis variable is the error on its mean.
  Only events that have y-axis variables between the y limits will be used.
  If `ylo' and `yhi' are both 0, no checking will be done.

  Note that for technical reasons the profile plot has both negative
  and positive errors.

2 FILTER
  Syntax: NTUPLE FILTER id&idb [&]idb2 [nevt1 nevt]
      or: NTUPLE FILTER id idb2
  where   id     is the ntuple identifier
          idb    is the (optional) secondary identifier
          idb2   is the secondary identifier of the output Ntuple
          nevt1  is the first event to scan
  and     nevt   is the number of events to scan

  Scans an Ntuple applying the currently selected cuts. Events that
  pass the cuts are stored in a second Ntuple with secondary identifier
  `idb2'.

  This command is useful for applying a preliminary set of cuts on an
  Ntuple to decrease its size.

  This command does not work with CWN's.

2 MERGE
  Syntax: NTUPLE MERGE id fileout filein1 [filein2 [filein3 ...]]
  where   id       is the ntuple identifier
          fileout  is the name of the output file for the Ntuple
          filein1  is the first filename etc.

  Merges several Ntuples with the  same identifier into a single Ntuple.
  A `<CR>'  signifies that the  merging has finished.  The merged Ntuple
  will then be read in and is available for further manipulation.

  This command does not work with CWN's.

  If you want to merge complete RZ files use the command `HMERGE'
  which calls the HBOOK routine `HMERGE' directly.

2 PLOT
  Syntax: NTUPLE PLOT id[&idb] var1 [var2 ...] [#weight [#dweight]] &idb2
          nbinx [xlo xhi]
          [nbiny] [ylo yhi] [nevt1 nevt]
  where   id       is the ntuple identifier
          var1     is the first variable or expression to project onto
          var2     is the second etc.
          weight   is a variable name or number to be used as the weight
          dweight  is a variable to be used as the error on the weight
          idb2     is the secondary identifier of the projection
          nbinx    are the number of bins for the x-axis of the projection
                   if the input is an Ntuple.
                   -1 means automatic binning
                    0 means keep as an Ntuple
          xlo      is the lower limit for the x-axis
          xhi      is the upper limit for the x-axis
          nbiny    are the number of bins for the y-axis
          ylo      is the lower limit for the y-axis
          yhi      is the upper limit for the y-axis
          nevt1    is the first event to scan
  and     nevt     is the number of events to scan

  Projects and  plots the  projection of  an Ntuple or  an n-dimensional
  histogram. For more details see HELP NTUPLE PROJECT.

2 PROJECT
  Syntax: NTUPLE PROJECT id[&idb] var1 [var2 ...] [#weight [#dweight]] &idb2
          nbinx [xlo xhi]
          [nbiny] [ylo yhi] [nevt1 nevt]
  where   id       is the ntuple identifier
          var1     is the first variable or expression to project onto
          var2     is the second etc.
          weight   is a variable name or number to be used as the weight
          dweight  is a variable to be used as the error on the weight
          idb2     is the secondary identifier of the projection
          nbinx    are the number of bins for the x-axis of the projection
                   if the input is an Ntuple.
                   -1 means automatic binning
                    0 means keep as an Ntuple
          xlo      is the lower limit for the x-axis
          xhi      is the upper limit for the x-axis
          nbiny    are the number of bins for the y-axis
          ylo      is the lower limit for the y-axis
          yhi      is the upper limit for the y-axis
          nevt1    is the first event to scan
  and     nevt     is the number of events to scan

  The  project   command has   several  uses. For   example if  you have
  specified cuts on a  plot, use the `PROJECT'  command to make a second
  plot which  shows the  results of the  cuts; or if you  have a scatter
  plot and want to make a binned histogram out of it.

  The end of the list of variables is signified by the end of line or
  the `&' of the secondary identifier.  As for cuts you can give a
  variable name or an expression for the projection. You can also give
  the variable number instead. While this also works for single
  variables in CWNs, it is not a recommended way of proceeding, as it
  does not work for arrays. An expression is recognized if it starts
  with a `(' or if it contains any arithmetic operator `+-*/^()'. Thus
  if, for some strange reason you want to use a register for an axis
  you would have to enclose the register in parentheses `(R1)' so that
  it is recognized as an expression. When an expression is parsed,
  first Ntuple variable names are searched for, then user defined
  variables and then the standard registers, parameters etc.

  If you want to project onto an element of a CWN, use the form
  `var(n)', where `n' is the element number you want to project
  onto. To project many elements of a CWN use the form `var(m,n1:n2)'
  for the case when `var' is a 2-dimensional array. You can also use
  this form inside expressions (see example 8), or when projecting
  onto more than 1 axis (see example 9).

  Note that the limits of each variable of a CWN are not
  known. Therefore you always have to give the limits for plotting
  yourself.

  If you want  one of the Ntuple variables  to be the weight precede the
  variable name   or number by  `#'. For  the error on  the  weight give
  another variable name  or number preceded by `#'.  This form is useful
  if  you  store a series  of  points in   an  Ntuple and  then  want to
  manipulate them as a series of points with errors.

  You only need to specify the binning if the input is an Ntuple. If
  you are projecting a scatter plot, specify 0 bins to keep it as a
  scatter plot, or give the binning if you want the projection to be a
  histogram. If you give the number of bins as -1 automatic binning
  will be used, taking as default lower and upper limits the lower and
  upper limits of the relevant variables in the Ntuple. However, as
  CWN's do not have the limits stored you are always given the
  opportunity to specify your own limits. If you want to keep the
  suggested limits just hit `<CR>' when asked for new limits. If you
  want to plot the result directly you can use the `NTUPLE PLOT'
  command.

  If you project onto a scatter plot then you can also give the limits
  on 1 or more of the axes for the projections - see example 4. These
  limits will be used as cuts, i.e. any events outside the limits will
  be dropped.

  The first event and  the number of events  to  be scanned can also  be
  given. If you omit them all events in the Ntuple will  be scanned.  If
  you specify 0  bins (i.e. you want to   make a scatter  plot, then you
  must give the limits for both axes if you  also want to give the event
  numbers. Use limits of 0 0 if they should be taken from the Ntuple.

  If you want to make a plot vs. date or time, you can use the various
  time expressions that are available (see HELP Expressions). Note
  that the reference time is always set to 80/01/01 00:00 for such
  plots. This should be changed in the future when I have a bit more
  experience with such plots. Use the command `SET X MODE DATE|TIME'
  to decide is the plot should be stored in terms of days or
  minutes. Somewhat more flexibility is available if the information
  is stored in an ASCII file and can then be read in using the
  `DAT_FETCH' command.

3 Examples

!\begin{enumerate}
!\item
!^
  Example 1:
   Project an Ntuple onto a 2-D histogram using automatic binning:
     FET 10 filename
     PROJ 10 VAR1 VAR2 &1 -1

!\item
!^
  Example 2:
   Project the sum of 2 variables and specify the binning:
     PROJ 10 (VAR1+VAR2) &2 100 0 50

!\item
!^
  Example 3:
   Make a scatter plot of an expression and a variable using
   a COMIS function as a cut plus a cut on another variable.
   Let the limits be calculated internally.
   Start scanning at event 100 and do 1000 events:
     CUT DEL 0
     CUT
     NEW VAR4.GT.5
     FILE CUT_NTUPLE.FOR
     USE 1 .OR. 2
     END
     NTUPLE PLOT 10 var3 (var1/var2) &3 0 0 0 0 0 100 1000

!\item
!^
  Example 4:
   Make a scatter plot of an expression and a variable using
   a COMIS function as a cut plus a cut on another variable.
   Specify the limits. Start scanning at event 20 and do 2000 events.
   This is the same as Example 3, except for the limits:
     CUT DEL 0
     CUT
     NEW VAR4.GT.5
     FILE CUT_NTUPLE.FOR
     USE 1 .OR. 2
     END
     NTUPLE PLOT 10 var3 (var1/var2) &3 0 -3 3 0 10 20 2000

!\item
!^
  Example 5:
   Project a 2-D histogram onto 1 of its axes:
     NTUPLE PLOT 10 1 &1

!\item
!^
  Example 6:
   Project a 2-D histogram onto the sum and difference of the axes.
   If you project onto an expression the lower and upper limits on
   each variable will be used and the expression evaluated for them.
   These will then be the default limits for the projection.
   This is usually not what you want and so you should set the limits
   afterwards by hand:
     NTUPLE PROJ 1 (X+Y) X-Y &4  -1
     partition 1&4 -5 5 -10 10

!\item
!^
  Example 7:
   Project an Ntuple onto a series of points and use one of the variables
   as the y value and another as its error:
     NTUPLE PROJ 1 X #WEIGHT #ERR &5 0

!\item
!^
  Example 8:
   Project the absolute value of a range of CWN array entries onto a
   1-dimensional histogram (note that if nval2 = 0, no entry will be
   made in the projection):
     ntuple plot 34 abs(rval2(1:nval2)) &11 75 -5 10

!\item
!^
  Example 9:
   Project a range of CWN entries into a scatter plot. Note that the
  scatter plot limits must be given as the limits for CWN variables
  are not known::
     ntuple plot 34 abs(rval2(2:nval2)) rval3(2,2:nval2) &12 0 -
      -5 10 -10 10

!\end{enumerate}

2 SCAN
  Syntax: NTUPLE SCAN id[&idb] filename[(arg)] Y|N [nevt1 nevt]
  where   id        is the ntuple identifier
          idb       is the (optional) secondary identifier
          filename  is the name of a file containing the Comis subroutine
                    that should be called
          arg       is an optional argument for the subroutine
          nevt1     is the first event number to scan
          nevt      is the number of events to scan

  Loops over all the events in an Ntuple and calls a function  which  is
  contained in  `filename'. If the  file does not  exist a skeleton file
  with the common  blocks containing  information on  the Ntuple will be
  created. You  will be asked if you  want to edit  the file or not. The
  function  will be  called with the  optional argument `arg', which can
  be a  register, parameter  etc. If it is  not given it  will be set to
  `0.0'.

  After the scan all HBOOK histograms in the current directory in memory
  will  be read  in as   Mn_Fit   histograms. If  you  also want  to get
  histograms from another directory  you can use the command `HB_MN_FIT'
  (see HELP HB_MN_FIT for more details).


2 SPROFILE
  Syntax: NTUPLE SPROFILE id[&idb] var1 var2 &idb2
          nbinx [xlo xhi]
          ylo yhi [nevt1 nevt]
  where   id       is the ntuple identifier
          var1     is the x-axis variable or expression to project onto
          var2     is the y-axis variable or expression
          idb2     is the secondary identifier of the projection
          nbinx    are the number of bins for the x-axis of the profile
                   plot if the input is an Ntuple.
                   -1 means automatic binning
          xlo      is the lower limit for the x-axis
          xhi      is the upper limit for the x-axis
          ylo      is the lower limit for the y-axis
          yhi      is the upper limit for the y-axis
          nevt1    is the first event to scan
  and     nevt     is the number of events to scan

  Makes a profile plot from an Ntuple. Either variables or expressions can
  be used for both axes. The mean of the y-axis variable is calculated.
  The error on the y-axis variable is its r.m.s.
  Only events that have y-axis variables between the y limits will be used.
  If `ylo' and `yhi' are both 0, no checking will be done.

  Note that for technical reasons the profile plot has both negative
  and positive errors.
