Commit f9db30bc authored by skamann's avatar skamann
Browse files

Finished documentation for SourceSelector class.

parent 10168d42
......@@ -33,7 +33,7 @@ Added
Latest SVN revision
-------------------
360, 2016/08/12
361, 2016/08/14
"""
import logging
import sys
......@@ -53,7 +53,7 @@ from ..utils.statistics import der_snr
__author__ = 'Sebastian Kamann (skamann@astro.physik.uni-goettingen.de)'
__revision__ = 360
__revision__ = 361
logger = logging.getLogger(__name__)
......@@ -300,7 +300,25 @@ class SourceSelector(object):
return True
def background_setup(self, skysize=-1):
"""
Method to add one or more background components.
One background component corresponds to a constant background across
the field of view. If more than one background component should be
used, the method will set up a grid. The background in each pixel will
then be obtained by interpolation of the grid points.
Parameters
----------
skysize : int, optional
The size of each cell of the background grid in pixels. Set to -1
for a constant background across the field of view.
Returns
-------
n_background : int
The number of background components used.
"""
if skysize <= 0:
background = BackgroundGrid.constant()
else:
......@@ -321,6 +339,14 @@ class SourceSelector(object):
return len(background.centroids)
def make_sources_instance(self):
"""
Method to create an instance of pampelmuse.core.Sources containing
the current list of stellar and background sources.
The method will run the intialisation method of the Sources-class and
copy the dispersion information from the IFs data to the new instance.
Afterwards, the instance can be accessed as SourceSelector().sources.
"""
self.sources = Sources(ids=np.asarray(self.cfp_results["id"], dtype=np.int32)[self.valid])
self.sources.x = np.asarray(self.cfp_results["x"], dtype=np.float32)[self.valid]
......@@ -345,7 +371,33 @@ class SourceSelector(object):
self.sources.cdelt = np.diff(self.ifs_data.wave).mean()
def prepare_psf(self, profile='moffat', parameters=None):
"""
Method to initialize the PSF that should be used in the source
selection process.
The method will define two properties, one containing the analytical
profile that should be used to model the PSF (accessible afterwards as
SourceSelector().psf_class) and one containing the values of the
individual parameters that define the profile (accessible afterwards
as SourceSelector().psf_attributes).
Parameters
----------
profile : str, optional
The name of the analytical profile used to model the PSF.
Currently 'moffat' (default), 'gauss', and 'double_gauss' are
supported.
parameters : list, optional
The values of the parameters of the chosen profile, provided as a
list that contains one dictionary per parameter. Each dictionary
should contain three keys:
- 'name': The name of the parameter
- 'value': The (initial) value of the parameter
- 'free': Boolean flag indicating if the parameter value should be
optimized in the analysis.
By default, a round Moffat profile with beta=2.5 and fwhm=3.0pixel
is used.
"""
if profile == "moffat":
self.psf_class = Moffat
elif profile == "gauss":
......@@ -370,6 +422,28 @@ class SourceSelector(object):
self.psf_attributes.info()
def create_mock_image(self, reslim, n_cpu=1):
"""
Method to create a mock image from the catalogue of sources.
This method creates a two dimensional image using the coordinates and
magnitudes for the available sources and the current PSF model. The
dimensions of the image are chosen so that all available sources are
included. For large catalogs, the parameter 'reslim' should be used
to only include a subset of bright stars in the image. After creation,
the image is available as SourceSelector().identification_image.
The image creation is parallelized and it uses the function
image_from_psf defined in this method.
Parameters
----------
reslim : float
The maximum magnitude of a source that is still included in the
image. Sources fainter than this value are ignored.
n_cpu : int, optional
The number of CPUs used to prepare the image.
"""
logger.info("Creating mock image from photometry catalogue...")
if self.sources is None:
......@@ -428,6 +502,23 @@ class SourceSelector(object):
self.identification_image[psf.y.astype('<i4'), psf.x.astype('<i4')] = _image
def create_image_from_ifs(self, n_bin=10):
"""
This method creates a two-dimensional image from the IFS data.
The image is created by integrating the IFS data over the passband in
which the magnitudes were provided. For large data cubes this can be
quite time-consuming. In those cases, consider using the the parameter
'n_bin' to reduce the computation time. Afterwards, the image is
accessible via SourceSelector().data_image. Note that the method will
also create an image with the average variances, accessible via
SourceSelector().var_image.
Parameters
----------
n_bin : int, optional
The binning factor; if >1, only every n_bin'th layer will be used
to create the image.
"""
logger.info("Creating mock {0}-band image from IFS data...".format(self.passband))
(self.data_image, self.var_image), weights = self.ifs_data.integrate_over_filtercurve(
......@@ -455,6 +546,28 @@ class SourceSelector(object):
logger.error("Flux sum in {0}-image is negative.".format(self.passband))
def cross_correlate_images(self, ccmaxoff=None, init_guess=None):
"""
This method tries to measure the offset between the IFS data and the
coordinates in the source catalogue.
The method will cross-correlate the image created from the IFS_data
with the mock image created from the source catalog and then find the
peak intensity of the cross-correlation signal if a pre-defined area.
The coordinates of this point are considered as the most-likely offset
between the two images and are accessible via SourceSelector().ccxoff
and SourceSelector().ccyoff afterwards.
Parameters
----------
ccmaxoff : float, optional
The maximum allowed offset between the two images in pixels.
init_guess : tuple, optional
Initial guesses for the offset along the x- and y-axes. The peak
in the cross-correlation signal is searched in a square with half-
width 'ccmaxoff' centred on the initial guess.
IMPORTANT: The offsets are measured relative to the initial guess
coordinates.
"""
if not self.use_wcs:
logger.error('Cannot perform cross-correlation unless valid WCS instance is available.')
......@@ -490,7 +603,26 @@ class SourceSelector(object):
self.sources.transformation.free[-2:] = True
def identify_footprint(self, reslim=20.):
"""
This method allows for a interactive determination of the location of
the IFS data relative to the source catalog.
This method will open the IFS data and the mock image created from the
source catalogue in the PampelMuse GUI. Then the locations of the
individual sources will be overplotted on the mock image. If the cross-
correlation via SourceSelector().cross_correlate_images() has been run
successfully before, the method will also overplot the likely location
of the IFS data on the mock image and the initial guesses of the
sources on the IFS data. Note that this method requires PyQt4 to be
installed on the system.
Parameters
----------
reslim : float, optional
The magnitude cut for sources that are overplotted on the mock image.
Note that it will be possible to adjust this parameter once the GUI
has been loaded.
"""
from PyQt4 import QtGui
from ..graphics import PampelMuseGui
......@@ -543,14 +675,33 @@ class SourceSelector(object):
logger.error("At least 2 sources must be identified.")
def calibrate_photometry(self, n_cpu=1, update_zeropoint=True):
# Perform photometric calibration (unless provided) and S/N estimation:
# This is done as follows:
# 1) Based on a hypothetical zeropoint, the flux profiles of all sources are determined and a hypothetical S/N
# estimate is obtained. This step is parallelized and also yields an estimate of the total flux in the image.
# 2) The integrated flux is compared to the sum of all pixel values in the broadband image created from the IFS
# data before. The ratio of these two fluxes can be converted into a magnitude difference between the
# hypothetical and the real zeropoint.
# 3) All S/N estimates are corrected for this magnitude difference
"""
This method performs a photometric calibration of the IFS data along
with an S/N estimation for all the sources in the catalog.
The method will perform the following steps to estimate the average
S/N of a source on the IFS data.
1) Based on a hypothetical zeropoint (i.e. the one provided during the
initialisation of the instance), the flux profiles of all sources
are determined and a hypothetical S/N estimate is obtained. This
step is parallelized and also yields an estimate of the total flux
in the image.
2) The integrated flux is compared to the sum of all pixel values in
the broadband image created from the IFS data before. The ratio of
these two fluxes can be converted into a magnitude difference
between the hypothetical and the real zeropoint.
3) All S/N estimates are corrected for this magnitude difference
Parameters
----------
n_cpu : int, optional
the number of CPUs used in the parallelized part of the method.
update_zeropoint : bool, optional
Flag indicating if the zeropoint should be updated based on the
flux comparison with the IFS data. If not, the S/N estimates of
all sources are based on the zeropoint provided upon
initialisation of the instance.
"""
logger.info("Estimating S/N for all sources...")
if self.var_image is None:
......@@ -628,6 +779,7 @@ class SourceSelector(object):
def select(self, reslim=None, sncut=3., confusion_density=0.4, binrad=0.2, use_unres=False, unres_range=2):
"""
This method performs the source selection process for the PSF fitting,
Each source is given a status based on criteria such as the estimated
S/N, the distance brighter sources or the edge of the field of view.
The status of a source can be one of the following:
......@@ -642,16 +794,29 @@ class SourceSelector(object):
Parameters
----------
reslim
confusion_density
sncut
binrad
use_unres
unres_range
Returns
-------
reslim : float, optional
If this parameter is set to a value different from None, the
method will not try to determine the confusion limit itself but
will only include sources brighter than the provided value.
confusion_density : float, optional
The source density where the confusion limit is reached, provided
as [no. of sources]/[resolution element]. A value of 0.4 gave good
results for the simulations performed in Kamann et al. (2013).
sncut : float, optional
The minimum S/N a source must have to be still included.
binrad : float, optional
The minimum distance for which sources are considered resolved,
provided relative to the FWHM of the PSF profile. Sources with
mutual distances below this value will be combined in the
analysis.
use_unres : bool, optional
Flag indicating if an unresolved component should be included in
the selection.
unres_range : float, optional
If an unresolved component should be included, this parameter
gives the range in magnitudes of the sources that are included in
the component. Note that the bright end of this range is set to
the magnitude of the faintest resolved source.
"""
logger.info("Selecting sources to be used in PSF fitting...")
......@@ -795,13 +960,17 @@ class SourceSelector(object):
def search_psf_stars(self, saturated=None, max_mag=None, psf_radius=10, aperture_noise=0.1):
"""
This method searches the photometry for stars suited to constrain the
the PSF. Such stars must fulfil the following criteria:
the PSF.
Stars that are considered suitable for constraining the PSF must
fulfil the following criteria:
(1) brighter than the provided magnitude limit (parameter max_mag)
(2) must have been identified as resolved (i.e. status==2) in the
source catalog
(3) must not have close companions (sources with status=1)
(4) must have an estimated S/N above the provided cut (this is
estimated using aperture photometry)
# (4) must have an estimated S/N above the provided cut (this is
# estimated using aperture photometry)
# This criterion is currently not used.
(5) at a distance of at least the PSF FWHM from the edge of the FoV
(2 x FWHM for MUSE)
(6) isolation criteria:
......@@ -820,14 +989,17 @@ class SourceSelector(object):
Parameters
----------
saturated
max_mag
psf_radius
aperture_noise
Returns
-------
saturated : list, optional
A list of source IDs that should be excluded from the PSF star
search, e.g. because they are saturated in the IFS data.
max_mag : float, optional
The maximum allowed magnitude of a PSF star.
psf_radius : float, optional
The radius out to which the PSF profiles are calculated. The
isolation criterion will be checked in a circle with this radius.
aperture_noise : float, optional
The maximum allowed contamination of a nearby source inside the
area where the PSF profile is defined.
"""
logger.info("Searching for possible PSF stars...")
......@@ -897,7 +1069,40 @@ class SourceSelector(object):
return
def run_aperture_photometry(self, ids=None, start=0, stop=-1, radius=3, n_cpu=1, n_bin=1):
"""
Method to perform aperture photometry for a subset of the source
catalog on the layers of the IFS data.
Based on the estimates for the centroid coordinates in the IFS data,
this method will obtain spectra for a given set of sources by
performing aperture photometry for those sources on all layers of the
IFs data. At the same time, the method will refine the centroids and
also obtain estimates of the PSF parameters using the spatial moments
measured during the analysis. The results will be written to the
SourceSelector().sources and SourceSelector().psf_attributes
properties.
Parameters
----------
ids : list, optional
The IDs of the stars for which the analysis should be performed.
If none are provided, the method will use all sources that have
status=3 in the SourceSelector().sources property.
start : int, optional
The first layer of the IFS data for which the analysis should be
performed.
stop : int, optional
The last layer of the IFS data for which the analysis should be
performed.
radius : int, optional
The aperture radius inside which the flux and the moments of each
source are determined.
n_cpu : int optional
The number of CPUs used in the parallized part of the analysis.
n_bin : int, optional
The binning factor of the IFS data. If >1, one new layer is created
by combining the signal from 'n_bin' adjacent layers.
"""
# carry out aperture spectrophotometry for PSF sources
logger.info("Initializing aperture spectrophotometry for possible PSF stars...")
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment