pysca 0.1.2

A tool for automated frequency extraction from photometric time series of heat-driven pulsators.

Pysca is a software package that allows automated extraction of frequencies, amplitudes and phases from non-equally sampled time series of heat-driven pulsators. The extraction is carried out by identifying the highest peaks in the Lomb-Scargle periodogram and fitting the time series with a superposition of harmonic functions of the corresponding frequencies. This is implemented using an iterative algorithm where the time series is progressively prewhitened up to an user defined termination condition. The signal-to-noise ratio is calculated for every frequency as a statistical measure of significance.

Requirements

Pysca runs with Python version 2.6 and 2.7; there is currently no support for Python 3. It depends on the following Python packages:

• NumPy, version 1.4.1 or newer

• SciPy, version 0.7.2 or newer

• PyFITS, version 2.3.1 or newer

If you use the pip package manager (see below), these packages will be (if neccessary) automatically downloaded and installed. Note however that pip will install these packages from source and that the build process might take quite some time (especially for the rather large SciPy package). So it might be a good idea to install a pre-compiled version of these packages (e.g. by using the package manager of your Linux distribution) before you install Pysca.

Installation

The prefered way to install Pysca is to use the pip:

pip install --user pysca

This way Pysca will be installed completely into the user’s home directory. The pysca executable will be installed to:

    $HOME/.local/bin/pysca                       (Linux, MacOS w/ Python 2.6)
or  $HOME/Library/Python/X.Y/bin/pysca                  (MacOS w/ Python 2.7)

where X.Y is the Python version (i.e. 2.7) and the pysca library will be installed under:

    $HOME/.local/lib/pythonX.Y/site-packages     (Linux, MacOS w/ Python 2.6)
or  $HOME/Library/Python/X.Y/lib/python/site-packages   (MacOS w/ Python 2.7)

Another advantage of pip is, that you can easily upgrade Pysca to the latest version, by entering:

pip install --user -U --no-deps pysca

or completely uninstall Pysca using the following command:

pip uninstall pysca

To run the pysca executable, you have to make sure, that it is in your PATH, by either adding the directory, where the executable was installed, to your PATH environment variable, e.g. using the Bash:

export PATH=$HOME/.local/bin/pysca:$PATH

or by creating a symlink of the binary to a directory which is already included in your PATH environment variable, e.g.:

ln -s $HOME/.local/bin/pysca $HOME/bin/

If you, for any reason, don’t want to use pip or any other Python installer (like easy_install), you can also download the .tar.gz file, extract it to some directory and then source the provided env_pysca.sh script:

tar -xzf pysca-x.y.z.tar.gz
source pysca-x.y.z/env_pysca.sh

Note however, that this script only works with the Bash; if you are using the C shell or anyting else, you can still use Pysca without using pip, but you have to set the PYTHONPATH and PATH environment variables by your self.

How to use

To use Pysca, you need an input file containing the (detrended) time series, either in FITS or in ASCII format. The file must have two columns, with the time steps in the first one and the amplitudes in the second one. Note that the physical unit of the time column determines the unit of the resulting frequencies. If the time column contains fractional days (e.g. JD or MJD), then the frequency unit is c/d (cycles per day). If, on the other hand, the time column contains values in seconds, then all frequencies are in Hz.

The pysca command

If Pysca was installed correctly, you can start it with the pysca command. An overview of all command-line options is available using the pysca --help command. In order to extract mode parameters from the time series, it is required that you specify a frequency range, which restricts the part of the spectrum where mode parameters should be extracted from (option -f). In addition you need to use the -b option to specify the width around each peak that is used to estimate the SNR; you can disable the SNR computation by explicitely setting it to 0. Finally you have to specify the output file name using the -o option.

The following gives a minimal example on how to use the pysca command:

pysca timeseries.fits -o out.dat -f 0.5 20 -b 3 -n 5

This reads the time series from a file called timeseries.fits, extracts the mode parameters of the 5 highest peaks from the frequency range between 0.5 and 20 c/d in the periodogram (assuming the time column of the time series contains MJD values), uses a width of 3 c/d around each peak to estimated the noise level and finally writes the result to an ASCII file called out.dat.

The python interface

As an alternative to the pysca command, you can also use the Python interface of Pysca. The following Python example does essentially the same as the example above:

from pysca import Pysca
from pysca.io import read_timeseries, write_params

t, a = read_timeseries('timeseries.fits')

p = Pysca(t, a, 0.5, 20, 3, verbose=1)
p.run(5)

write_params('out.dat', p.result, fmt='ascii', clobber=True)

Important note: Pysca is still in an early development state, so it is most likely that some of the command-line options, aswell as parts of the Python API will change in the future.