VARTOOLS
========

Light-curve analysis tools — a command-line C program and Python API
for analyzing astronomical photometric time series.

    Website:       http://www.astro.princeton.edu/~jhartman/vartools.html
    Legacy docs:   http://www.astro.princeton.edu/~jhartman/vartools_old.html
    GitHub:        https://github.com/joeldhartman/vartools
    Contact:       Joel D. Hartman <jhartman@astro.princeton.edu>


1. Description
--------------

VARTOOLS is a collection of tools for analyzing astronomical photometric
time series (light curves).  It is written in C and runs from the command
line, or via the Python package ``pyvartools``, processing one or many
light curves through a user-defined pipeline of statistical, filtering,
period-finding, and model-fitting operations.  The program is designed to
enable efficient batch processing of large light-curve collections.


2. Citation
-----------

If you use VARTOOLS in published research, please cite:

    Hartman, J. D. & Bakos, G. A. 2016, Astronomy and Computing, 17, 1

and the relevant sources for the algorithms you use.


3. Installation — quick start (Linux)
-------------------------------------

From the source directory::

    ./configure --prefix=$HOME/.local
    make
    make install

Then, to install the Python wrapper::

    cd python
    pip install -e .

This assumes the prerequisites for your platform are installed.  See the
platform-specific companion files for details:

    README.linux     Debian/Ubuntu, Fedora/RHEL, Arch
    README.mac       macOS (Homebrew)
    README.windows   Windows (WSL recommended; MSYS2 alternative)


4. Dependencies
---------------

A working C compiler, ``make``, ``libtool``, and a Fortran compiler
(``gfortran``) are required.

All of the following are **optional** — ``configure`` autodetects each one
and disables the corresponding feature if it is not found.

    Library / interpreter     Used for
    -----------------------   -------------------------------------------
    cfitsio                   FITS light-curve I/O
    GSL                       -addnoise, -microlens, -resample, -FFT, -IFFT
    pthread                   Parallel processing (-parallel N)
    CSPICE                    BJD/UTC conversions (-converttime)
    Python + NumPy (embed)    -python command (embedded interpreter)
    R (embed)                 -R command (embedded interpreter)
    dynamic-library support   -L and -F user-command / user-function loading

Standard paths:

    cfitsio:    libcfitsio.so, fitsio.h
    GSL:        libgsl.so, libgslcblas.so, gsl/*.h
    pthread:    libpthread (on Linux / macOS); MSYS2 native on Windows
    CSPICE:     cspice.a, SpiceUsr.h   (no standard package — build from source)
    Python:     libpython3.X.so, Python.h, numpy arrayobject.h
    R:          libR.so, Rinternals.h, Rembedded.h, R_ext/Parse.h
    libltdl:    used for dynamic library loading; configure/libtool handle it

The ``configure`` script takes a number of ``--with-*`` flags to point at
non-standard locations for these — see section 5 below or run
``./configure --help`` for the full list.


4.1 CSPICE — additional setup
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

CSPICE needs ancillary SPICE kernel files at runtime.  Download the
latest versions of each from the NAIF site and store them in
``${HOME}/.vartools/`` (the default location VARTOOLS looks in)::

    https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/planets/  (e.g. de432s.bsp)
    https://naif.jpl.nasa.gov/pub/naif/generic_kernels/lsk/           (e.g. naif0012.tls)
    https://naif.jpl.nasa.gov/pub/naif/generic_kernels/pck/           (e.g. pck00010.tpc)

New versions of each are released periodically; check for updates, especially
the leap-second file (``naif*.tls``) after any announced leap-second event.

Optionally, set environment variables to point at specific kernel files::

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

These paths can also be passed on the ``vartools`` command line.


5. Configuring and building
---------------------------

Unpack the source tarball and ``cd`` into it::

    wget http://www.astro.princeton.edu/~jhartman/vartools/vartools-1.6.tar.gz
    tar xzf vartools-1.6.tar.gz
    cd vartools-1.6

5.1 Install paths
~~~~~~~~~~~~~~~~~

By default, installation uses ``$(PREFIX)/bin``, ``$(PREFIX)/lib``, and
``$(PREFIX)/share``, with ``PREFIX=/usr/local``.  Override with::

    --prefix=$HOME/.local      # install into home dir (no sudo needed)
    --bindir=$HOME/bin         # just the binary directory
    --libdir=...
    --datarootdir=...

    vartools binary           → $(BINDIR)
    libvartoolspipeline.so    → $(LIBDIR)
    Documentation             → $(DATAROOTDIR)/doc/vartools
    User-compiled commands    → $(DATAROOTDIR)/vartools/USERLIBS
    User-compiled functions   → $(DATAROOTDIR)/vartools/USERFUNCS
    Example light curves      → $(DATAROOTDIR)/vartools/EXAMPLES

5.2 Pointing at non-standard library locations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Most optional dependencies follow one of two patterns:

* **A package manager installed them to a standard prefix** (``/usr``,
  ``/usr/local``, Homebrew's ``$(brew --prefix)``): ``configure`` finds
  them automatically, or needs only a ``CPPFLAGS="-I..."`` /
  ``LDFLAGS="-L..."`` hint.

* **You built from source to a custom prefix** (e.g.  CFITSIO in
  ``$HOME/src/cfitsio``): use the ``--with-*`` flag for that dependency.

Available ``--with-*`` flags::

    --with-cfitsio=PATH            prefix containing fitsio.h + libcfitsio.a
    --with-cfitsio-include=PATH    header-only override
    --with-cfitsio-lib=PATH        library-only override (full path to .a)

    --with-gsl | --with-gsl=no     enable / disable GSL support

    --with-cspice=PATH             prefix (expects PATH/include and PATH/lib/cspice.a)
    --with-cspice-include=PATH
    --with-cspice-lib=PATH         full path to cspice.a

    --with-RHOME=PATH              R installation prefix (RHOME from "R RHOME")
    --with-R-include=PATH
    --with-R-lib=PATH              directory containing libR.so

    --with-pythonconfig=PATH       path to python-config (typically autodetected)
    --with-pythonhome=PATH         hard-code PYTHONHOME at build time
    --with-pythonpath=PATH         hard-code PYTHONPATH at build time

Fortran compiler selection (some extensions are compiled in Fortran; the
system default ``F77`` / ``FC`` is often insufficient)::

    FC=gfortran F77=gfortran

5.3 Example invocation
~~~~~~~~~~~~~~~~~~~~~~

Install to home directory, with CSPICE built locally, R support, and
gfortran as the Fortran compiler::

    ./configure \
        --prefix=$HOME/.local \
        --with-cspice=$HOME/src/cspice \
        --with-RHOME=$(R RHOME) \
        CPPFLAGS="-I$HOME/src/cfitsio" \
        LDFLAGS="-L$HOME/src/cfitsio" \
        FC=gfortran F77=gfortran

5.4 Rebuilding the build system
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The source distribution ships with a pre-generated ``configure`` script
and ``Makefile.in`` files, so autoconf/automake are not required on the
build machine for a normal build.  If ``./configure`` fails with errors
about m4 macros or missing helper scripts, re-generate with::

    ./autogen.sh

This runs ``autoreconf --install --force``.  It requires ``autoconf``,
``automake``, and ``libtool`` to be installed.  See the platform READMEs
for how to install them on your system.


6. Compiling and installing
---------------------------

::

    make
    make install

``make`` produces a working binary at ``src/vartools``, but running it
from there will usually fail due to missing shared-library paths.  Use
the installed binary at ``$(BINDIR)/vartools`` instead.

If the install prefix is outside your home directory (e.g. the default
``/usr/local``), ``make install`` requires root::

    sudo make install


7. Testing
----------

Run a quick sanity check from the source directory (``$(BINDIR)`` should
be on your ``PATH``)::

    vartools -help
    vartools -listcommands
    vartools -example -LS

A more detailed test::

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

should produce output beginning with::

    Name                     = EXAMPLES/2
    LS_Period_1_0            =     1.23440877
    Log10_LS_Prob_1_0        = -4000.59209
    ...

See the website and ``EXAMPLES/`` directory for additional tests.


8. pyvartools — Python wrapper
------------------------------

The ``python/`` subdirectory contains ``pyvartools``, a Python package
that provides a Pythonic API over the ``vartools`` binary.  After
``make install`` succeeds::

    cd python
    pip install -e .

pyvartools offers:

* A fluent / chaining API — ``lc.LS(...).rms().expr(...)``.
* Input types covering NumPy arrays, pandas DataFrames, astropy
  ``TimeSeries``, and ``LightCurve`` wrappers.
* Result objects (``Result``, ``BatchResult``) with structured access to
  vartools' output statistics, periodograms, and processed light curves.

8.1 In-process library mode
~~~~~~~~~~~~~~~~~~~~~~~~~~~

``make install`` also installs a shared library, ``libvartoolspipeline.so``
(``.dylib`` on macOS), alongside the binary.  pyvartools uses this library
to run vartools **in-process** by default, avoiding the subprocess
spawn overhead (~20× speedup in typical usage).  The subprocess path is
used automatically as a fallback whenever library mode is unavailable,
so no user-level configuration is required.

Override the library location if ``pyvartools`` can't find it::

    import pyvartools as vt
    vt.set_library("/path/to/libvartoolspipeline.so")

or set the environment variable ``VARTOOLS_LIBRARY``.

8.2 Further reading
~~~~~~~~~~~~~~~~~~~

See ``python/README.md`` for a pyvartools quick start, and the website's
*Python API* section for the full reference.


9. Creating VARTOOLS extensions
-------------------------------

Users can add new commands and analytic functions to VARTOOLS by compiling
them as dynamic libraries that are loaded at runtime.  See:

* ``USERLIBS/ReadME.USERLIBS`` — defining new commands.
* ``USERFUNCS/ReadME.USERFUNCS`` — defining new analytic functions.


10. Disclaimer
--------------

This program is distributed without any warranty.  Use it at your own risk.


11. Bugs / feedback
-------------------

Please send bug reports, feature requests, or other feedback to
Joel Hartman (jhartman AT astro DOT princeton DOT edu) or open an issue
at https://github.com/joeldhartman/vartools/issues.
