barsN.fun(x,y,initial,iknots,prior,priorparam,burnin,sims,
       tau,c,fits,peak,conf,bins)

 Prior to using this Swrapper, one must build a CHAPTER with the file
 barsN.c.  You must make the shared library available with the
 dyn.open("S.so") command.  Also, the barsN.c program must be properly
 compiled, with the compiled program saved as barsN.out.  WARNING:
 Please note that this program creates or overwrites several files,
 entitled "bars_points", "bar_params", "samp_mu", "samp_params",
 "summ_mu", "summ_mugrid", "summ_params", "prior_knots", and
 "samp_knots".  Care should be made to avoid accidentally deleting files. 
 

 This S wrapper for the BARS code has the following input:

 Required: 

  x  
     a vector of the independent variable, in increasing order

  y   
     a vector of the dependent variable


 Optional:

 Initial knots settings (optional):

  initial
     use logspline ("logspline") or evenly spaced ("even" or "equal")
     for initial knots (default is "logspline")

  iknots
     the initial number of knots for the spline (default = 3)


 Settings on prior for knots (optional):

  prior
     the type of prior being used for the knots (the only acceptable
       answers are "Poisson", "uniform", and "user"  - default = "Poisson")

  priorparam
     the parameter for the prior
     a) if using Poisson, the choice for lambda = mean (default = 2.0)
     b) if using Uniform, a vector of length 2 which includes the
   minimum number of knots followed by the maximum number of knots
     c) if using user-defined prior, a matrix with 2 columns.  The
   first column should be the number of knots and the second column
   should be the probability of obtaining this number of knots.
   Note the following example:
     
       2 0.05
       3 0.15
       4 0.30
       5 0.30
       6 0.10
       7 0.10

 MCMC settings (optional):
 
  burnin
     the desired length of the burn-in for the MCMC chain 
    (default = 200)

  sims
     the number of simulations desired for the MCMC chain 
    (default = 2000)

 tau 
     parameter that controls the spread for the knot proposal
       distribution (default = 50.0) 
 
  c 
     parameter that controls the probability of birth and death
       candidates (default = 0.4)


 Output settings (optional):

  fits
     if "T", the program will return the fitted values for each
       data point for each run of the simulation (default = F)  Please
       note that if the number of data points and/or simulations is
       large, there may be a lengthy delay as the necessary data is
       read.  

  peak
     if "T", the program will return the location and height of the
       highest point on the fitted curve (default = T)

  conf
     for use with peak.  Sets the limits for the credible intervals
       for the location and height of the peak.  (default = 0.95 for 95%
       credible intervals).


 Other settings (optional):


  bins
     the number of bins one desires the x-axis to be divided into -
       used to handle unbinned data and calculate posterior modes
       (default = 150)


 Note that due to the large amount of output generated by the program,
 it is desirable to save the results of the program into a
 variable, such as:

 q_barsN.fun(x,y,.....)
 

 The Swrapper performs the operation by reading the data into the
 file "bars_points", reading the settings into the file "bar_params" and
 running the program in a unix setting.  The following information is
 returned in the output:


 postmeans 
    vector of the posterior means evaluated at the x values

 postmodes 
    vector of the posterior modes evaluated at the x values

 trials 
    vector of each trial number, beginning at burnin + 1 and
       ending at burnin + sims

 no.knots 
    vector of the number of knots used at each trial (does not include
       burnin iterations)

 sampknots
    matrix containing the position of the knots at each iteration.
       Length of the matrix is equal to the number of iterations, not
       including burnin iterations, with the width of the matrix equal to
       the maximum number of knots at any iteration.  NAs are used to
       fill in the matrix at iteration numbers that have less than the
       maximum number of knots.

 sampBICs 
    vector of the calculated BIC at each trial (does not include burnin
       iterations) 

 sampllikes 
    vector of the calculated loglikelihood at each trial (does not
       include burnin iterations)


 Optional output for fits setting:

 sampfits
    matrix of fits for each trial (does not include burnin
       iterations), with the rows of the matrix corresponding to the
       individual trial.  The columns represent the fits at each value
       of x.


 Optional output for peak setting:

 samplpeaks 
    vector of the x location of the highest point in the fitted
       curve for each trial (does not include burnin iterations)

 samphpeaks 
    vector of the y value (height) of the highest point in the
       fitted curve for each trial (does not include burnin iterations)

 peaklocationquantile
    a credible interval for the x location of the highest peak; width
       of the interval is dependent upon the setting chosen for conf

 peaklocationmean 
    the mean x location for the highest peak

 peaklocationmode 
    the mode x location for the highest peak

 peakheightquantile 
    a credible interval for the y value (height) of the highest peak;
       width of the interval is dependent upon the setting chosen for
       conf

 peakheightmean 
    the mean y value (height) of the highest peak

 peakheightmode 
    the mode y value (height) of the highest peak