Module s2fil_field_mod

module s2fil_field_mod

        ! Uses
    use s2_types_mod
    use s2_sky_mod
    use s2fil_error_mod
    use s2fil_types_mod
    use s2fil_filter_mod
    use cswt_tr_mod
    use cswt_swav_mod

        ! Types
    public type s2fil_field

        ! Interfaces
    public interface s2fil_field_init

        ! Subroutines and functions
    private function s2fil_field_init_data (filename_filter, filename_sky, sky_file_type, n_gamma) result (field)
    private function s2fil_field_init_file (filename, filename_filter) result (field)
    private function s2fil_field_init_copy (orig) result (copy)
    public subroutine s2fil_field_free (field)
    public subroutine s2fil_field_compute (field)
    private subroutine s2fil_field_ckset_size (field)
    public subroutine s2fil_field_loc_thres (field, nsigma, n_regions, max_val, max_loc, max_siz, filename_thres, filename_connected)
    public subroutine s2fil_field_io_fits_write (filename, field, write_filter, comment)
    private subroutine s2fil_field_io_fits_read (filename, field, filename_filter_in)
    private subroutine s2fil_field_io_fits_error_check (status, halt)
    private subroutine s2fil_field_io_fits_exists (filename, status, exists)
    private subroutine s2fil_field_io_fits_del (filename, status)
    public subroutine s2fil_field_io_txt_dots_write (filename, alpha, beta)
    public subroutine s2fil_field_io_txt_dots_read (filename, alpha, beta)
    public function s2fil_field_get_init (field) result (init)
    public function s2fil_field_get_n_gamma (field) result (n_gamma)
    public function s2fil_field_get_computed_status (field) result (computed_status)
    public function s2fil_field_get_n_alpha (field) result (n_alpha)
    public function s2fil_field_get_n_beta (field) result (n_beta)
    public function s2fil_field_get_lmax (field) result (lmax)
    public function s2fil_field_get_mmax (field) result (mmax)
    public function s2fil_field_get_n_scale (field) result (n_scale)
    public function s2fil_field_get_nside (field) result (nside)
    public subroutine s2fil_field_get_scale_val (field, iscale, one_scale)

end module 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.

Notes:

Note dilation values stored in tr structures are all unitary, since filters already dilated to appropriate size. To find actual corresponding dilation look in filter%scale array.

Author: J. D. McEwen (mcewen@mrao.cam.ac.uk)

Version: 0.1 April 2005

Description of Types

s2fil_field

public type s2fil_field
    private
    logical :: init = .false.
    integer :: n_gamma = 0
    type (s2fil_filter) :: filter
    type (s2_sky) :: sky
    type (cswt_tr), allocatable, dimension (:) :: tr
    logical :: computed_status = .false.
end type s2fil_field

Description of Interfaces

s2fil_field_init

public interface s2fil_field_init
    module procedure s2fil_field_init_data
    module procedure s2fil_field_init_file
    module procedure s2fil_field_init_copy
end interface s2fil_field_init

Description of Subroutines and Functions

s2fil_field_init_data

private function s2fil_field_init_data (filename_filter, filename_sky, sky_file_type, n_gamma) result (field)
    character (len=*), intent(in) :: filename_filter
    character (len=*), intent(in) :: filename_sky
    integer, intent(in) :: sky_file_type
    integer, intent(in) :: n_gamma
    type (s2fil_field) :: field
    ! Calls: cswt_swav_free, s2_sky_free, s2fil_error, s2fil_field_ckset_size
end function s2fil_field_init_data

Initialise an uncomputed s2fil filtered field from data contained in files. Note that space for the filtered field coefficient tr structures is allocated here but the tr structures themselves are not computed yet.

Variables:

filename_filter: Name of full s2fil_filter fits file containing all optimal filter data (including filenames of associated filter sky, template and background files).
filename_sky: Name of data sky file (either fits map file or fits full s2_sky file as defined by sky_file_type).
sky_file_type: Type of data sky file read (options specified in s2_sky_mod as either S2_SKY_FILE_TYPE_MAP or S2_SKY_FILE_TYPE_SKY).
n_gamma: N_gamma (number of orientations) considered for the filtered field map.

Author: J. D. McEwen

Version: 0.1 April 2005

s2fil_field_init_file

private function s2fil_field_init_file (filename, filename_filter) result (field)
    character (len=*), intent(in) :: filename
    character (len=*), optional, intent(in) :: filename_filter
    type (s2fil_field) :: field
    ! Calls: s2fil_error, s2fil_field_io_fits_read
end function s2fil_field_init_file

Initialise a field structure from a field fits file. Wrapper for routine s2fil_field_io_fits_read.

Notes:

Much of the field data is not stored directly in the s2fil field fits file but rather in associated child files, the filenames of which are stored in the field file header.

Variables:

filename: The fits file to read the field from.
field: Filtered field constructed with the data read from the file.

Author: J. D. McEwen

Version: 0.1 April 2005

s2fil_field_init_copy

private function s2fil_field_init_copy (orig) result (copy)
    type (s2fil_field), intent(in) :: orig
    type (s2fil_field) :: copy
    ! Calls: s2fil_error
end function s2fil_field_init_copy

Initialse a field structure as a copy of another field.

Variables:

orig: The original field to copy.
copy: The initialised field copied from the original.

Author: J. D. McEwen

Version: 0.1 April 2005

s2fil_field_free

public subroutine s2fil_field_free (field)
    type (s2fil_field), intent(inout) :: field
    ! Calls: cswt_tr_free, s2_sky_free, s2fil_error, s2fil_filter_free
end subroutine s2fil_field_free

Free all data associated with an initialised field and reset all other attributes.

Variables:

field: The s2fil field object to be freed.

Author: J. D. McEwen

Version: 0.1 April 2005

s2fil_field_compute

public subroutine s2fil_field_compute (field)
    type (s2fil_field), intent(inout) :: field
    ! Calls: cswt_tr_analysis, s2_sky_compute_alm, s2fil_error
end subroutine s2fil_field_compute

Compute filter field wavelet coefficient tr structures.

Notes:

Sky alms are computed before calling cswt_tr_analysis, so that they need only be computed once for all scales.
Object must already be initialised with space for tr structures allocated for all scales.

Variables:

field: Field to compute tr structures for.

Author: J. D. McEwen

Version: 0.1 April 2005

s2fil_field_ckset_size

private subroutine s2fil_field_ckset_size (field)
    type (s2fil_field), intent(inout) :: field
    ! Calls: s2_sky_set_lmax, s2_sky_set_nside, s2fil_error
end subroutine s2fil_field_ckset_size

Check and set field sizes. Ensure filter and sky sizes are consistent. If sky sizes are not defined (as most likely for lmax and mmax if just read from map file) then set to sizes defined by filter structure.

Variables:

field: Field to check filter and sky sizes and set if necessary.

Author: J. D. McEwen

Version: 0.1 April 2005

s2fil_field_loc_thres

public subroutine s2fil_field_loc_thres (field, nsigma, n_regions, max_val, max_loc, max_siz, filename_thres, filename_connected)
    type (s2fil_field), intent(in) :: field
    real (kind=s2_sp), intent(in) :: nsigma
    integer, allocatable, intent(out), dimension (:) :: n_regions
    real (kind=s2_sp), allocatable, intent(out), dimension (:,:) :: max_val
    integer, allocatable, intent(out), dimension (:,:,:) :: max_loc
    integer, allocatable, intent(out), dimension (:,:) :: max_siz
    character (len=*), optional, intent(in) :: filename_thres
    character (len=*), optional, intent(in) :: filename_connected
    ! Calls: cswt_tr_free, cswt_tr_io_fits_write_wcoeff, cswt_tr_localmax_ab, cswt_tr_wcoeff_thres_nsigma, s2fil_error
end subroutine s2fil_field_loc_thres

Find localised regions in filtered field using thresholding strategy.

Notes:

*Currently only set up to consider only one dilation and orientation.*
Data arrays of maximum local values and locations are allocated herein, since no prior knowledge of number of objects contained in map. These arrays must be freed by the calling routine.
Sigma computed across all scales and orientations.

Variables:

field: Field containing filtered coefficients to detect local maxima in.
nsigma: Number of sigma level to perform thresholding at.
max_val: List of local maximum values found.
max_loc: List of locations of local maximum values found.
[filename_thres]: If present save cswt file of thresholded coefficients.
[filename_connected]: If present save cswt file of connected components.

Author: J. D. McEwen

Version: 0.1 April 2005

s2fil_field_io_fits_write

public subroutine s2fil_field_io_fits_write (filename, field, write_filter, comment)
    character (len=*), intent(in) :: filename
    type (s2fil_field), intent(in) :: field
    logical, optional, intent(in) :: write_filter
    character (len=*), optional, intent(in) :: comment
    ! Calls: cswt_tr_io_fits_write_wcoeff, ftclos, ftfiou, ftgiou, ftibin, ftinit, ftpcle, ftpcom, ftpdat, ftphpr, ftpkyj, ftpkyl, ftpkys, s2_sky_io_fits_write, s2fil_error, s2fil_field_io_fits_error_check, s2fil_field_io_fits_exists, s2fil_filter_get_scale, s2fil_filter_io_fits_write
end subroutine s2fil_field_io_fits_write

Write filtered field structure to a fits file.

Notes:

The field file only contains a header and no data directly (except scales). All other data is stored in associated child files, the filenames of which are stored in the filtered field file header.
An option is given for saving the filter file since this will most likely already have been read from an input file and so, to avoid duplication, another output need not be written.
The sky data file is written (and may be duplicated), however, since this will have alms computed and will be saved in the full s2_sky fits format.

Variables:

filename: Name of fits file to write to.
field: The filtered field structure containing all data to be written to fits file.
[comment]: Comment to append to header of output fits file.

Author: J. D. McEwen

Version: 0.1 April 2005

s2fil_field_io_fits_read

private subroutine s2fil_field_io_fits_read (filename, field, filename_filter_in)
    character (len=*), intent(in) :: filename
    type (s2fil_field), intent(out) :: field
    character (len=*), optional, intent(in) :: filename_filter_in
    ! Calls: ftclos, ftfiou, ftgcve, ftgiou, ftgkyj, ftgkyl, ftgkys, ftmahd, ftopen, ftthdu, s2fil_error, s2fil_field_io_fits_error_check, s2fil_field_io_fits_exists, s2fil_filter_get_scale
end subroutine s2fil_field_io_fits_read

Read a s2fil_field fits file and all associated child files (i.e. data sky, tr structure coefficients and filter files.)

Notes:

Child files (as described in the filter file header) must be located in the same directory.

Variables:

filename: Name of primary s2fil_filter fits file.
filter: Returned filter structure initialised with the data contained in the filter fits file and the associated child files.

Author: J. D. McEwen

Version: 0.1 - April 2005

s2fil_field_io_fits_error_check

private subroutine s2fil_field_io_fits_error_check (status, halt)
    integer, intent(inout) :: status
    logical, intent(in) :: halt
    ! Calls: ftgerr, ftgmsg
end subroutine s2fil_field_io_fits_error_check

Check if a fits error has occured and print error message. Halt program execution if halt flag is set.

Notes:

Copied form cswt_tr_mod module.

Variables:

status: Fits integer status code.
halt: Logical to indicate whether to halt program execution if an error is detected.

Author: J. D. McEwen

Version: 0.1 - November 2004

s2fil_field_io_fits_exists

private subroutine s2fil_field_io_fits_exists (filename, status, exists)
    character (len=*), intent(in) :: filename
    integer, intent(inout) :: status
    logical, intent(out) :: exists
    ! Calls: ftclos, ftfiou, ftgiou, ftopen, s2fil_field_io_fits_error_check
end subroutine s2fil_field_io_fits_exists

Check if a fits file exists.

Notes:

Copied form cswt_tr_mod module.

Variables:

filename: Name of fits file to check existence of.
status: Fits integer status code.
exists: Logical indicating whether the fits file already exists.

Author: J. D. McEwen

Version: 0.1 - November 2004

s2fil_field_io_fits_del

private subroutine s2fil_field_io_fits_del (filename, status)
    character (len=*), intent(in) :: filename
    integer, intent(inout) :: status
    ! Calls: ftcmsg, ftdelt, ftfiou, ftgiou, ftopen
end subroutine s2fil_field_io_fits_del

Delete a fits file.

Notes:

Copied form cswt_tr_mod module.

Variables:

filename: Name of fits file to detele.
status: Fits integer status code.

Author: J. D. McEwen

Version: 0.1 - November 2004

s2fil_field_io_txt_dots_write

public subroutine s2fil_field_io_txt_dots_write (filename, alpha, beta)
    character (len=S2_STRING_LEN), intent(in) :: filename
    real (kind=s2_sp), intent(in), dimension (:) :: alpha
    real (kind=s2_sp), intent(in), dimension (:) :: beta
    ! Calls: s2fil_error
end subroutine s2fil_field_io_txt_dots_write

Write source positions to an output dot text file.

Variables:

filename: Name of text file to write source positions to.
alpha: Alpha (phi) spherical coordinate array of source positions to write.
beta: Beta (theta) spherical coordinate array of source positions to write.

Author: J. D. McEwen

Version: 0.1 - May 2005

s2fil_field_io_txt_dots_read

public subroutine s2fil_field_io_txt_dots_read (filename, alpha, beta)
    character (len=S2_STRING_LEN), intent(in) :: filename
    real (kind=s2_sp), intent(out), allocatable, dimension (:) :: alpha
    real (kind=s2_sp), intent(out), allocatable, dimension (:) :: beta
    ! Calls: s2fil_error
end subroutine s2fil_field_io_txt_dots_read

Read source positions from an input dot text file.

Notes:

Alpha and beta arrays are allocated herein and must be freed by the calling routine.

Variables:

filename: Name of text file to read source positions from.
alpha: Alpha (phi) spherical coordinate array of source positions read.
beta: Beta (theta) spherical coordinate array of source positions read.

Author: J. D. McEwen

Version: 0.1 - May 2005

s2fil_field_get_init

public function s2fil_field_get_init (field) result (init)
    type (s2fil_field), intent(in) :: field
    logical :: init
end function s2fil_field_get_init

Get init variable from the passed field.

Variables:

field: Field object to get the variable of.
init: Object init variable returned.

Author: J. D. McEwen

Version: 0.1 April 2005

s2fil_field_get_n_gamma

public function s2fil_field_get_n_gamma (field) result (n_gamma)
    type (s2fil_field), intent(in) :: field
    integer :: n_gamma
    ! Calls: s2fil_error
end function s2fil_field_get_n_gamma

Get n_gamma variable from the passed field.

Variables:

field: Field object to get the variable of.
n_gamma: Object n_gamma variable returned.

Author: J. D. McEwen

Version: 0.1 April 2005

s2fil_field_get_computed_status

public function s2fil_field_get_computed_status (field) result (computed_status)
    type (s2fil_field), intent(in) :: field
    logical :: computed_status
    ! Calls: s2fil_error
end function s2fil_field_get_computed_status

Get computed_status variable from the passed field.

Variables:

field: Field object to get the variable of.
computed_status: Object computed_status variable returned.

Author: J. D. McEwen

Version: 0.1 April 2005

s2fil_field_get_n_alpha

public function s2fil_field_get_n_alpha (field) result (n_alpha)
    type (s2fil_field), intent(in) :: field
    integer :: n_alpha
    ! Calls: s2fil_error
end function s2fil_field_get_n_alpha

Get n_alpha variable from the passed field. Note n_alpha stored in tr structure.

Variables:

field: Field object to get the n_alpha of.
n_alpha: N_alpha variable returned.

Author: J. D. McEwen

Version: 0.1 April 2005

s2fil_field_get_n_beta

public function s2fil_field_get_n_beta (field) result (n_beta)
    type (s2fil_field), intent(in) :: field
    integer :: n_beta
    ! Calls: s2fil_error
end function s2fil_field_get_n_beta

Get n_beta variable from the passed field. Note n_beta stored in tr structure.

Variables:

field: Field object to get the n_beta of.
n_beta: N_beta variable returned.

Author: J. D. McEwen

Version: 0.1 April 2005

s2fil_field_get_lmax

public function s2fil_field_get_lmax (field) result (lmax)
    type (s2fil_field), intent(in) :: field
    integer :: lmax
    ! Calls: s2fil_error
end function s2fil_field_get_lmax

Get lmax variable from the passed field. Note lmax stored in filter object.

Variables:

field: Field object to get the lmax of.
lmax: Lmax variable returned.

Author: J. D. McEwen

Version: 0.1 April 2005

s2fil_field_get_mmax

public function s2fil_field_get_mmax (field) result (mmax)
    type (s2fil_field), intent(in) :: field
    integer :: mmax
    ! Calls: s2fil_error
end function s2fil_field_get_mmax

Get mmax variable from the passed field. Note mmax stored in filter object.

Variables:

field: Field object to get the mmax of.
mmax: Mmax variable returned.

Author: J. D. McEwen

Version: 0.1 April 2005

s2fil_field_get_n_scale

public function s2fil_field_get_n_scale (field) result (n_scale)
    type (s2fil_field), intent(in) :: field
    integer :: n_scale
    ! Calls: s2fil_error
end function s2fil_field_get_n_scale

Get n_scale variable from the passed field. Note nside stored in filter object.

Variables:

field: Field object to get the n_scale of.
n_scale: N_scale variable returned.

Author: J. D. McEwen

Version: 0.1 April 2005

s2fil_field_get_nside

public function s2fil_field_get_nside (field) result (nside)
    type (s2fil_field), intent(in) :: field
    integer :: nside
    ! Calls: s2fil_error
end function s2fil_field_get_nside

Get nside variable from the passed field. Note nside stored in filter object (where it is in turn stored in the tmpl sky)

Variables:

field: Field object to get the nside of.
nside: Nside variable returned.

Author: J. D. McEwen

Version: 0.1 April 2005

s2fil_field_get_scale_val

public subroutine s2fil_field_get_scale_val (field, iscale, one_scale)
    type (s2fil_field), intent(in) :: field
    integer, intent(in) :: iscale
    real (kind=s2_sp), intent(out), dimension (:) :: one_scale
    ! Calls: s2fil_error, s2fil_filter_get_scale
end subroutine s2fil_field_get_scale_val

Get value from filter scale array corresponding to the index iscale. Note value copied is 2D array (since 2D dilation/scale).

Notes:

Space for one_scale must be allocated and deallocated by calling routine.

Variables:

field: Field containing filter objects to get the variable of.
iscale: Index of scale to get.
one_scale: The single scale (2D for 2D dilation) returned corresponding to the specified scale.

Author: J. D. McEwen

Version: 0.1 April 2006