S2FIL package documentation

Jason McEwen

The S2FIL library contains functionality to support optimal filtering on the sphere. Optimal directional matched filters (MF) and scale adaptive filters (SAF) may be constructed from a template and stochastic background process. Functionality is incorporated also to filter a sky data map using an optimal filter and to detect compact objects using a naive thresholding strategy. The derivation of the optimal filters on the sphere implemented here is presented in our paper:

J. D. McEwen, M. P. Hobson, and A. N. Lasenby. Optimal filters on the sphere. IEEE Trans. Sig. Proc., in press, 2006.

The library design is based on object-oriented principles and is implemented in Fortran 90. Generally one must instantiate a class object using the corresponding init routines. The instatiated object should be freed once it is no longer required with the corresponding free routine (this deallocates all memory associated with the object).

For further details see the README.txt file.


Installation

The S2FIL package requires the FastCSWT, COMB, S2, HEALPix, CFITSIO and FFTW 2.1.5 packages. Please note that all S2FIL code is written in Fortran 90 and a suitable Fortran compiler will be required.

Compiling library

Before compiling you may need to edit the makefile to specify your compiler and to link with the appropriate libraries. Once you have set the makefile up for your system then the S2FIL library may be compilied by running:
>> make lib

For details on how to use the S2FIL library code see the documentation below.

Compiling utility programs

The S2FIL utility programs may be compiled by running:

>> make prog
For details on how to use the S2FIL utility programs see the documentation
below.

Testing

Typical input and output files for S2FIL are available for download here. Untar the data archive and place the data_in and test_field, test_filter and test_localise directories within the base s2fil-1.0 directory. To test the S2FIL installation a number of scripts are provided. Firstly, run

>> ./construct_and_plot_mf_bfly.sh
and
>> ./construct_and_plot_saf_bfly.sh
to compute the MF and SAF of the butterfly template respectively. Filter files are written to the data_filter directory and should match those files in the test_filter directory. Next run
>> ./field_construct_mf_bfly.sh
to perform filtering with the MF (fast filtering is performed using the FastCSWT library). Filtered field files are written to the data_field directory and should match those files in the test_field directory. Finally, run
>> ./localise_mf_bfly.sh
to perform a naive thresholding strategy to detect embedded objects from the filtered field. Related files are written to the data_localise directory and should match those files in the test_localise directory. The map contained in the data_localise/bfly_obj_loc.fits file shows the recovered objects and may be compared to the actual embedded objects shown in the map contained in the data_in/bfly_obj.fits file.

Documentation

By default, the S2FIL code ships with only this single documentation page. The remainder of the documentation is automatically generated from the source code using f90doc. Please ensure that you have f90doc installed in order to generate this documentation. Once f90doc is installed the documentation may be generated by running:

>> make docs

Cleaning up

To clean up your version of the S2FIL code and return all code to its original state run:
>> make clean
To remove all documentation, except the front page (i.e. this file), run:
>> make cleandocs

Library classes

An overview of the classes that comprise the S2FIL library is given here. Please click on the link for each class for detailed documentation.

s2fil_field_mod: Functionality to compute and store the coefficients of a filtered field from the optimal filter and data sky map. Interfaces with the CSWT library to actually compute the `wavelet' coefficients.

s2fil_filter_mod: Functionality to compute (and store) optimal filters from a background noise process and template function defined on the sky. Both spherical directional matched filters and scale adaptive filters may be constructed. Filters at various scales may be constrcuted either by dilating the original template (`correct' approach) or by dilating the first computed optimal filter.

s2fil_types_mod: Definition of intrinsic types and constants used in the s2fil library.

s2fil_error_mod: Functionality to handle errors that may occur in the S2FIL library. Public S2FIL error codes are defined, with corresponding private error comments and default halt execution status.


Utility programs

Utility programs based on the S2FIL library are listed here. More S2FIL programs may appear here in the future as their need becomes apparent. Please click on the link for each program for detailed documentation.

s2fil_filter_construct: Compute optimal filter from template and background process.

s2fil_field_construct: Construct filtered field from optimal filter and data sky.

s2fil_localisation_thres: Find localised regions in filtered field using thresholding strategy. Locations and values found are written to the standard output.

s2fil_draw_dots: Draw dots on sky map at specified positions.

s2fil_draw_dots_only: Draw dots at specified positions on constant value map.


Support

For support or to report any bugs please contact Jason McEwen (mcewen@mrao.cam.ac.uk).

Reference

If you use the code to produce published works please reference the download site http://github.com/astro-informatics/s2fil and our related paper:
J. D. McEwen, M. P. Hobson, and A. N. Lasenby. Optimal filters on the sphere. IEEE Trans. Sig. Proc., 56(8), 3813-3823, 2008.
J. D. McEwen, S. M. Feeney, M. C. Johnson, and H. V. Peiris. Optimal filters for detecting cosmic bubble collisions. Phys. Rev. D., 85(10):103502, 2012.

Version

Author: J. D. McEwen

Version: 1.1

Version History


License

S2fil package to provide functionality for optimal filtering on the sphere
Copyright (C) 2005 Jason McEwen

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 (LICENSE.txt).

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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.


Acknowledgements

JDM would like to thank Mike Hobson for very useful discussions on optimal filter theory on the sphere.

This documentation has been generated largely by f90doc, with some minor modifications.


Last modified: 1 July 2008