Module s2fil_filter_mod

module s2fil_filter_mod

        ! Uses
    use s2_types_mod
    use s2_sky_mod
    use s2_pl_mod
    use s2fil_types_mod
    use s2fil_error_mod

        ! Types
    public type s2fil_filter

        ! Variables
    integer, public, parameter :: S2FIL_FILTER_TYPE_MF = 1
    integer, public, parameter :: S2FIL_FILTER_TYPE_SAF = 2
    character (len=*), public, parameter :: S2FIL_FILTER_TYPE_STR_MF = 'mf'
    character (len=*), public, parameter :: S2FIL_FILTER_TYPE_STR_SAF = 'saf'
    integer, public, parameter :: S2FIL_FILTER_SCALE_TYPE_TMPL = 1
    integer, public, parameter :: S2FIL_FILTER_SCALE_TYPE_FILTER = 2
    character (len=*), public, parameter :: S2FIL_FILTER_SCALE_TYPE_STR_TMPL = 'tmpl'
    character (len=*), public, parameter :: S2FIL_FILTER_SCALE_TYPE_STR_FILTER = 'filter'

        ! Interfaces
    public interface s2fil_filter_init
    public interface s2fil_filter_get_scale

        ! Subroutines and functions
    private function s2fil_filter_init_data (tmpl, background, scale, filter_type, scale_type, mmax, norm_pres_dil, beam, heuristic) result (filter)
    private function s2fil_filter_init_copy (orig) result (copy)
    private function s2fil_filter_init_file (filename) result (filter)
    private subroutine s2fil_filter_comp_filter (filter, heu)
    public subroutine s2fil_filter_free (filter)
    public subroutine s2fil_filter_io_fits_write (filename, filter, comment)
    private subroutine s2fil_filter_io_fits_read (filename, filter)
    private subroutine s2fil_filter_io_fits_error_check (status, halt)
    private subroutine s2fil_filter_io_fits_exists (filename, status, exists)
    private subroutine s2fil_filter_io_fits_del (filename, status)
    public subroutine s2fil_filter_write_filter_map (filter, iscale, filename, comment)
    public function s2fil_filter_get_init (filter) result (init)
    public function s2fil_filter_get_lmax (filter) result (lmax)
    public function s2fil_filter_get_mmax (filter) result (mmax)
    public function s2fil_filter_get_nside (filter) result (nside)
    public function s2fil_filter_get_n_scale (filter) result (n_scale)
    public function s2fil_filter_get_norm_pres_dil (filter) result (norm_pres_dil)
    public function s2fil_filter_get_filter_type (filter) result (filter_type)
    public function s2fil_filter_get_scale_type (filter) result (scale_type)
    public function s2fil_filter_get_background (filter) result (background)
    public function s2fil_filter_get_beam (filter) result (beam)
    public function s2fil_filter_get_tmpl (filter) result (tmpl)
    private subroutine s2fil_filter_get_scale_array (filter, scale)
    private subroutine s2fil_filter_get_scale_val (filter, iscale, one_scale)
    public function s2fil_filter_get_sky (filter, iscale) result (sky)
    public function s2fil_filter_get_sky_status (filter) result (sky_status)
    public function s2fil_filter_get_filter_cl (filter, iscale) result (filter_cl)
    public function s2fil_filter_get_tmpl_cl (filter, iscale) result (tmpl_cl)

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

Notes:

Regarding beams: See comment in s2fil_filter_init_data comment header.

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

Version: 0.1 January 2005

Description of Types

s2fil_filter

public type s2fil_filter
    private
    logical :: init = .false.
    integer :: lmax = 0
    integer :: mmax = 0
    integer :: n_scale = 0
    logical :: norm_pres_dil = S2FIL_NORM_PRES_DIL_DEFAULT
    integer :: filter_type = S2FIL_FILTER_TYPE_MF
    integer :: scale_type = S2FIL_FILTER_SCALE_TYPE_TMPL
    type (s2_pl) :: background
    type (s2_pl) :: beam
    type (s2_sky) :: tmpl
    real (kind=s2_sp), allocatable, dimension (:,:) :: scale
    type (s2_sky), allocatable, dimension (:) :: sky
    logical :: sky_status = .false.
    logical :: beam_status = .false.
end type s2fil_filter

Description of Variables

S2FIL_FILTER_TYPE_MF

integer, public, parameter :: S2FIL_FILTER_TYPE_MF = 1

Filter type: Matched filter.

S2FIL_FILTER_TYPE_SAF

integer, public, parameter :: S2FIL_FILTER_TYPE_SAF = 2

Filter type: Scale adaptive filter.

S2FIL_FILTER_TYPE_STR_MF

character (len=*), public, parameter :: S2FIL_FILTER_TYPE_STR_MF = 'mf'

Matched filter string description.

S2FIL_FILTER_TYPE_STR_SAF

character (len=*), public, parameter :: S2FIL_FILTER_TYPE_STR_SAF = 'saf'

Scale adaptive filter string description.

S2FIL_FILTER_SCALE_TYPE_TMPL

integer, public, parameter :: S2FIL_FILTER_SCALE_TYPE_TMPL = 1

Scale type: Scale template before

S2FIL_FILTER_SCALE_TYPE_FILTER

integer, public, parameter :: S2FIL_FILTER_SCALE_TYPE_FILTER = 2

Scale type: Scale filter

S2FIL_FILTER_SCALE_TYPE_STR_TMPL

character (len=*), public, parameter :: S2FIL_FILTER_SCALE_TYPE_STR_TMPL = 'tmpl'

Scale type template string description.

S2FIL_FILTER_SCALE_TYPE_STR_FILTER

character (len=*), public, parameter :: S2FIL_FILTER_SCALE_TYPE_STR_FILTER = 'filter'

Scale type filter string description.

Description of Interfaces

s2fil_filter_init

public interface s2fil_filter_init
    module procedure s2fil_filter_init_data
    module procedure s2fil_filter_init_copy
    module procedure s2fil_filter_init_file
end interface s2fil_filter_init

s2fil_filter_get_scale

public interface s2fil_filter_get_scale
    module procedure s2fil_filter_get_scale_array
    module procedure s2fil_filter_get_scale_val
end interface s2fil_filter_get_scale

Description of Subroutines and Functions

s2fil_filter_init_data

private function s2fil_filter_init_data (tmpl, background, scale, filter_type, scale_type, mmax, norm_pres_dil, beam, heuristic) result (filter)
    type (s2_sky), intent(in) :: tmpl
    type (s2_pl), intent(in) :: background
    real (kind=s2_sp), intent(in), dimension (:,:) :: scale
    integer, intent(in) :: filter_type
    integer, intent(in) :: scale_type
    integer, optional, intent(in) :: mmax
    logical, optional, intent(in) :: norm_pres_dil
    type (s2_pl), optional, intent(in) :: beam
    logical, optional, intent(in) :: heuristic
    type (s2fil_filter) :: filter
    ! Calls: s2_sky_set_lmax, s2fil_error, s2fil_filter_comp_filter
end function s2fil_filter_init_data

Initialise a filter structure directly from data.

Notes:

Tmpl is just a function defined on the sphere and does not have an inherent scale(/dilation) or rotation. The template function is assumed to be of scale one and zero rotation. Filters for all other scales are constructed from the template and its assumed unity scale.
Filter lmax is set as lmax of background.
If mmax is present and less than lmax, then set, else mmax is set to lmax.
Regarding beams: The filter template attribute is saved for a dilation of unity. When used the template is scaled to the appropriate size. When a beam is present the beam must be applied each time the template is used once the scaling has been performed. The beam must already be applied to the background before it is used to initialise the filter object. That is, the filter background attribute saved has already had a beam applied. This is because the background may consist of a cmb (for which the beam must be applied) plus noise (for which the beam is not applied to).

Variables:

tmpl: Template compact object defined on the sky.
background: Background power spectrum template object is embedded in.
scales: Scales of tmpl (dilations) to construct filters for.
[mmax]: Optional mmax which is only used if it's below the background lmax. Otherwise background lmax is used.
[norm_pres_dil]: Optional to specify whether norm preserving dilations are to be performed or not. Over-rides default filter%norm_pres_dil if included.
filter: Optimal filter constructed.

Author: J. D. McEwen

Version: 0.1 January 2005

s2fil_filter_init_copy

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

Initialise a filter structure as a copy of another filter.

Variables:

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

Author: J. D. McEwen

Version: 0.1 January 2005

s2fil_filter_init_file

private function s2fil_filter_init_file (filename) result (filter)
    character (len=*), intent(in) :: filename
    type (s2fil_filter) :: filter
    ! Calls: s2fil_error, s2fil_filter_io_fits_read
end function s2fil_filter_init_file

Initialise a filter structure from a filter file.

Variables:

filename: The fits file to read the filter from.
filter: Optimal filter constructed with the data read from the file.

Author: J. D. McEwen

Version: 0.1 January 2005

s2fil_filter_comp_filter

private subroutine s2fil_filter_comp_filter (filter, heu)
    type (s2fil_filter), intent(inout) :: filter
    logical, optional, intent(in) :: heu
    ! Calls: s2_pl_free, s2_pl_get_spec, s2_sky_compute_alm, s2_sky_compute_map, s2_sky_conv, s2_sky_dilate, s2_sky_free, s2_sky_get_alm, s2fil_error
end subroutine s2fil_filter_comp_filter

Compute the filter structure filter variable. Space for the filters is allocated here.

Notes:

All other filter variables must already be allocated and defined.
Filter status should not be set before calling functions, but sould be set be calling routine following call to this function.
Filter nside (for each scale) set from tmpl nside.
Start from l=2, thus monopole and dipole not considered. This is usually the case of interest.

Variables:

filter: Optimal filter object that filter variable is computed for.
[heu]: Logical specifying whether to adopt heuristic lmax level.

Author: J. D. McEwen

Version: 0.1 January 2005

s2fil_filter_free

public subroutine s2fil_filter_free (filter)
    type (s2fil_filter), intent(inout) :: filter
    ! Calls: s2_pl_free, s2_sky_free, s2fil_error
end subroutine s2fil_filter_free

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

Variables:

filter: The filter to be freed.

Author: J. D. McEwen

Version: 0.1 January 2005

s2fil_filter_io_fits_write

public subroutine s2fil_filter_io_fits_write (filename, filter, comment)
    character (len=*), intent(in) :: filename
    type (s2fil_filter), intent(in) :: filter
    character (len=*), optional, intent(in) :: comment
    ! Calls: ftclos, ftfiou, ftgiou, ftibin, ftinit, ftpcle, ftpcom, ftpdat, ftphpr, ftpkyj, ftpkyl, ftpkys, s2_pl_io_fits_write, s2_sky_io_fits_write, s2fil_error, s2fil_filter_io_fits_error_check, s2fil_filter_io_fits_exists
end subroutine s2fil_filter_io_fits_write

Write filter structure to a fits file.

Variables:

filename: Name of fits file to write to.
filter: The filter 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_filter_io_fits_read

private subroutine s2fil_filter_io_fits_read (filename, filter)
    character (len=*), intent(in) :: filename
    type (s2fil_filter), intent(out) :: filter
    ! Calls: ftclos, ftfiou, ftgcve, ftgiou, ftgkyj, ftgkyl, ftgkys, ftmahd, ftopen, ftthdu, s2fil_error, s2fil_filter_io_fits_error_check, s2fil_filter_io_fits_exists
end subroutine s2fil_filter_io_fits_read

Read a s2fil_filter file and all associated child files (i.e. template, background and skies).

Notes:

Child template, background and sky 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_filter_io_fits_error_check

private subroutine s2fil_filter_io_fits_error_check (status, halt)
    integer, intent(inout) :: status
    logical, intent(in) :: halt
    ! Calls: ftgerr, ftgmsg
end subroutine s2fil_filter_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_filter_io_fits_exists

private subroutine s2fil_filter_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_filter_io_fits_error_check
end subroutine s2fil_filter_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_filter_io_fits_del

private subroutine s2fil_filter_io_fits_del (filename, status)
    character (len=*), intent(in) :: filename
    integer, intent(inout) :: status
    ! Calls: ftcmsg, ftdelt, ftfiou, ftgiou, ftopen
end subroutine s2fil_filter_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_filter_write_filter_map

public subroutine s2fil_filter_write_filter_map (filter, iscale, filename, comment)
    type (s2fil_filter), intent(inout) :: filter
    integer, intent(in) :: iscale
    character (len=*), intent(in) :: filename
    character (len=*), optional, intent(in) :: comment
    ! Calls: s2_sky_compute_map, s2_sky_write_map_file, s2fil_error
end subroutine s2fil_filter_write_filter_map

Write a fits sky file for the filter at a specified scale.

Notes:

If the map of the filter chosen is not already computed it will be, hence the returned filter has intent inout since filter maps may have been computed.

Variables:

filter: The filter structure containing the filter map field to write to the file.
iscale: Scale of the filter (i.e. particular filter) to output.
filename: Name of output fits file.
[comment]: Optional comment appended to fits file header if present.

Author: J. D. McEwen

Version: 0.1 January 2005

s2fil_filter_get_init

public function s2fil_filter_get_init (filter) result (init)
    type (s2fil_filter), intent(in) :: filter
    logical :: init
end function s2fil_filter_get_init

Get init variable from the passed filter.

Variables:

filter: Filter object to get the variable of.
init: Object init variable returned.

Author: J. D. McEwen

Version: 0.1 January 2005

s2fil_filter_get_lmax

public function s2fil_filter_get_lmax (filter) result (lmax)
    type (s2fil_filter), intent(in) :: filter
    integer :: lmax
    ! Calls: s2fil_error
end function s2fil_filter_get_lmax

Get lmax variable from the passed filter.

Variables:

filter: Filter object to get the variable of.
lmax: Object lmax variable returned.

Author: J. D. McEwen

Version: 0.1 January 2005

s2fil_filter_get_mmax

public function s2fil_filter_get_mmax (filter) result (mmax)
    type (s2fil_filter), intent(in) :: filter
    integer :: mmax
    ! Calls: s2fil_error
end function s2fil_filter_get_mmax

Get mmax variable from the passed filter.

Variables:

filter: Filter object to get the variable of.
mmax: Object mmax variable returned.

Author: J. D. McEwen

Version: 0.1 January 2005

s2fil_filter_get_nside

public function s2fil_filter_get_nside (filter) result (nside)
    type (s2fil_filter), intent(in) :: filter
    integer :: nside
    ! Calls: s2fil_error
end function s2fil_filter_get_nside

Get n_scale variable from the passed filter. Note nside stored in tmpl sky.

Variables:

filter: Filter object to get nside of.
nside: Nside of the filter (stored in tmpl sky).

Author: J. D. McEwen

Version: 0.1 January 2005

s2fil_filter_get_n_scale

public function s2fil_filter_get_n_scale (filter) result (n_scale)
    type (s2fil_filter), intent(in) :: filter
    integer :: n_scale
    ! Calls: s2fil_error
end function s2fil_filter_get_n_scale

Get n_scale variable from the passed filter.

Variables:

filter: Filter object to get the variable of.
n_scale: Object n_scale variable returned.

Author: J. D. McEwen

Version: 0.1 January 2005

s2fil_filter_get_norm_pres_dil

public function s2fil_filter_get_norm_pres_dil (filter) result (norm_pres_dil)
    type (s2fil_filter), intent(in) :: filter
    logical :: norm_pres_dil
    ! Calls: s2fil_error
end function s2fil_filter_get_norm_pres_dil

Get norm_pres_dil variable from the passed filter.

Variables:

filter: Filter object to get the variable of.
norm_pres_dil: Object norm_pres_dil variable returned.

Author: J. D. McEwen

Version: 0.1 January 2005

s2fil_filter_get_filter_type

public function s2fil_filter_get_filter_type (filter) result (filter_type)
    type (s2fil_filter), intent(in) :: filter
    integer :: filter_type
    ! Calls: s2fil_error
end function s2fil_filter_get_filter_type

Get filter_type variable from the passed filter.

Variables:

filter: Filter object to get the variable of.
filter_type: Object filter_type variable returned.

Author: J. D. McEwen

Version: 0.1 January 2005

s2fil_filter_get_scale_type

public function s2fil_filter_get_scale_type (filter) result (scale_type)
    type (s2fil_filter), intent(in) :: filter
    integer :: scale_type
    ! Calls: s2fil_error
end function s2fil_filter_get_scale_type

Get scale_type variable from the passed filter.

Variables:

filter: Filter object to get the variable of.
scale_type: Object scale_type variable returned.

Author: J. D. McEwen

Version: 0.1 March 2005

s2fil_filter_get_background

public function s2fil_filter_get_background (filter) result (background)
    type (s2fil_filter), intent(in) :: filter
    type (s2_pl) :: background
    ! Calls: s2fil_error
end function s2fil_filter_get_background

Get background variable from the passed filter.

Notes:

Initialises a new background (s2_pl) object as a copy of the background stored herein. The returned (copy) background must be freed by the calling routine.

Variables:

filter: Filter object to get the variable of.
background: Copy of object background variable returned.

Author: J. D. McEwen

Version: 0.1 January 2005

s2fil_filter_get_beam

public function s2fil_filter_get_beam (filter) result (beam)
    type (s2fil_filter), intent(in) :: filter
    type (s2_pl) :: beam
    ! Calls: s2fil_error
end function s2fil_filter_get_beam

Get beam variable from the passed filter.

Notes:

Initialises a new beam (s2_pl) object as a copy of the beam stored herein. The returned (copy) beam must be freed by the calling routine.

Variables:

filter: Filter object to get the variable of.
beam: Copy of object beam variable returned.

Author: J. D. McEwen

Version: 0.1 January 2005

s2fil_filter_get_tmpl

public function s2fil_filter_get_tmpl (filter) result (tmpl)
    type (s2fil_filter), intent(in) :: filter
    type (s2_sky) :: tmpl
    ! Calls: s2fil_error
end function s2fil_filter_get_tmpl

Get tmpl variable from the passed filter.

Notes:

Initialises a new tmpl (s2_sky) object as a copy of the tmpl stored herein. The returned (copy) tmpl must be freed by the calling routine.

Variables:

filter: Filter object to get the variable of.
tmpl: Copy of object tmpl variable returned.

Author: J. D. McEwen

Version: 0.1 January 2005

s2fil_filter_get_scale_array

private subroutine s2fil_filter_get_scale_array (filter, scale)
    type (s2fil_filter), intent(in) :: filter
    real (kind=s2_sp), intent(out), dimension (:,:) :: scale
    ! Calls: s2fil_error
end subroutine s2fil_filter_get_scale_array

Get copy of scale array from the passed filter.

Notes:

Space for scale array must be allocated and deallocated by calling routine.

Variables:

filter: Filter object to get the variable of.
scale: Object scale array returned.

Author: J. D. McEwen

Version: 0.1 January 2005

s2fil_filter_get_scale_val

private subroutine s2fil_filter_get_scale_val (filter, iscale, one_scale)
    type (s2fil_filter), intent(in) :: filter
    integer, intent(in) :: iscale
    real (kind=s2_sp), intent(out), dimension (:) :: one_scale
    ! Calls: s2fil_error
end subroutine s2fil_filter_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:

filter: Filter object 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 January 2005

s2fil_filter_get_sky

public function s2fil_filter_get_sky (filter, iscale) result (sky)
    type (s2fil_filter), intent(in) :: filter
    integer, intent(in) :: iscale
    type (s2_sky) :: sky
    ! Calls: s2fil_error
end function s2fil_filter_get_sky

Get filter variable(/sky) corresponding to the iscale index from the passed filter.

Notes:

Initialises a new filter (s2_sky) object as a copy of the filter stored herein for the specified scale. The returned (copy) filter must be freed by the calling routine.

Variables:

filter: Filter object to get the variable of.
iscale: Index of scale to get.
filter: Copy of object filter variable returned corresponding to the specified scale.

Author: J. D. McEwen

Version: 0.1 January 2005

s2fil_filter_get_sky_status

public function s2fil_filter_get_sky_status (filter) result (sky_status)
    type (s2fil_filter), intent(in) :: filter
    logical :: sky_status
    ! Calls: s2fil_error
end function s2fil_filter_get_sky_status

Get sky_status variable from the passed filter.

Variables:

filter: Filter object to get the variable of.
sky_status: Object sky_status variable returned.

Author: J. D. McEwen

Version: 0.1 January 2005

s2fil_filter_get_filter_cl

public function s2fil_filter_get_filter_cl (filter, iscale) result (filter_cl)
    type (s2fil_filter), intent(in) :: filter
    integer, intent(in) :: iscale
    type (s2_pl) :: filter_cl
    ! Calls: s2fil_error
end function s2fil_filter_get_filter_cl

Compute and return filter cl spectrum for the iscale index specified.

Notes:

Initialises a new filter_cl (s2_pl) object. The returned filter_cl must be freed by the calling routine.
Alms of filter must already be computed (which they will be since the optimal filters are constructed in harmonic space).

Variables:

filter: Filter object to get the variable of.
iscale: Index of scale to get.
filter_cl: Object filter cl spectrum corresponding to the specified scale.

Author: J. D. McEwen

Version: 0.1 January 2005

s2fil_filter_get_tmpl_cl

public function s2fil_filter_get_tmpl_cl (filter, iscale) result (tmpl_cl)
    type (s2fil_filter), intent(in) :: filter
    integer, intent(in) :: iscale
    type (s2_pl) :: tmpl_cl
    ! Calls: s2_sky_compute_alm, s2_sky_conv, s2_sky_dilate, s2_sky_free, s2fil_error
end function s2fil_filter_get_tmpl_cl

Compute and return tmpl cl spectrum for the dilation corresponding to the iscale index specified.

Notes:

Initialises a new tmpl_cl (s2_pl) object. The returned tmpl_cl must be freed by the calling routine.
Requires dilation of template to specified scale, then alms of dilated template must be computed, before computing cls.

Variables:

filter: Filter object to get the variable of.
iscale: Index of scale to get.
tmpl_cl: Object tmpl cl spectrum corresponding to dilation specified by iscale.

Author: J. D. McEwen

Version: 0.1 January 2005