1. Description:
---------------
The VARTOOLS program is a command line utility that provides tools for
processing and analyzing astronomical time series data (a.k.a. light
curves). It includes methods for calculating variability/periodicity
statistics of light curves; for filtering, transforming, and otherwise
modifying light curves; and for modeling light curves. It is intended
primarily for batch processing a large number of light curves. The
program is run by issuing a sequence of commands to perform actions on
light curves, each command is executed in turn with the resulting
light curves passed to the next command. Statistics computed by each
command are sent to stdout as an ascii table.

2. Disclaimer:
--------------
This program is available without any warranty - use it at your own
risk. If you do find a bug, please let me know so that I can fix it
(jhartman@astro.princeton.edu). Also feel free to let me
know if there are any commands/algorithms that you would like to see
added to this program.

3. Citation:
------------
If you use this program, please cite Hartman and Bakos 2016, Astronomy
and Computing, 17, 1. Also, be sure to cite the relevant sources for
the algorithms that you use.

4. Documentation on Usage:
--------------------------
Help on usage of the program can be found at
http://www.astro.princeton.edu/~jhartman/vartools.html

5. General Installation notes:
------------------------------
As of VARTOOLS version 1.32 the GNU autobuild system is used for
configuring, compiling and installing the software. The program was
developed in a 64-bit linux environment (specifically Ubuntu 14.04),
so it has been most fully-debugged in linux or other POSIX-compatible
environments. It has been successfully installed on Mac (using Xcode
and homebrew GNU packages) and Windows 32 (mingw) systems as well.

6. Dependencies:
----------------
Although VARTOOLS can be compiled without using non-standard external
libraries, several features depend on outside libraries. To use these
features you will need to install the following libraries on your
system.

   A. CFITSIO:
      Needed for reading binary-fits format light curves (e.g. processing
         Kepler light curves).
      http://heasarc.gsfc.nasa.gov/docs/software/fitsio/fitsio.html

   B. PTHREAD:
      Needed for parallel processing of light curves. This is standard on
      linux and Mac, for windows you will need to install the pthreads-win32
      library (http://sourceforge.net/projects/pthreads4w/)

   C. GSL (GNU scientific library):
      Needed for the -addnoise, -microlens, -resample, -FFT and -IFFT commands.
      http://www.gnu.org/s/gsl/

   D. DYNAMIC LIBRARY SUPPORT:
      User-compiled commands and analytic functions are supported through
      loading dynamically linked libraries. The 'configure' script should 
      detect and make use of whatever framework your system uses to
      accomplish this. On linux you would need libdl.so, dlfcn.h and ctype.h.
      On Mac you would need dlfcn.h and ctype.h, but not libdl.so. On windows
      DLL support is accomplished through windows.h. I have not fully tested
      this feature on Mac or Windows, so bugs may be present.

   E. JPL NAIF CSPICE:
      Needed for converting to/from BJD and UTC/TDB in the -converttime
         command.
      http://naif.jpl.nasa.gov/naif/toolkit_C.html

      Additionally, the following kernel files storing ancillary
         time/solar-system data should be downloaded and stored in 
         e.g. the ${HOME}/.vartools directory:

      ftp://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/planets/de432s.bsp
      ftp://naif.jpl.nasa.gov/pub/naif/generic_kernels/lsk/naif0011.tls
      ftp://naif.jpl.nasa.gov/pub/naif/generic_kernels/pck/pck00010.tpc

      Note that new versions of these files are regularly released. 
      You should check the directories (e.g.
      ftp://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/planets/
      ftp://naif.jpl.nasa.gov/pub/naif/generic_kernels/lsk/
      ftp://naif.jpl.nasa.gov/pub/naif/generic_kernels/pck/ )
      For any newer versions. Also note that whenever there is a leapsecond
      you will need to download and install the newest version of
      naif*.tls.

      On a *nix system you may want to add the following lines to your
      .bashrc file (or the equivalent version to your .cshrc file):

      export CSPICE_EPHEM_FILE=${HOME}/.vartools/de432s.bsp
      export CSPICE_LEAPSEC_FILE=${HOME}/.vartools/naif0011.tls
      export CSPICE_PLANETDATA_FILE=${HOME}/.vartools/pck00010.tpc

      Alternatively the path to these files can be specified on the
      command line when calling VARTOOLS.

   E. Python and Numpy
      Needed for the -python command to allow calling python routines
      on light curves through vartools. Python version 2.6 or greater is
      required. The minimum required version of numpy has not been determined,
      but this has been built and used successfully with versions from 1.6.2 to
      1.11.1.

      https://www.python.org/
      http://www.numpy.org/
      
   F. R (Statistical Computing Software Environment)
      Needed for the -R command to allow calling R routines on light
      curves through vartools. The minimum R version required has not
      been determined. But this has been built and tested on version
      3.4.2. You will need the R library file (libR.so on linux) and
      header files (Rinternals.h, Rembedded.h and R_ext/Parse.h). You
      will also need to set the R_HOME environment variable in the
      shell you are calling vartools from in order to use the -R
      command.

      If this is not already defined, then n a *nix system you may
      want to add the following lines to your .bashrc file (or the
      equivalent version to your .cshrc file), where we assume R is in
      your PATH:

      export R_HOME=$(R RHOME)

      https://www.r-project.org/


7. Download and unpack the VARTOOLS source:
-------------------------------------------

   For example, the following commands might be used:

      cd ${HOME}/src/

      wget \
        http://www.astro.princeton.edu/~jhartman/vartools/vartools-1.38.tar.gz

      tar -xzvf vartools-1.38.tar.gz

      cd vartools-1.38

8. Configure VARTOOLS:
----------------------

   Type './configure' to create the Makefile. You will probably need
   to supply some options and set some environment variables so that
   VARTOOLS installs to the correct location on your system, and so
   that all of the necessary library and header files can be found (in
   particular, if CFITSIO, GSL and/or CSPICE are not installed to
   locations in your LD_LIBRARY_PATH). You may also need to change the
   compiler (and compiler options) used.  

   The following directories are used for installation:

      PREFIX=/usr/local
      BINDIR=$(PREFIX)/bin
      LIBDIR=$(PREFIX)/lib
      DATAROOTDIR=$(PREFIX)/share
      DOCDIR=$(DATAROOTDIR)/doc/vartools      

      vartools executable -->  $(BINDIR)
      libvartools --> $(LIBDIR)
      Documentation --> $(DATAROOTDIR)
      User-developed commands --> $(DATAROOTDIR)/vartools/USERLIBS/
      User-developed functions --> $(DATAROOTDIR)/vartools/USERFUNCS/
      Data for examples --> $(DATAROOTDIR)/vartools/EXAMPLES

   These may be changed using options such as

      --prefix=${HOME}/ (install vartools to the bin subdirectory of
        your home directory, the documentation to
        ${HOME}/share/doc/vartools/, etc.)

      --bindir=${HOME}/bin  (modify only the bin directory)

      --libdir=${HOME}/lib

      --datarootdir=${HOME}/share

      --docdir=${HOME}/doc

      Note that if you do not change the prefix, you will need to have
      root permission to carry out 'make install'

   You will also likely need to supply additional paths for locating
   libraries and header files. These can be set using the LDFLAGS and
   CPPFLAGS variables, respectively. They can either be exported as
   environment variables before running configure, or passed to
   configure as options. Note that these variables are passed directly
   to the linker and compiler, and so need to include the appropriate
   flags. For example, if the CFITSIO library file libcfitsio.so is in
   the directory /home/jhartman/src/cfitsio/ and the header file
   fitsio.h is in this same directory, running
       './configure LDFLAGS=-L/home/jhartman/src/cfitsio/ \
           CPPFLAGS=-I/home/jhartman/src/cfitsio/'
   will make sure that the library and header files for cfitsio may be found.

   Finding the cspice library is a special case due to the non-standard
   naming convention which prevents the linker for automatically
   finding it. By default the configure script will search for the
   library at /usr/lib/cspice.a and for the SpiceUsr.h header file in
   /usr/include/cspice. If it does not find these files, it will not
   include the CSPICE features in VARTOOLS. You can specify an
   alternative location for these files using the --with-cspice-lib
   and --with-cspice-include options to configure.  For example, if
   you have cspice.a in /home/jhartman/src/cspice/lib and SpiceUsr.h is in
   /home/jhartman/src/cspice/include you would do:
      './configure --with-cspice-lib=/home/jhartman/src/cspice/lib/cspice.a \
           --with-cspice-include=/home/jhartman/src/cspice/include/'
   Note that --with-cspice-lib includes the cspice.a name of the file,
   whereas --with-cspice-include is just the directory.

   If you wish to enable the -R command, you will also need to tell
   configure how tot find the R library and header files (libR.so, 
   Rinternals.h, Rembedded.h and R_ext/Parse.h). These are typically
   in the directories ${R_HOME}/lib/ and ${R_HOME}/include/ where R_HOME
   can be found by issuing 'R RHOME' on the command line. You can supply the
   value of R_HOME to ./configure using the --with-RHOME=${R_HOME} keyword, or
   you can specify the include and library directories separately using the
   --with-R-include=PATH and --with-R-lib=PATH options.

   Another issue to consider is the fortran compiler, which is used to
   compile some of the extensions. You can change the fortran compiler
   using the FC and F77 variables (the former is used for f90 code,
   the later for f77 code). On my own system running ubuntu 14.04
   these default to gcc, which fails to compile the command
   extensions, so I need to set both to gfortran.

   Below is an example run of configure which sets things to install
   the vartools binary in ${HOME}/bin, the library in ${HOME}/lib and
   the shared data (extensions, documents, example data) in
   ${HOME}/share, and which adds options for finding the cfitsio,
   cspice, and R libraries, and specifies gfortran as the fortran
   compiler:

   ./configure --prefix=${HOME}/ \
      --with-cspice-lib=${HOME}/src/cspice/lib/cspice.a \
      --with-cspice-include=${HOME}/src/cspice/include \
      --with-RHOME=${R_HOME} \
      CPPFLAGS="-I${HOME}/src/cfitsio" \
      LDFLAGS="-L${HOME}/src/cfitsio" \
      F77=gfortran FC=gfortran

9. Compiling VARTOOLS:
----------------------

   To do the compilation type:

      make

   If it's successful a 'vartools' executable file will be created in
   the src subdirectory.  If it fails and you cannot figure out the
   problem, feel free to contact the author (see section 13
   below). Note that the executable created in the src subdirectory
   will most likely fail with an error about missing libraries if you
   try to run it. You need to issue 'make install' and then execute
   the version installed to the binary directory.

10. Installing VARTOOLS:
------------------------

   To install type:

      make install

   See section 3 for changing the installation location. Note that if
   you are installing to the default location of /usr/local you will
   need root permission to do this, so may need to run

      sudo make install

   If you don't have root permission, or do not want to make a
   system-wide installation, you should re-run configure with the
   --prefix option to set the installation to a location where you
   have write permission.

11. Testing VARTOOLS:
---------------------

   If your bin directory is in your PATH, then you should be able to
   type 'vartools' to execute the program. Otherwise you will need to
   specify the path on the command line (e.g. 'src/vartools'). The
   discussion below assumes that it has been installed somewhere in
   your PATH.

  The command:

      vartools -help

   will give you a brief synopsis of the program.

      vartools -listcommands

   will give you a list of all commands which may be issued.
   You can use the -example command to get various examples. e.g.:

      vartools -example -LS

   The command

      vartools -i EXAMPLES/2 -oneline -ascii \
          -LS 0.1 10. 0.1 5 1 EXAMPLES/OUTDIR1 whiten clip 5. 1

   If run from the same directory where you did 'make' and 'make
   install' should produce the output:

      Name                     = EXAMPLES/2
      LS_Period_1_0            =     1.23440877
      Log10_LS_Prob_1_0        = -4000.59209
      LS_Periodogram_Value_1_0 =    0.99619
      LS_SNR_1_0               =  116.60562
      LS_Period_2_0            =     0.55747493
      Log10_LS_Prob_2_0        =  -85.74406
      LS_Periodogram_Value_2_0 =    0.11152
      LS_SNR_2_0               =   14.48656
      LS_Period_3_0            =     0.54669773
      Log10_LS_Prob_3_0        =  -42.14997
      LS_Periodogram_Value_3_0 =    0.05837
      LS_SNR_3_0               =    8.23508
      LS_Period_4_0            =     0.33412568
      Log10_LS_Prob_4_0        =  -33.07258
      LS_Periodogram_Value_4_0 =    0.04868
      LS_SNR_4_0               =    9.78596
      LS_Period_5_0            =     0.25922584
      Log10_LS_Prob_5_0        =  -24.23642
      LS_Periodogram_Value_5_0 =    0.03682
      LS_SNR_5_0               =    9.51180

12. Creating VARTOOLS Extensions:
---------------------------------

   It is possible to add new commands and analytic functions to
   VARTOOLS by creating dynamic libraries that are loaded at
   run-time. Help on creating commands can be found in
   USERLIBS/ReadME.USERLIBS while help on adding analytic functions
   recognized by the VARTOOLS analytic expression evaluation can be
   found in USERFUNCS/ReadME.USERFUNCS.

13. Bugs/Feedback:
------------------

   Please send bug reports or other feedback to Joel Hartman 
   (jhartman AT astro DOT princeton DOT edu).


