lenstronomy.Data package¶
Submodules¶
lenstronomy.Data.coord_transforms module¶
-
class
Coordinates
(transform_pix2angle, ra_at_xy_0, dec_at_xy_0)[source]¶ Bases:
object
Class to handle linear coordinate transformations of a square pixel image.
-
__init__
(transform_pix2angle, ra_at_xy_0, dec_at_xy_0)[source]¶ Initialize the coordinate-to-pixel transform and their inverse.
Parameters: - transform_pix2angle – 2x2 matrix, mapping of pixel to coordinate
- ra_at_xy_0 – ra coordinate at pixel (0,0)
- dec_at_xy_0 – dec coordinate at pixel (0,0)
-
coordinate_grid
(nx, ny)[source]¶ Parameters: - nx – number of pixels in x-direction
- ny – number of pixels in y-direction
Returns: 2d arrays with coordinates in RA/DEC with ra_coord[y-axis, x-axis]
-
map_coord2pix
(ra, dec)[source]¶ Maps the (ra,dec) coordinates of the system into the pixel coordinate of the image.
Parameters: - ra – relative RA coordinate as defined by the coordinate frame
- dec – relative DEC coordinate as defined by the coordinate frame
Returns: (x, y) pixel coordinates
-
map_pix2coord
(x, y)[source]¶ Maps the (x,y) pixel coordinates of the image into the system coordinates.
Parameters: - x – pixel coordinate (can be 1d numpy array), defined in the center of the pixel
- y – pixel coordinate (can be 1d numpy array), defined in the center of the pixel
Returns: relative (RA, DEC) coordinates of the system
-
pixel_area
¶ Angular area of a pixel in the image.
Returns: area [arcsec^2]
-
pixel_width
¶ Size of pixel.
Returns: sqrt(pixel_area)
-
radec_at_xy_0
¶ Returns: RA, DEC coordinate at (0,0) pixel coordinate
-
shift_coordinate_system
(x_shift, y_shift, pixel_unit=False)[source]¶ Shifts the coordinate system.
Parameters: - x_shift – shift in x (or RA)
- y_shift – shift in y (or DEC)
- pixel_unit – bool, if True, units of pixels in input, otherwise RA/DEC
Returns: updated data class with change in coordinate system
-
transform_angle2pix
¶ Returns: transformation matrix from angular to pixel coordinates
-
transform_pix2angle
¶ Returns: transformation matrix from pixel to angular coordinates
-
xy_at_radec_0
¶ Returns: pixel coordinate at angular (0,0) point
-
-
class
Coordinates1D
(transform_pix2angle, ra_at_xy_0, dec_at_xy_0)[source]¶ Bases:
lenstronomy.Data.coord_transforms.Coordinates
Coordinate grid described in 1-d arrays.
lenstronomy.Data.image_noise module¶
-
class
ImageNoise
(image_data, exposure_time=None, background_rms=None, noise_map=None, gradient_boost_factor=None, verbose=True, flux_scaling=1)[source]¶ Bases:
object
Class that deals with noise properties of imaging data.
-
C_D
¶ Covariance matrix of all pixel values in 2d numpy array (only diagonal component) The covariance matrix is estimated from the data. WARNING: For low count statistics, the noise in the data may lead to biased estimates of the covariance matrix.
Returns: covariance matrix of all pixel values in 2d numpy array (only diagonal component).
-
C_D_model
(model)[source]¶ Parameters: model – model (same as data but without noise) Returns: estimate of the noise per pixel based on the model flux
-
__init__
(image_data, exposure_time=None, background_rms=None, noise_map=None, gradient_boost_factor=None, verbose=True, flux_scaling=1)[source]¶ Parameters: - image_data – numpy array, pixel data values
- exposure_time – int or array of size the data; exposure time (common for all pixels or individually for each individual pixel)
- background_rms – root-mean-square value of Gaussian background noise
- noise_map – int or array of size the data; joint noise sqrt(variance) of each individual pixel. Overwrites meaning of background_rms and exposure_time.
- gradient_boost_factor – None or float, variance terms added in quadrature scaling with gradient^2 * gradient_boost_factor
- flux_scaling (float or int (default=1)) – scales the model amplitudes to match the imaging data units. This can be used, for example, when modeling multiple exposures that have different magnitude zero points (or flux normalizations) but demand the same model normalization
-
background_rms
¶ Returns: rms value of background noise
-
exposure_map
¶ Units of data and exposure map should result in: number of flux counts = data * exposure_map
Returns: exposure map for each pixel
-
-
covariance_matrix
(data, background_rms, exposure_map, gradient_boost_factor=None)[source]¶ Returns a diagonal matrix for the covariance estimation which describes the error.
Notes:
- the exposure map must be positive definite. Values that deviate too much from the mean exposure time will be
- given a lower limit to not under-predict the Poisson component of the noise.
- the data must be positive semi-definite for the Poisson noise estimate.
- Values < 0 (Possible after mean subtraction) will not have a Poisson component in their noise estimate.
Parameters: - data – data array, eg in units of photons/second
- background_rms – background noise rms, eg. in units (photons/second)^2
- exposure_map – exposure time per pixel, e.g. in units of seconds
- gradient_boost_factor – None or float, variance terms added in quadrature scaling with gradient^2 * gradient_boost_factor
Returns: len(d) x len(d) matrix that give the error of background and Poisson components; (photons/second)^2
lenstronomy.Data.imaging_data module¶
-
class
ImageData
(image_data, exposure_time=None, background_rms=None, noise_map=None, gradient_boost_factor=None, ra_at_xy_0=0, dec_at_xy_0=0, transform_pix2angle=None, ra_shift=0, dec_shift=0, phi_rot=0, log_likelihood_constant=0, antenna_primary_beam=None, likelihood_method='diagonal', flux_scaling=1)[source]¶ Bases:
lenstronomy.Data.pixel_grid.PixelGrid
,lenstronomy.Data.image_noise.ImageNoise
Class to handle the data, coordinate system and masking, including convolution with various numerical precisions.
The Data() class is initialized with keyword arguments:
- ‘image_data’: 2d numpy array of the image data
- ‘transform_pix2angle’ 2x2 transformation matrix (linear) to transform a pixel shift into a coordinate shift (x, y) -> (ra, dec)
- ‘ra_at_xy_0’ RA coordinate of pixel (0,0)
- ‘dec_at_xy_0’ DEC coordinate of pixel (0,0)
optional keywords for shifts in the coordinate system:
- ‘ra_shift’: shifts the coordinate system with respect to ‘ra_at_xy_0’
- ‘dec_shift’: shifts the coordinate system with respect to ‘dec_at_xy_0’
optional keywords for noise properties:
- ‘background_rms’: rms value of the background noise
- ‘exp_time’: float, exposure time to compute the Poisson noise contribution
- ‘exposure_map’: 2d numpy array, effective exposure time for each pixel. If set, will replace ‘exp_time’
- ‘noise_map’: Gaussian noise (1-sigma) for each individual pixel.
If this keyword is set, the other noise properties will be ignored.
optional keywords for interferometric quantities:
- ‘likelihood_method’: need to be specified to ‘interferometry_natwt’ if one needs to use the interferometric likelihood function.
The default of ‘likelihood_method’ is ‘diagonal’, which is used for non-correlated noises (usually for the CCD images.)
- ‘log_likelihood_constant’: a constant that adds to logL.
- ‘antenna_primary_beam’: primary beam pattern of antennae (now treat each antenna dish with the same primary beam).
** notes ** the likelihood for the data given model P(data|model) is defined in the function below. Please make sure that your definitions and units of ‘exposure_map’, ‘background_rms’ and ‘image_data’ are in accordance with the likelihood function. In particular, make sure that the Poisson noise contribution is defined in the count rate.
-
__init__
(image_data, exposure_time=None, background_rms=None, noise_map=None, gradient_boost_factor=None, ra_at_xy_0=0, dec_at_xy_0=0, transform_pix2angle=None, ra_shift=0, dec_shift=0, phi_rot=0, log_likelihood_constant=0, antenna_primary_beam=None, likelihood_method='diagonal', flux_scaling=1)[source]¶ Parameters: - image_data – 2d numpy array of the image data
- exposure_time – int or array of size the data; exposure time (common for all pixels or individually for each individual pixel)
- background_rms – root-mean-square value of Gaussian background noise in units counts per second
- noise_map – int or array of size the data; joint noise sqrt(variance) of each individual pixel.
- gradient_boost_factor – None or float, variance terms added in quadrature scaling with gradient^2 * gradient_boost_factor
- transform_pix2angle – 2x2 matrix, mapping of pixel to coordinate
- ra_at_xy_0 – ra coordinate at pixel (0,0)
- dec_at_xy_0 – dec coordinate at pixel (0,0)
- ra_shift – RA shift of pixel grid
- dec_shift – DEC shift of pixel grid
- log_likelihood_constant – float, allows user to input a constant that will be added to the log likelihood. Note that, as for now, this variable is ONLY used for interferometric mode.
- antenna_primary_beam – 2d numpy array with the same size of imaga_data;
- phi_rot – rotation angle in regard to pixel coordinate transform_pix2angle
- antenna_primary_beam – 2d numpy array with the same size of image_data; more descriptions of the primary beam can be found in the AngularSensitivity class
- likelihood_method – string, type of method of log_likelihood computation: options are ‘diagonal’, ‘interferometry_natwt’. The default option ‘diagonal’ uses a diagonal covariance matrix, which is the case for CCD images. The ‘interferometry_natwt’ option uses our special interferometric likelihood function based on natural weighting images.
- flux_scaling – scales the model amplitudes to match the imaging data units. This can be used, for example, when modeling multiple exposures that have different magnitude zero points (or flux normalizations) but demand the same model normalization
-
data
¶ Returns: 2d numpy array of data
-
likelihood_method
()[source]¶ Pass the likelihood_method to the ImageModel and will be used to identify the method of likelihood computation in ImageLinearFit.
Returns: string, likelihood method
-
log_likelihood
(model, mask, additional_error_map=0)[source]¶ Computes the likelihood of the data given the model p(data|model) The Gaussian errors are estimated with the covariance matrix, based on the model image. The errors include the background rms value and the exposure time to compute the Poisson noise level (in Gaussian approximation).
Parameters: - model – the model (same dimensions and units as data)
- mask – bool (1, 0) values per pixel. If =0, the pixel is ignored in the likelihood
- additional_error_map – additional error term (in same units as covariance matrix). This can e.g. come from model errors in the PSF estimation.
Returns: the natural logarithm of the likelihood p(data|model)
-
log_likelihood_interferometry
(model)[source]¶ log_likelihood function for natural weighting interferometric images, based on (placeholder for Nan Zhang’s paper).
For the interferometry case, the model should be in the form [array1, array2], where array1 and array2 are unconvolved and convolved model images respectively. They are both 2d array with the same shape of the data.
The chi^2 of interferometry is computed by
\[\chi^2 = (d-Ax)^TC^{-1}(d-Ax) = \frac{1}{\sigma^2}(d^TA^{-1}d - 2x^Td + x^TAx)\]where \(d\) and \(x\) are the data vector and the unconvolved model image vector respectively. \(A\) is the convolution operation matrix, where we normalize the PSF by setting its central pixel to 1. \(C\) is the noise covariance matrix, its diagonal entries are rms^2 of noises, \(\sigma^2\). For natural weighting interferometric images, we used the relation (see Section 3.2 of https://doi.org/10.1093/mnras/staa2740 for the relation of natural weighting covariance matrix and PSF convolution)
\[C = \sigma^2 A\]to simplify the likelihood function above.
lenstronomy.Data.pixel_grid module¶
-
class
PixelGrid
(nx, ny, transform_pix2angle, ra_at_xy_0, dec_at_xy_0, antenna_primary_beam=None)[source]¶ Bases:
lenstronomy.Data.coord_transforms.Coordinates
,lenstronomy.Data.angular_sensitivity.AngularSensitivity
Class that manages a specified pixel grid (rectangular at the moment) and its coordinates.
-
__init__
(nx, ny, transform_pix2angle, ra_at_xy_0, dec_at_xy_0, antenna_primary_beam=None)[source]¶ Parameters: - nx – number of pixels in x-axis
- ny – number of pixels in y-axis
- transform_pix2angle – 2x2 matrix, mapping of pixel to coordinate
- ra_at_xy_0 – ra coordinate at pixel (0,0)
- dec_at_xy_0 – dec coordinate at pixel (0,0)
- antenna_primary_beam – 2d numpy array with the same size of imaga_data; more descriptions of the primary beam can be found in the AngularSensitivity class
-
center
¶ Returns: center_x, center_y of coordinate system
-
num_pixel
¶ Returns: number of pixels in the data
-
num_pixel_axes
¶ Returns: number of pixels per axis, nx ny
-
pixel_coordinates
¶ Returns: RA coords, DEC coords
-
shift_coordinate_system
(x_shift, y_shift, pixel_unit=False)[source]¶ Shifts the coordinate system :param x_shift: shift in x (or RA) :param y_shift: shift in y (or DEC) :param pixel_unit: bool, if True, units of pixels in input, otherwise RA/DEC :return: updated data class with change in coordinate system.
-
width
¶ Returns: width of data frame
-
lenstronomy.Data.psf module¶
-
class
PSF
(psf_type='NONE', fwhm=None, truncation=5, pixel_size=None, kernel_point_source=None, psf_error_map=None, point_source_supersampling_factor=1, kernel_point_source_init=None, kernel_point_source_normalisation=True)[source]¶ Bases:
object
Point Spread Function class.
This class describes and manages products used to perform the PSF modeling (convolution for extended surface brightness and painting of PSF’s for point sources).
-
__init__
(psf_type='NONE', fwhm=None, truncation=5, pixel_size=None, kernel_point_source=None, psf_error_map=None, point_source_supersampling_factor=1, kernel_point_source_init=None, kernel_point_source_normalisation=True)[source]¶ Parameters: - psf_type – string, type of PSF: options are ‘NONE’, ‘PIXEL’, ‘GAUSSIAN’
- fwhm – float, full width at half maximum, only required for ‘GAUSSIAN’ model
- truncation – float, Gaussian truncation (in units of sigma), only required for ‘GAUSSIAN’ model
- pixel_size – width of pixel (required for Gaussian model, not required when using in combination with ImageModel modules)
- kernel_point_source – 2d numpy array, odd length, centered PSF of a point source (if not normalized, will be normalized)
- psf_error_map – uncertainty in the PSF model per pixel (size of data, not super-sampled). 2d numpy array. Size can be larger or smaller than the pixel-sized PSF model and if so, will be matched. This error will be added to the pixel error around the position of point sources as follows: sigma^2_i += ‘psf_error_map’_j * <point source amplitude>**2
- point_source_supersampling_factor – int, supersampling factor of kernel_point_source. This is the input PSF to this class and does not need to be the choice in the modeling (thought preferred if modeling choses supersampling)
- kernel_point_source_init – memory of an initial point source kernel that gets passed through the psf iteration
- kernel_point_source_normalisation – boolean, if False, the pixel PSF will not be normalized automatically.
-
fwhm
¶ Returns: full width at half maximum of kernel (in units of pixel)
-
kernel_pixel
¶ Returns the convolution kernel for a uniform surface brightness on a pixel size.
Returns: 2d numpy array
-
kernel_point_source
¶
-
kernel_point_source_supersampled
(supersampling_factor, updata_cache=True)[source]¶ Generates (if not already available) a supersampled PSF with ood numbers of pixels centered.
Parameters: - supersampling_factor – int >=1, supersampling factor relative to pixel resolution
- updata_cache – boolean, if True, updates the cached supersampling PSF if generated. Attention, this will overwrite a previously used supersampled PSF if the resolution is changing.
Returns: super-sampled PSF as 2d numpy array
-
psf_error_map
¶ Error variance of the normalized PSF.
This error will be added to the pixel error around the position of point sources as follows: sigma^2_i += ‘psf_error_map’_j * <point source amplitude>**2
Returns: error variance of the normalized PSF. Variance of Return type: 2d numpy array of size of the PSF in pixel size (not supersampled)
-