file: Usages

This file contains concise syntax descriptions for commands in the HRV
toolkit.  Square brackets ([]) surround optional arguments, and
vertical bars (|) indicate alternatives; neither the brackets nor the
bars appear literally in the commands.

NOTE: plt_rrs and get_hrv must be given at least a pair of arguments,
which specify the input.  If the input is a text file containing RR
intervals, the arguments should be "-R" and the name of the file; if
the input is an annotation file, the arguments should be the record
name and the annotator name. (The annotator name is the last part of
the annotation file's name, following the '.', and the record name is
everything up to, but not including, the '.'.)

________________________________________________________________________________

plt_rrs :   Plot RR intervals or RR interval heart rates

  usage: plt_rrs [options] -R rrfile | record annotator [start [end]]

  input:
    an RR interval list (text file) or an annotation file (see note above)
  output:
    a plot (either on screen or, with -o option, in a PostScript file)
  options :
    [-P 2|4|8|16|24|32] : plot 2, 4, 8, 16, 24 or 32 hours per page
                          (default: scale page length to data length)
    [-R rrfile] : RR interval file : time (sec), interval
    [-N] : plot NN intervals instead of RR intervals
    [-H] : plot RR/NN interval heart rate
    [-F "filt hwin"] : filter intervals, plot filtered data
    [-f "filt hwin"] : filter intervals
    [-p] : plot points
    [-I c|h|m] : input time format: hh::mm:ss, hours, minutes (default: seconds)
    [-m] : RR intervals in msec
    [-y "ymin ymax"] : y axis limits
    [-o] : output PostScript (default: show output on-screen)

   Exclude data outside a time interval by adding start and optional
   end time specifications to the end of the command.  (Specify times
   as HH:MM:SS; default is to include all available input data.)
________________________________________________________________________________

get_hrv :	Get HRV statistics

  usage: get_hrv [options] -R rrfile | record annotator [start [end]]

  input:
    an RR interval list (text file) or an annotation file (see note above)
  output:
    REC : NN/RR AVNN SDNN SDANN SDNNINDX RMSSD PNN :
	  TOTPWR ULF VLF LF HF LF/HF
    with the -S option displays an on screen HRV plot or, with -o option,
    outputs an HRV plot in a PostScript file)
  options :
    [-R rrfile] : RR interval file : time (sec), interval
    [-f "filt hwin"] : filter outliers
    [-p "nndiff ..."] : nn difference for pnn (default: 50 msec)
    [-P "lo1 hi1 lo2 hi2 lo3 hi3 lo4 hi4"] : power bands
	(default : 0 0.0033 0.0033 0.04 0.04 0.15 0.15 0.4)
    [-s] : short term stats of
          REC : NN/RR AVNN SDNN RMSSD PNN : TOTPWR VLF LF HF LF/HF
    [-I c|h|m] : input time format: hh::mm:ss, hours, minutes (default: seconds)
    [-m] : RR intervals in msec
    [-M] : output statistics in msec rather than sec
    [-L] : output statistics on one line 
    [-S] : plot HRV results on screen

  plotting options :
    [-F "filt hwin"] : filter outliers, plot filtered data
    [-y "ymin ymax"] : time series y-axis limits ("- -" for self-scaling)
    [-X maxfreq] : fft maximum frequency (default : 0.4 Hz)
    [-Y fftmax] : fft maximum ("-" for self-scaling)
    [-o] : output plot in postscript
________________________________________________________________________________

statnn :  Calculate nn interval stats

  usage: statnn [options]

  input:
    (from stdin) time(sec), interval(sec), annotation  
  output:
    see -s and -L options below
  options :
    [-l len] : window length (default 5:00)
    [-m] : RR intervals in msec
    [-p nndif ...] : nn difference for pnn
    [-s] : short term stats
           nn/rr, avnn, sdnn, rmssd and pnn on stderr
    [-L] : print ratio avnn sdnn sdann sdnnindx rmssd pnns on one line
________________________________________________________________________________

rrlist : Convert annotation file to RR interval list

  usage: rrlist annotator record [options]

  input:
    an annotation file, specified by annotator and record names (note that
    arguments are in reverse order)
  output:
    RR interval list (to stdout) 
  options are :
    [-f start] : begin at time 'start'
    [-t end] : end at time 'end'
    [-l length] : output for duration 'length'
    [-n count] : output 'count' intervals
    [-c] : output time in hh:mm:ss in first column
    [-h] : output time in hours in first column
    [-m] : output time in minutes in first column
    [-s] : output time in seconds in first column
    [-e] : output elapsed time from start
    [-a annotation] :   list only intervals between consecutive annotations
    [-r] : output ratio of specified annotation intervals to RR intervals
    [-H] : high precision intervals (8 significant digits vs 3)
    [-M] : output intervals in msec
________________________________________________________________________________

filt : Read 1 (y) or 2 (x,y) columns from stdin and filter outliers
  by deleting those intervals outside of `filt' range of the average
  within a window `hwin' distance on either side of the current
  interval

  usage: filt filt hwin [options]

  options :
    [-x min max] : exclude data outside min - max
    [-n] : print ratio of nout to nin
    [-p file] : print excluded points to file not including start/end
       hwin buffer; excluded points may not be printed in time sequential
       order if -x option is used
________________________________________________________________________________

filtnn : Read 2 (y,ann) or 3 (x,y,ann) columns from stdin and filter
  NN intervals by marking intervals not within `filt' range from the
  average of intervals within a window `hwin' distance on either side
  of current interval

  usage: filtnn [options] filt hwin

  options:
    [-n] : print ratio of nnout to nnin to rrin
    [-x min max] : exclude data outside min - max
    [-p] : print excluded data at start/end of hwin buffer
    [-C ann] : change annotation of excluded points to ann (default: X)

  To restore time order, pipe the output series through 'sort -n'.
________________________________________________________________________________

pwr : Calculate total (and relative) power in fft between lo and hi.

  usage: pwr [-r] [-L] lo1 hi1 ... [lo10 hi10]

  options :
  [-r] : print ratio of powers to total
  [-L] : print powers on one line

  Specify additional bands (up to 10 in all) by appending more lo and hi
  arguments to the command.
________________________________________________________________________________

seconds :  Convert string in [[hh:]mm:]ss to seconds

  usage: seconds [[hh]:mm]:ss | -

  `-' to read stdin
________________________________________________________________________________

hours :	   Convert seconds to hh:mm:ss

  usage: hours seconds | -
  
  `-' to read stdin
________________________________________________________________________________
