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.
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.
>> make lib
For details on how to use the S2FIL library code see the documentation
below.
The S2FIL utility programs may be compiled by running:
Typical input and output files for S2FIL are available for
download here.
Untar the data archive and place the Compiling utility programs
For details on how to use the S2FIL utility programs see the documentation
below.
>> make prog
Testing
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
and
>> ./construct_and_plot_mf_bfly.sh
to compute the MF and SAF of the butterfly template respectively.
Filter files are written to the >> ./construct_and_plot_saf_bfly.sh
data_filter directory and
should match those files in the test_filter
directory.
Next run
to perform filtering with the MF (fast filtering is performed using
the FastCSWT library).
Filtered field files are written to the >> ./field_construct_mf_bfly.sh
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.
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
>> make clean
To remove all documentation, except the front page (i.e. this file),
run:
>> make cleandocs
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.
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.
mcewen@mrao.cam.ac.uk).
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.
Author: J. D. McEwen
Version: 1.1
S2fil package to provide functionality for optimal filtering on the sphere
Copyright (C) 2005 Jason McEwenThis 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.
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