span - Spectral Analysis

Purpose

Span is a Python-driven toolkit for spectral analysis. Data can be loaded from and saved to ASCII files. Span supports the generation of synthetic data by an autoregressive model. Spectral estimation is based on covariance estimates. Alternatively, parametric estimation with maximum likelihood parameters is available. For visualization and printing, span uses the Python version of Gnuplot.

Structure

The span package consists of a Python class, implemented in spanVar.py and a shared object library. The Python class contains a constructor to create span variables. These provide access to the methods for spectral estimation. The methods of this class use Fortran routines, which are compiled into the shared object library.

Requirements

To build the shared object library you need a C and a FORTRAN compiler. gcc with g77 is fine. Other combinations have not been tested yet.

Span uses the NumPtr package to interface between Numeric arrays and the Fortran library. NumPtr is distributed with span and will be built and installed automatically.

The Python interface to the shared object library has been built with Swig and Swift. However, to install and use span you don't need them. The interfaces are included in the distribution.

Span makes use of the Numeric package and the Gnuplot package. Span works without Gnuplot, but plotting and printing is not available in this case.

Span has been tested on Mac OS X/Darwin with Python 2.2 and Python 2.3 and on Debian Linux with Python 2.2 and Python 2.3.

Installation

Download the latest version of span and unpack it

> gzip -d span-0.7.tar.gz
> tar xf span-0.7.tar

There is no setup.py script yet. Installation needs to be done manually, using a Makefile. To install the span package, go to the ./src directory and type make

> cd span-0.7/src
> make

This should build the shared object library. To install span in the default location and then clean up the ./src directory, type

> make install
> make clean

If you want to install span in your home directory for example, provide the prefix, where the package is to be installed

> make install 'prefix=/home/cdieterich'

If the installation process was successful, span should be ready to use now. To test the span package, type

> make test 'prefix=/home/cdieterich'

which performs testing of the docstrings in the Python files and executes the unit tests in spanUnit.py. Start the Python interpreter, import the span module and type help(span) to get started

> python
>>> import span
>>> help(span)

A html version of the documentation is included in the ./doc directory. These files contain relative paths, which work as long as the directory structure is unchanged. If you like to put the html documentation somewhere else, you can create a new html version of the docstrings, including absolute paths. After span is installed, run

> make doc 'prefix=/home/cdieterich'

to generate html-files of the installed span package.

Demos

To get used to span, there is demo script in the ./lib directory. To run the demo #1, type

> span.py --demo 1

To run all the demos, type

> span.py --demo 0

Documentation

Documentation for the span package is included in the Python files. From the interpreter it is accessed via the help() function

>>> import span
>>> help(span)

or from the command line, using the --help switch

> span.py --help

Browse the detailed html documentation or read the overview of the span package. The overview is reproduced below.

Concept

Span is designed as an easy-to-use toolbox for spectral analysis of one-dimensional time series. The package supports univariate and multivariate time series analysis.

The basic entity of the span package is the span variable. Such a variable is basically a Numeric array which holds the data. Time series, covariance functions, spectral densities, maximum likelihood parameters are all span variables.

Additional data attributes keep track of the methods applied to the span variable. The spectrum, computed from the covariance function of a time series for example, knows that it is a spectrum. It also knows the sampling interval of the time series, the number of lags in the covariance estimate, its degree of freedom and the bandwidth.

Span variables have access to all methods of the class and most methods return span variables. So, it is straightforward to use the result of a previous computation as input to the next one.

To create an initial span variable the constructor of the class accepts a wide variety of input. Span variables containing synthetic or real data can be created from single numbers, tuples, lists, Numeric arrays, span variables and files. Special constructors provide easy means to generate commonly used time series, like white noise, autoregressive processes and data from ASCII files.

Usage

To generate a normally distributed series of white noise and save the data to an ASCII file, use

>>> import span
>>> y = span.normal(100)
>>> y.dump('foo.asc')

To estimate and plot the power spectral density and its confidence limits of data from an ASCII file, use

>>> y = span.spanVar('foo.asc')
>>> cvf = y.ccvf()
>>> psd = cvf.epsd()
>>> [lpsd, upsd] = psd.confidence()
>>> psd.plot(); lpsd.replot(); upsd.replot()

To create an autoregressive process, estimate its maximum likelihood parameters with confidence limits and dump the parameters to an ASCII file, use

>>> y = span.process(100)
>>> par = y.arm()
>>> [lpar, upar] = par.confidence(y)
>>> par.dump('foo.asc')

To estimate and visualize the spectral response functions of a bivariate process and save the plot to a postscript file, use

>>> y = span.normal((100,2))
>>> cvf = y.ccvf()
>>> [copsd, qupsd] = cvf.cpsd()
>>> [cohsq, phase] = copsd.transfer(qupsd)
>>> [gain, resid] = cohsq.response(copsd)
>>> [lgain, ugain] = gain.confidence(cohsq)
>>> gain.plot(num=3); lgain.replot(num=3); ugain.replot(num=3)
>>> gain.hardcopy('foo.ps')

Synopsis

First order statistical moments (mean, variance)

Histogram/statistical tests

Auto- and cross covariance estimators

Auto- and cross correlation estimators

Low- and high-pass filters

Generic finite impulse response filter

Even and odd, one-sided power spectral density estimators (autospectra)

Cross power spectral density estimator (co- and quadrature-spectra)

Estimator for spectral transfer functions (coherency and phase)

Estimator for spectral response functions (gain and residual)

Estimator for maximum likelihood parameters

Estimator for maximum entropy coefficients

Estimator for spectral density using maximum entropy method

Confidence limits for all estimators

Uniformly and normally distributed noise generators

Autoregressive and moving average processes

Input/Output from/to ASCII files

Pickle/Unpickle to/from pickle file

Plot/Print using Gnuplot

To Do

Incorporate dependencies into methods called by the user.

Think of a better solution for the ordering in cross spectral estimates.

Include arma models.

Remodel the demo files.

Extend the unit test file.

Write a setup.py file.

Extend some of the methods to process multivariate time series.

Make span work with other compilers and on other platforms.

Reference

The algorithms used in span are based on

Spectral Analysis and its Applications
Gwilym M. Jenkins and Donald G. Watts
Holden-Day, San Francisco, 1968

Numerical Recipes in FORTRAN
W. H. Press, S. A. Teukolsky, W. T. Vetterling, and B. P. Flannery
Cambridge University Press, 1992, 2nd edition

License

span - Spectral Analysis Toolkit
Copyright (C) 2004, 2005 Christian Dieterich

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA