tokult package

Submodules

Module contents

Tokult — Tools of Kinematics on UV-plane for Lensed Targets

Tokult is a kinematics fitting tool.

class tokult.Tokult(datacube, dirtybeam=None, gravlens=None)

Bases: object

Interface of Tokult.

Users specify data to launch an instance object and start fitting through the instance. This class contains observed data, psf, and lensing parameters, along with useful functions to manipulate data and models.

Parameters:

  • datacube (DataCube) –

  • dirtybeam (Optional[DirtyBeam], optional) – Defaults to None.

  • gravlens (Optional[GravLens], optional) – Defaults to None.

Examples

>>> import tokult
>>> tok = tokult.Tokult.launch('data.fits', 'psf.fits',
                             ('x-arcsec-deflect.fits', 'y-arcsec-deflect.fits'))
classmethod launch(data, beam=None, gravlens=None, header_data=None, header_beam=None, header_gravlens=None, index_data=0, index_beam=0, index_gravlens=0)

Constructer of Tokult.

Construct an instance easier than to use the init constructer.

Parameters:

  • data (Union[np.ndarray, str]) – Observed data. The format is a data array or a fits file name.

  • beam (Union[np.ndarray, str, None], optional) – Dirty beam or point spread function (PSF). The format is a data array or a fits file name. Defaults to None.

  • gravlens (Union[tuple[np.ndarray, ...], tuple[str, ...]], None, optional) – Gravitational lensing parameters. The format is a tuple containing the three data array or fits file names of parameters: x_arcsec_deflect and y_arcsec_deflect. Defaults to None.

  • header_data (Optional[fits.Header], optional) – Header of data. Defaults to None. This is necessary when the data is not given in a fits file.

  • header_beam (Optional[fits.Header], optional) – Header of psf. Defaults to None. This is necessary when beam is not given in a fits file.

  • header_gravlens (Optional[fits.Header], optional) – Header of gravlens. Defaults to None. This is necessary when gravlens is not given in fits files.

  • index_data (int, optional) – Index of fits extensions of the data fits file. Defaults to 0.

  • index_beam (int, optional) – Index of fits extensions of the beam fits file. Defaults to 0.

  • index_gravlens (int, optional) – Index of fits extensions of the lens fits files. Defaults to 0.

Return type:

Tokult

Examples

>>> tok = tokult.Tokult.launch(
             'data.fits', 'psf.fits',
             (x_arcsec_deflect.fits', y_arcsec_deflect.fits'))
imagefit(init, bound=None, fix=None, optimization='mc', niter=1, nperturb=1000, nwalkers=64, nsteps=5000, pool=None, is_separate=False, mask_for_fit=None, uvcoverage=None, progressbar=False)

Fit a 3d model to the data cube on the image plane.

Parameters:

  • init (Sequence[float]) – Initial parameters of fitting.

  • bound (Optional[tuple[Sequence[float], Sequence[float]], optional) – Boundaries of parameters. Defaults to None. When None is given, the default parameter boundaries are used. The boundaries can be easily set using get_bound_params. Currently, in the mcmc method, only flat prior distributions are available through this argument.

  • fix (Optional[fitting.FixParams], optional) – Defaults to None.

  • optimization (str, optional) – Defaults to ‘mc’.

  • niter (int, optional) – Number of iterations of fitting, used in the least square method. Defaults to 1.

  • nperturb (int, optional) – Number of perturbations in the Monte Carlo method. Defaults to 1000.

  • nwalkers (int, optional) – Number of walkers, used in the MCMC method. Defaults to 64.

  • nsteps (int, optional) – Number of steps, used in the MCMC method. Defaults to 5000.

  • pool (Optional[Pool], optional) – multiprocessing.pool for a multi-process MCMC fitting. Defaults to None.

  • is_separate (bool, optional) – If True, parameters regarding kinematics and emission are separated; and thus fitting uses all the 14 parameters. If False, the parameters are the same and the number of free parameters are reduced. Defaults to False.

  • mask_for_fit (Optional[np.ndarray], optional) – Mask specifying pixels used for fitting. Defaults to None.

  • progressbar (bool, optional) – If True, a progress bar is shown. Defaults to False.

  • uvcoverage (ndarray | None) –

Returns:

Fitting results and related parameters.

Return type:

fitting.Solution

Examples

>>> sol = tok.imagefit(init, bound, optimization='mc')
uvfit(init, bound=None, fix=None, optimization='mcmc', niter=1, nwalkers=64, nsteps=5000, pool=None, is_separate=False, mask_for_fit=None, progressbar=False)

Fit a 3d model to the data cube on the uv plane.

Parameters:

  • init (Sequence[float]) – Initial parameters of fitting. a function to guess initial parameters: tokult.initialguess().

  • bound (Optional[tuple[Sequence[float], Sequence[float]], optional) – Boundaries of parameters. Defaults to None. When None is given, the default parameter boundaries are used. The boundaries can be easily set using get_bound_params. Currently, in the mcmc method, only flat prior distributions are available through this argument.

  • fix (Optional[fitting.FixParams], optional) – Fix parameters during fitting. See FixParams. Defaults to None.

  • optimization (str, optional) – Method to optimize the 3D model. - ‘ls’: least square method. - ‘mcmc’: Malcov Chain Monte Carlo method. Defaults to ‘mcmc’.

  • niter (int, optional) – Number of iterations of fitting, used in the least square method. Defaults to 1.

  • nperturb (int, optional) – Number of perturbations in the Monte Carlo method. Defaults to 1000.

  • nwalkers (int, optional) – Number of walkers, used in the MCMC method. Defaults to 64.

  • nsteps (int, optional) – Number of steps, used in the MCMC method. Defaults to 5000.

  • pool (Optional[Pool], optional) – multiprocessing.pool for a multi-process MCMC fitting. Defaults to None.

  • is_separate (bool, optional) – If True, parameters regarding kinematics and emission are separated; and thus fitting uses all the 14 parameters. If False, the parameters are the same and the number of free parameters are reduced. Defaults to False.

  • mask_for_fit (Optional[np.ndarray], optional) – Mask specifying pixels used for fitting. In uv fitting, specifying the uv-coverage is important, which is passed through this argument. Defaults to None.

  • progressbar (bool, optional) – If True, a progress bar is shown. Defaults to False.

Returns:

Fitting results and related parameters.

Return type:

fitting.Solution

Examples

>>> sol = tok.uvfit(init, bound, optimization='mcmc')

Note

The input parameters are the same as imagefit.

initialguess(is_separate=False)

Guess initial input parameters for fitting.

Fit tow-dimensional moment-0 (flux) map and moment-1 (velocity) map then Estimate input parameters from the 2-d fitting results.

Parameters:

is_separate (bool, optional) – If True, parameters regarding kinematics and emission are separated; and thus fitting uses all the 14 parameters. If False, the parameters are the same and the number of free parameters are reduced. Defaults to False.

Returns:

Best-guessed input parameters.

Return type:

fitting.InputParams

Examples

>>> init = tok.initialguess()

Note

Initial parameters are crucial for parameter fitting, especially in the least-square and Monte Carlo methods and being related with speed of convergence in the MCMC method.

use_region(xlim=None, ylim=None, vlim=None)

Use a region of datacube used for fitting.

Parameters:

  • xlim (Optional[tuple[int, int]], optional) – The limit of the x-axis. Defaults to None.

  • ylim (Optional[tuple[int, int]], optional) – The limit of the y-axis. Defaults to None.

  • vlim (Optional[tuple[int, int]], optional) – The limit of the v-axis. Defaults to None.

Return type:

None

Examples

>>> tok.use_region((32, 96), (32, 96), (5, 12))

Note

In uvfit, the v-axis limit must be specified smaller than original cube size, because uvfit estimates the noise level using the pixels outside vlim.

use_redshifts(z_source, z_lens, z_assumed=inf)

Set the redshifts of the source and the lens galaxies.

The redshifts are used to compute the gravitational lensing effects and to convert the parameters to the physical units.

Parameters:

  • z_source (float) – The source (galaxy) redshift.

  • z_lens (float) – The lens (cluster) redshift.

  • z_assumed (float, optional) – The redshift assumed in the gravitational parameters. If D_s / D_L = 1, the value should be infinite (np.inf). Defaults to np.inf.

Return type:

None

Examples

>>> tok.use_redshift(z_source=6.2, z_lens=0.9)
change_datacube(data_or_fname, header=None, index_hdul=0, xlim=None, ylim=None, vlim=None)

Change the variable datacube.

May be useful to change datacube of an instance.

Nonte:

This method should be used before use_region and use_redshift.

Parameters:

  • data_or_fname (ndarray | str) –

  • header (Header | None) –

  • index_hdul (int) –

  • xlim (tuple[int, int] | None) –

  • ylim (tuple[int, int] | None) –

  • vlim (tuple[int, int] | None) –

Return type:

None

change_dirtybeam(data_or_fname, header=None, index_hdul=0)

Change the variable dirtybeam.

May be useful to change dirtybeam of an instance.

Nonte:

This method should be used before use_region and use_redshift.

Parameters:

  • data_or_fname (ndarray | str) –

  • header (Header | None) –

  • index_hdul (int) –

Return type:

None

change_gravlens(*, data_or_fname_xy_arcsec_deflect=None, data_or_fname_xy_pixel_deflect=None, data_or_fname_psi_arcsec=None, header=None, index_hdul=0)

Change the variable gravlens.

May be useful to change gravlens of an instance.

Nonte:

This method should be used before use_region and use_redshift.

Parameters:

  • data_or_fname_xy_arcsec_deflect (tuple[numpy.ndarray, ...] | tuple[str, ...] | None) –

  • data_or_fname_xy_pixel_deflect (tuple[numpy.ndarray, ...] | tuple[str, ...] | None) –

  • data_or_fname_psi_arcsec (ndarray | str | None) –

  • header (Header | None) –

  • index_hdul (int) –

Return type:

None

construct_modelcube(params)

Construct modelcube from the input parameters.

Construct a 3D model and set it to an internal variable modelcube. If you want to use a model outside Tokult instances, please use ModelCube.create() instead.

Parameters:

params (tuple[float, ...]) – Input parameters.

Return type:

None

Examples

Change a part of the best-fit parameters and construct the model.

>>> params = sol.best._replace(PA_dyn=0.0)
>>> tok.construct_modelcube(params)

Note

This method needs the global parameters to be set already. You may need to fit the data once, before using this method.

calculate_normweight()

Calculate the normalization weight used in uvfit.

The obtained value is almost equal to sum-of-weight, but different by a factor of a few.

Returns:

The normalization weight

Return type:

float

class tokult.Cube(imageplane, header=None, xlim=None, ylim=None, vlim=None)

Bases: object

3D data cube.

Examples

>>>
Parameters:

  • imageplane (np.ndarray) –

  • header (Optional[fits.Header]) –

  • xlim (Optional[tuple[int, int]]) –

  • ylim (Optional[tuple[int, int]]) –

  • vlim (Optional[tuple[int, int]]) –

imageplane

Cutout 3D data cube on the image plane.

Type:

np.ndarray

uvplane

Cutout 3D data cube on the uv plane. This is the Fourier transformation of imageplane.

Type:

np.ndarray

original

Original-size, 3D data cube.

Type:

np.ndarray

header

Header of the fits data. Defaults to None.

Type:

Optional[fits.Header]

cutout(xlim=None, ylim=None, vlim=None)

Cutout 3D cube from original.

Parameters:

  • xlim (Optional[tuple[int, int]], optional) – The limit of the x-axis. Defaults to None.

  • ylim (Optional[tuple[int, int]], optional) – The limit of the y-axis. Defaults to None.

  • vlim (Optional[tuple[int, int]], optional) – The limit of the v-axis. Defaults to None.

Return type:

None

Examples

>>> cube.cutout((32, 96), (32, 96), (5, 12))
rms(is_originalsize=False)

Compute the rms noise of the data cube.

Compute the rms noise using pixels outside of the region used for imageplane, by assuming that the pixels are not affected by any objects and reflect pure noises.

Parameters:

  • is_originalsize (bool, optional) – If False, the computed rms noise is

  • True (limited at vlim of imageplane. If) –

  • is (the rms noise) –

  • False. (computed using the original-size data cube. Defaults to) –

Returns:

the one-dimensional array containing the rms noises at each pixel (channel) along the velocity axis.

Return type:

np.ndarray

Examples

>>> rms = cube.rms()

Note

This method may not return the correct rms if multiple objects are detected in the Field of View.

moment0(is_originalsize=False)

Moment-0 (integrated-flux) map.

The moment-0 map is the flux map integrated along the velocity axis. The default computed area is the one defined by Cube.cutout().

Parameters:

is_originalsize (bool, optional) – If False, compute the moment-0 map using the cutout region. If True, using the original-size data. Defaults to False.

Returns:

Two-dimensional moment-0 map.

Return type:

np.ndarray

Examples

>>> mom0 = cube.moment0()
rms_moment0(is_originalsize=False)

RMS noise of the moment 0 map.

RMS noise is computed using the region outside the cutout region, where the object is located.

Parameters:

is_originalsize (bool, optional) – If False, the moment-0 map is computed using the cutout region. If True, using the original- size data. Defaults to False.

Returns:

rms of the moment-0 map.

Return type:

float

pixmoment1(thresh=0.0)

Moment-1 (velocity) map.

Parameters:

  • thresh (float, optional) – Threshold of the pixel values on the moment-

  • threshold (0 map. In the pixels below this) –

  • inserted. (np.nan is) –

  • 0.0. (Defaults to) –

Returns:

Two-dimensional moment-1 map.

Return type:

np.ndarray

Examples

To output pixels whose moment-0 values are two times higher than the rms noise of the moment-0 map.

>>> mom1 = cube.pixmoment1(thresh=2 * cube.rms_moment0())

Note

The units of the moment-1 map is pixel. You may change the units by multiplying the results by the velocity-bin width.

pixmoment2(thresh=0.0)

Moment-2 (velocity-dispersion) map.

Parameters:

  • thresh (float, optional) – Threshold of the pixel values on the moment-

  • threshold (0 map. In the pixels below this) –

  • inserted. (np.nan is) –

  • 0.0. (Defaults to) –

Returns:

Two-dimensional moment-2 map.

Return type:

np.ndarray

Examples

To output pixels whose moment-0 values are two times higher than the rms noise of the moment-0 map.

>>> mom2 = cube.pixmoment2(thresh=2 * cube.rms_moment0())

Note

The units of the moment-2 map is pixel. You may change the units by multiplying the results by the velocity-bin width.

noisy(rms, convolve=None, seed=None, is_originalsize=False, uvcoverage=None, rms_of_standardnoise=None)

Create a noisy mock data cube.

The noisy cube is created by adding noise to the contained 3D data cube. This means that convolve should be the same as applied to the contained data cube. This method is useful to perturb the data cube for the Monte Carlo estiamtes of fitting errors.

Parameters:

  • rms (Union[float, np.ndarray]) – RMS of the added noise cube. The rms is computed at each pixel (channel) along the velocity axis.

  • convolve (Optional[Callable], optional) – Convolution function. Defaults to None.

  • seed (Optional[int], optional) – Random seed. Defaults to None.

  • is_originalsize (bool, optional) – If False, the size of the noisy cube the same as the cutout imageplane. If True, the cube is the original size. Defaults to False.

  • uvcoverage (Optional[np.ndarray], optional) – Mask on the uv plane. The pixels with False are set to 0.0. Defaults to None.

  • rms_of_standardnoise (ndarray | None) –

static rfft2(data, zero_padding=False)

Wrapper of misc.rfft2.

This method add the new argument zero_padding for observed data.

Parameters:

  • data (np.ndarray) – Data cube on the image plane.

  • zero_padding (bool, optional) – If True, zero-padding the pixels with None. Defaults to False.

Returns:

Fourier-transformed data cube on the uv plane.

Return type:

np.ndarray

Examples

>>> uv = cube.rfft2(image, zero_padding=True)
static create_noise(rms, shape, convolve=None, seed=None, uvcoverage=None, rms_of_standardnoise=None)

Create a noise cube.

Parameters:

  • rms (Union[float, np.ndarray]) – RMS noise of the cube.

  • shape (tuple[int, ...]) – Shape of the cube.

  • convolve (Optional[Callable], optional) – Convolution function. Defaults to None.

  • seed (Optional[int], optional) – Random seed. Defaults to None.

  • uvcoverage (Optional[np.ndarray], optional) – Mask on the uv plane. Defaults to None.

  • rms_of_standardnoise (ndarray | None) –

Returns:

Noise cube.

Return type:

np.ndarray

Examples

>>> noise = cube.create_noise(rms, shape, func_convlution)
class tokult.DataCube(imageplane, header=None, xlim=None, ylim=None, vlim=None)

Bases: Cube

Cube class to contain an observed datacube.

Parameters:

  • imageplane (np.ndarray) –

  • header (Optional[fits.Header]) –

  • xlim (Optional[tuple[int, int]]) –

  • ylim (Optional[tuple[int, int]]) –

  • vlim (Optional[tuple[int, int]]) –

perturbed(convolve=None, seed=None, is_originalsize=False, uvcoverage=None, rms_of_standardnoise=None)

Perturb the data cube with the same noise level and return it.

This method is useful to perturb the data cube for the Monte Carlo estiamtes of fitting errors.

Parameters:

  • convolve (Optional[Callable], optional) – Convolution function. Defaults to None.

  • seed (Optional[int], optional) – Random seed. Defaults to None.

  • is_originalsize (bool, optional) – If False, the output is the perturbed imagepalne. If True, the perturbed original Defaults to False.

  • uvcoverage (Optional[np.ndarray], optional) – Mask on the uv plane. Defaults to None.

  • rms_of_standardnoise (ndarray | None) –

Returns:

Perturbed data cube.

Return type:

np.ndarray

Examples

>>> cube_perturbed = datacube.perturbed(convolve=func_fullconvolve)
classmethod create(data_or_fname, header=None, index_hdul=0)

Constructer of DataCube.

Parameters:

  • data_or_fname (Union[np.ndarray, str]) – Data array or fits file name.

  • header (Optional[fits.Header], optional) – Header of the fits file, necessary if data_or_fname is a data array. Defaults to None.

  • index_hdul (int, optional) – Index of fits extensions of the fits file. Defaults to 0.

Returns:

Data cube.

Return type:

DataCube

Examples

>>> datacube = DataCube.create('data.fits')

Note

When the file name is give, the loaded data is squeezed; that is, the axis with zero size is dropped. Specifically, the polarization axis of the ALMA fits data may be dropped.

static loadfits(fname, index_hdul=0)

Read a data cube from a fits file.

Parameters:

  • fname (str) – Fits file name.

  • index_hdul (int, optional) – Index of fits extensions of the fits file. Defaults to 0.

Returns:

Tuple of the data and the fits header.

Return type:

tuple[np.ndarray, fits.Header]

Note

When the file name is give, the loaded data is squeezed; that is, the axis with zero size is dropped. Specifically, the polarization axis of the ALMA fits data may be dropped.

class tokult.ModelCube(imageplane, raw=None, xlim=None, ylim=None, vlim=None)

Bases: Cube

Cube class to contain a modeled datacube.

This class is especially for the best-fit model cube.

Parameters:

  • imageplane (np.ndarray) –

  • raw (Optional[np.ndarray]) –

  • xlim (Optional[tuple[int, int]]) –

  • ylim (Optional[tuple[int, int]]) –

  • vlim (Optional[tuple[int, int]]) –

classmethod create(params, datacube, lensing=None, convolve=None, create_interpolate_lensing=None, upsampling_rate=(1, 1, 1))

Constructer of ModelCube.

Parameters:

  • params (tuple[float, ...]) – Input parameters.

  • datacube (DataCube) – Data cube. The size of the model cube is based on this data cube.

  • lensing (Optional[Callable], optional) – Lensing function. Defaults to None.

  • convolve (Optional[Callable], optional) – Convolving function. Defaults to None.

  • create_interpolate_lensing (Callable | None) –

  • upsampling_rate (tuple[int, ...]) –

Returns:

Model cube.

Return type:

ModelCube

Examples

>>> model = ModelCube.create(params, tok.datacube,
                             lensing=tok.gravlens.lensing,
                             convolve=tok.dirtybeam.fullconvolve)
to_mockcube(rms, convolve=None, seed=None, is_originalsize=False, uvcoverage=None)

Convert to and output noisy mock cube.

Parameters:

  • rms (Union[float, np.ndarray]) – RMS noise added to the model cube, after convolution.

  • convolve (Optional[Callable], optional) – Convolution function. This convolve both raw model cube and noise. Defaults to None.

  • seed (Optional[int], optional) – Random seed. Defaults to None.

  • is_originalsize (bool, optional) – If False, the output mock cube is the same size as imageplane. If True, the size is the same as original. Defaults to False.

  • uvcoverage (Optional[np.ndarray], optional) – Mask on the uv plane. Defaults to None.

Returns:

Mock data cube.

Return type:

np.ndarray

Examples

>>> mock = modelcube.to_mockcube(
               tok.datacube.rms(),
               tok.dirtybeam.fullconvolve,
               is_original=True)
class tokult.DirtyBeam(beam, header=None)

Bases: object

Contains dirtybeam, i.e., Point Spread Functions (PSF) of Cube.

Contained data is dirtybeam images as a function of frequency.

Parameters:

  • beam (np.ndarray) –

  • header (Optional[fits.Header]) –

classmethod create(data_or_fname, header=None, index_hdul=0)

Constructer of DirtyBeam.

Parameters:

  • data_or_fname (Union[np.ndarray, str]) – Data array or fits file name.

  • header (Optional[fits.Header], optional) – Header of the fits file. Defaults to None.

  • index_hdul (int, optional) – Index of fits extensions of the fits file. Defaults to 0.

Returns:

instance of DirtyBeam.

Return type:

DirtyBeam

convolve(image)

Convolve imageplane with dirtybeam (psf) in two dimension.

Perform two-dimensional convolution at each pixel (channel) along the velocity axis.

Parameters:

image (np.ndarray) – Image to be convolved. Note that the size must be the same as the attribute imageplane.

Returns:

2D-convolved cube.

Return type:

np.ndarray

Examples

>>> convolved_image = dirtybeam.convole(image)
fullconvolve(image, uvcoverage=None, is_noise=False)

Convolve original with dirtybeam (psf) in two dimension.

Difference between convolve() and fullconvolve() is the size of the input image. This method fullconvolve treat the image with the same size as the dirtybeam.original.

Parameters:

  • image (np.ndarray) – Image to be convolved. Note that the size must be the same as the attribute original.

  • uvcoverage (Optional[np.ndarray], optional) – Mask on the uv plane. Defaults to None.

  • is_noise (bool, optional) – True if image is data. False if noise. Defaults to False.

Returns:

2D-convolved cube.

Return type:

np.ndarray

Examples

>>> convolved_image = dirtybeam.fullconvole(tok.modelcube.raw)

How to create convolved noise.

>>> rng = numpy.random.default_rng()
>>> noise = rng.standard_normal(size=shape)
>>> noise = dirtybeam.fullconvolve(
                noise, uvcoverage=uvcoverage, is_noise=True)
cutout(xlim, ylim, vlim)

Cutout a cubic region from the dirty beam cube.

Parameters:

  • xlim (Union[tuple[int, int], slice]) – The limit of the x-axis.

  • ylim (Union[tuple[int, int], slice]) – The limit of the y-axis.

  • vlim (Union[tuple[int, int], slice]) – The limit of the v-axis.

Return type:

None

cutout_to_match_with(cube)

Cutout a region with the same size of the input cube.

Parameters:

cube (DataCube) – Datacube. The size of cube.original must be the same as the dirtybeam.original. This method makes the size of the dirtybeam.imageplane the same as cube.imageplane.

Return type:

None

static loadfits(fname, index_hdul=0)

Read the dirty beam from a fits file.

Parameters:

  • fname (str) – Fits file name.

  • index_hdul (int, optional) – Index of fits extensions of the fits file. Defaults to 0.

Returns:

Tuple of the data and the fits header.

Return type:

tuple[np.ndarray, fits.Header]

Caution

The data shape of DirtyBeam must be the same as the Datacube. This requirement is naturaly satisfied if the input dirty-beam and the image-cube fits files are simulationsly created with CASA.

class tokult.GravLens(x_arcsec_deflect, y_arcsec_deflect, header, z_source=None, z_lens=None, z_assumed=None)

Bases: object

Deal with gravitational lensing effects based on a given lens models.

Contents are lensing parameters depending on positions.

Parameters:

  • x_arcsec_deflect (np.ndarray) –

  • y_arcsec_deflect (np.ndarray) –

  • header (fits.Header) –

  • z_source (Optional[float]) –

  • z_lens (Optional[float]) –

  • z_assumed (Optional[float]) –

classmethod create(*, data_or_fname_xy_arcsec_deflect=None, data_or_fname_xy_pixel_deflect=None, data_or_fname_psi_arcsec=None, header=None, index_hdul=0, z_source=None, z_lens=None, z_assumed=inf)

Constructer of GravLens.

Either of the first three arguments are required to construct GravLens. If more thean one among the three are given, the earier argument take a priority (i.e., xy_arcsec_deflect > xy_pixel_deflect > psi_arcsec).

Parameters:

  • (Optional[Union[tuple[np.ndarray (data_or_fname_xy_arcsec_deflect) – tuple[str, …]]]): Tuple of the data arrays or fits file names of lensing parmeters, x-arcsec-deflect and y-arcsec-deflect. Defaults to None.

  • ...] – tuple[str, …]]]): Tuple of the data arrays or fits file names of lensing parmeters, x-arcsec-deflect and y-arcsec-deflect. Defaults to None.

  • data_or_fname_xy_arcsec_deflect (tuple[numpy.ndarray, ...] | tuple[str, ...] | None) –

  • data_or_fname_xy_pixel_deflect (tuple[numpy.ndarray, ...] | tuple[str, ...] | None) –

  • data_or_fname_psi_arcsec (ndarray | str | None) –

  • header (Header | None) –

  • index_hdul (int) –

  • z_source (float | None) –

  • z_lens (float | None) –

  • z_assumed (float) –

Return type:

GravLens

:paramtuple[str, …]]]): Tuple of the data arrays or fits file names of

lensing parmeters, x-arcsec-deflect and y-arcsec-deflect. Defaults to None.

Parameters:

  • (Optional[Union[tuple[np.ndarray (data_or_fname_xy_pixel_deflect) – tuple[str, …]]]): Tuple of the data arrays or fits file names of lensing parmeters, x-pixel-deflect and y-pixel-deflect. Defaults to None.

  • ...] – tuple[str, …]]]): Tuple of the data arrays or fits file names of lensing parmeters, x-pixel-deflect and y-pixel-deflect. Defaults to None.

  • data_or_fname_xy_arcsec_deflect (tuple[numpy.ndarray, ...] | tuple[str, ...] | None) –

  • data_or_fname_xy_pixel_deflect (tuple[numpy.ndarray, ...] | tuple[str, ...] | None) –

  • data_or_fname_psi_arcsec (ndarray | str | None) –

  • header (Header | None) –

  • index_hdul (int) –

  • z_source (float | None) –

  • z_lens (float | None) –

  • z_assumed (float) –

Return type:

GravLens

:paramtuple[str, …]]]): Tuple of the data arrays or fits file names of

lensing parmeters, x-pixel-deflect and y-pixel-deflect. Defaults to None.

Parameters:

  • data_or_fname_psi_arcsec (Optional[Union[np.ndarray, str]]) – Data array or fits file name of a lensing parmeter, psi. Note that this method compute the gradient of psi to obtain the deflection angles, so that significantly strong gravitational lensing might not be traced by psi. Defaults to None.

  • header (Optional[fits.Header], optional) – Header of the fits file. This method assumes that lensing parameter maps, x-arcsec-deflect and y-arcsec-deflect, have the same size and coordinates. Defaults to None.

  • index_hdul (int, optional) – Index of fits extensions of the fits file. Defaults to 0.

  • z_source (Optional[float], optional) – The source (galaxy) redshift. Defaults to None.

  • z_lens (Optional[float], optional) – The lens (cluster) redshift. Defaults to None.

  • z_assumed (float, optional) – The redshift assumed in the gravitational parameters. If D_s / D_L = 1, the value should be infinite (np.inf). Defaults to np.inf.

  • data_or_fname_xy_arcsec_deflect (tuple[numpy.ndarray, ...] | tuple[str, ...] | None) –

  • data_or_fname_xy_pixel_deflect (tuple[numpy.ndarray, ...] | tuple[str, ...] | None) –

Returns:

Instance of GravLens.

Return type:

GravLens

lensing(xgrid, ygrid)

Convert coordinates (x, y) from the image plane to the source plane.

Parameters:

  • xgrid (np.ndarray) – Array of the x coordinates on the image plane.

  • ygrid (np.ndarray) – Array of the y coordinates on the image plane.

Returns:

Tuple of coordinates on the source plane.

Return type:

tuple[np.ndarray, …]

Examples

>>> xx_source, yy_source = lensing(xx_image, yy_image)
create_interpolate_lensing(xgrid, ygrid)

Retrun a LensingInterpolate instance.

Parameters:

  • xgrid (np.ndarray) – 2D array of the x coordinate.

  • ygrid (np.ndarray) – 2D array of the y coordinate.

Returns:

[description]

Return type:

LensingInterpolate

Examples

>>> lensing_interp = gl.create_interpolate_lensing(xgrid, ygrid)
>>> x0_s, y0_s = lensing_interp(x0_i, y0_i)
class LensingInterpolate(xx, yy, x_pixel_deflect, y_pixel_deflect)

Bases: object

Interpolate lensing effects to a data point.

This class method is implemented to convert the center of the model disk to the image plane.

Parameters:

  • xx (np.ndarray) –

  • yy (np.ndarray) –

  • x_pixel_deflect (np.ndarray) –

  • y_pixel_deflect (np.ndarray) –

match_wcs_with(cube)

Match the world coordinate system with the input data cube.

Use the wcs of cube.imageplane; therefore, the matched lensing parameter map become smaller than the original map.

Parameters:

cube (DataCube) – DataCube including the header information. This method uses the wcs included in the header of the data cube and the GravLens instance.

Return type:

None

Examples

>>> gravlens.match_wcs_with(datacube)
use_redshifts(z_source, z_lens, z_assumed=inf)

Correct the lensing parameters using the redshifts.

Parameters:

  • z_source (float) – The source (galaxy) redshift.

  • z_lens (float) – The lens (cluster) redshift.

  • z_assumed (float, optional) – The redshift assumed in the gravitational parameters. If D_s / D_L = 1, the value should be infinite (np.inf). Defaults to np.inf.

Return type:

None

reset_redshifts()

Reset the redshift infomation.

Return type:

None

compute_deflection_angles()

Compute deflection angles in arcsec and pixels using redshifts

static convert_xy_arcsec_to_pixel(x_arcsec, y_arcsec, header)

Convert deflection angles of x and y in arcsec to in pixels.

Use the internal header “CDELT” for the conversion.

Parameters:

  • x_arcsec (np.ndarray) – Deflection angle of x given in arcsec.

  • y_arcsec (np.ndarray) – Deflection angle of y given in arcsec.

  • header (fits.Header) – Header including units information

Returns:

Tuple of the deflection angles of x

and y in pixels.

Return type:

tuple[np.ndarray, np.ndarray]

Examples

>>> x_pix, y_pix = gl.convert_xy_arcsec_to_pixel(x_arcsec, y_arcsec)
Nonte:

Assumes that the units of “CDELT1” and “CDELT2” are degree.

static convert_xy_pixel_to_arcsec(x_pixel, y_pixel, header)

Convert deflection angles of x and y in pixel to in arcsec.

Use the internal header “CDELT” for the conversion.

Parameters:

  • x_pixel (np.ndarray) – Deflection angle of x given in pixel.

  • y_pixel (np.ndarray) – Deflection angle of y given in pixel.

  • header (fits.Header) – Header including units information.

Returns:

Tuple of the deflection angles of x

and y in arcsec.

Return type:

tuple[np.ndarray, np.ndarray]

Examples

>>> x_arcsec, y_arcsec = gl.convert_xy_pixel_to_arcsec(x_pix, y_pix, header)
Nonte:

Assumes that the units of “CDELT1” and “CDELT2” are degree.

static gradient(psi, header)

Compute gradient of 2D image.

This method is used to compute deflection angles from the deflection potential psi.

Parameters:

  • psi (np.ndarray) – 2D image of the deflection potential. The units are given in arcsec, meaning that differentiation of psi with respect to the angle in arcsec gives the deflection angles in arcsec.

  • header (fits.Header) – Header including units information.

Returns:

Tuple of the deflection angles of y

and x. Note that the order is (y, x).

Return type:

tuple[np.ndarray, np.ndarray]

Examples

>>> y_arcsec, x_arcsec = gl.gradient(psi, header=header)
Nonte:

Assumes that the units of “CDELT1” and “CDELT2” are degree.

static get_angular_distance_ratio(z_source, z_lens, z_assumed=inf)

Angular distance ratio of D_LS to D_S, normalized by assumed D_LS/D_S.

Lensing parameter maps are distributed using some D_LS/D_S at specific redshifts. This method provides a new factor that can be multiplied by the lensing parameter maps to correct the redshift dependency.

Parameters:

  • z_source (float) – The source (galaxy) redshift.

  • z_lens (float) – The lens (cluster) redshift.

  • z_assumed (float, optional) – The redshift assumed in the gravitational parameters. If D_s / D_L = 1, the value should be infinite (np.inf). Defaults to np.inf.

Returns:

Angular distance ratio, D_LS/D_S

Return type:

float

Examples

>>> distance_ratio = gravlens.get_angular_distance_ratio(6.2, 0.9)
>>> x_deflect_new = x_deflect_old * distance_ratio
static loadfits(fname_x_deflect, fname_y_deflect, index_hdul=0)

Read gravlens from fits file.

Parameters:

  • fname_x_deflect (str) – Fits file name of the deflect map of x.

  • fname_y_deflect (str) – Fits file name of the deflect map of y.

  • index_hdul (int, optional) – Index of fits extensions of the fits file. Assumes that all the fits files include the lensing parameter maps at the same extension index. Defaults to 0.

Returns:

Tuple of three objects;

deflection angles (x and y) and header.

Return type:

tuple[np.ndarray, np.ndarray, fits.Header]

class tokult.InputParams(x0_dyn, y0_dyn, PA_dyn, inclination_dyn, radius_dyn, velocity_sys, mass_dyn, brightness_center, velocity_dispersion, radius_emi, x0_emi, y0_emi, PA_emi, inclination_emi)

Bases: NamedTuple

Input parameters for construct_model_at_imageplane.

Parameters:

  • x0_dyn (float) –

  • y0_dyn (float) –

  • PA_dyn (float) –

  • inclination_dyn (float) –

  • radius_dyn (float) –

  • velocity_sys (float) –

  • mass_dyn (float) –

  • brightness_center (float) –

  • velocity_dispersion (float) –

  • radius_emi (float) –

  • x0_emi (float) –

  • y0_emi (float) –

  • PA_emi (float) –

  • inclination_emi (float) –

x0_dyn: float

the coordinate on x-axis

y0_dyn: float

Alias for field number 1

PA_dyn: float

Alias for field number 2

inclination_dyn: float

Alias for field number 3

radius_dyn: float

Alias for field number 4

velocity_sys: float

Alias for field number 5

mass_dyn: float

Alias for field number 6

brightness_center: float

Alias for field number 7

velocity_dispersion: float

Alias for field number 8

radius_emi: float

Alias for field number 9

x0_emi: float

Alias for field number 10

y0_emi: float

Alias for field number 11

PA_emi: float

Alias for field number 12

inclination_emi: float

Alias for field number 13

to_units(header, redshift=0.0)

Return input parameters with units.

Parameters:

  • header (Header) –

  • redshift (float) –

Return type:

FitParamsWithUnits

class tokult.FitParamsWithUnits(x0_dyn, y0_dyn, PA_dyn, inclination_dyn, radius_dyn, velocity_sys, mass_dyn, brightness_center, velocity_dispersion, radius_emi, x0_emi, y0_emi, PA_emi, inclination_emi, header=None, z=0.0)

Bases: object

Fitting parameters with units.

Parameters:

  • x0_dyn (u.Quantity) –

  • y0_dyn (u.Quantities) –

  • PA_dyn (u.Quantities) –

  • inclination_dyn (u.Quantities) –

  • radius_dyn (u.Quantities) –

  • velocity_sys (u.Quantities) –

  • mass_dyn (u.Quantities) –

  • brightness_center (u.Quantities) –

  • velocity_dispersion (u.Quantities) –

  • radius_emi (u.Quantities) –

  • x0_emi (u.Quantities) –

  • y0_emi (u.Quantities) –

  • PA_emi (u.Quantities) –

  • inclination_emi (u.Quantities) –

  • header (Optional[fits.Header]) –

  • z (float) –

x0_dyn: u.Quantity
y0_dyn: u.Quantities
PA_dyn: u.Quantities
inclination_dyn: u.Quantities
radius_dyn: u.Quantities
velocity_sys: u.Quantities
mass_dyn: u.Quantities
brightness_center: u.Quantities
velocity_dispersion: u.Quantities
radius_emi: u.Quantities
x0_emi: u.Quantities
y0_emi: u.Quantities
PA_emi: u.Quantities
inclination_emi: u.Quantities
header: fits.Header | None = None
z: float = 0.0
wcs: WCS | None
pixelscale: u.Equivalency | None
freq_rest: u.Quantities | None
vpixelscale: u.Equivalency | None
diskmassscale: u.Equivalency | None
to_physicalscale()

Convert values to physicalscales.

Return type:

None

vmax()

Maximum rotation velcoity.

classmethod from_inputparams(inputparams, header=None, z=0.0)

Constructer from InputParams

Parameters:

  • inputparams (InputParams | InputParamsArray) –

  • header (Header | None) –

  • z (float) –

Return type:

FitParamsWithUnits

tokult.get_bound_params(x0_dyn=(-inf, inf), y0_dyn=(-inf, inf), PA_dyn=(0.0, 6.283185307179586), inclination_dyn=(0.0, 1.5707963267948966), radius_dyn=(0.0, inf), velocity_sys=(-inf, inf), mass_dyn=(-inf, inf), brightness_center=(0.0, inf), velocity_dispersion=(0.0, inf), radius_emi=(0.0, inf), x0_emi=(-inf, inf), y0_emi=(-inf, inf), PA_emi=(0.0, 6.283185307179586), inclination_emi=(0.0, 1.5707963267948966))

Return bound parameters.

Parameters:

  • x0_dyn (tuple[float, float]) –

  • y0_dyn (tuple[float, float]) –

  • PA_dyn (tuple[float, float]) –

  • inclination_dyn (tuple[float, float]) –

  • radius_dyn (tuple[float, float]) –

  • velocity_sys (tuple[float, float]) –

  • mass_dyn (tuple[float, float]) –

  • brightness_center (tuple[float, float]) –

  • velocity_dispersion (tuple[float, float]) –

  • radius_emi (tuple[float, float]) –

  • x0_emi (tuple[float, float]) –

  • y0_emi (tuple[float, float]) –

  • PA_emi (tuple[float, float]) –

  • inclination_emi (tuple[float, float]) –

Return type:

tuple[tokult.fitting.InputParams, tokult.fitting.InputParams]

tokult.common module

Common utilities

tokult.fitting module

Modules of fitting functions

class tokult.fitting.InputParams(x0_dyn, y0_dyn, PA_dyn, inclination_dyn, radius_dyn, velocity_sys, mass_dyn, brightness_center, velocity_dispersion, radius_emi, x0_emi, y0_emi, PA_emi, inclination_emi)

Bases: NamedTuple

Input parameters for construct_model_at_imageplane.

Parameters:

  • x0_dyn (float) –

  • y0_dyn (float) –

  • PA_dyn (float) –

  • inclination_dyn (float) –

  • radius_dyn (float) –

  • velocity_sys (float) –

  • mass_dyn (float) –

  • brightness_center (float) –

  • velocity_dispersion (float) –

  • radius_emi (float) –

  • x0_emi (float) –

  • y0_emi (float) –

  • PA_emi (float) –

  • inclination_emi (float) –

x0_dyn: float

the coordinate on x-axis

y0_dyn: float

Alias for field number 1

PA_dyn: float

Alias for field number 2

inclination_dyn: float

Alias for field number 3

radius_dyn: float

Alias for field number 4

velocity_sys: float

Alias for field number 5

mass_dyn: float

Alias for field number 6

brightness_center: float

Alias for field number 7

velocity_dispersion: float

Alias for field number 8

radius_emi: float

Alias for field number 9

x0_emi: float

Alias for field number 10

y0_emi: float

Alias for field number 11

PA_emi: float

Alias for field number 12

inclination_emi: float

Alias for field number 13

to_units(header, redshift=0.0)

Return input parameters with units.

Parameters:

  • header (Header) –

  • redshift (float) –

Return type:

FitParamsWithUnits

class tokult.fitting.FitParamsWithUnits(x0_dyn, y0_dyn, PA_dyn, inclination_dyn, radius_dyn, velocity_sys, mass_dyn, brightness_center, velocity_dispersion, radius_emi, x0_emi, y0_emi, PA_emi, inclination_emi, header=None, z=0.0)

Bases: object

Fitting parameters with units.

Parameters:

  • x0_dyn (u.Quantity) –

  • y0_dyn (u.Quantities) –

  • PA_dyn (u.Quantities) –

  • inclination_dyn (u.Quantities) –

  • radius_dyn (u.Quantities) –

  • velocity_sys (u.Quantities) –

  • mass_dyn (u.Quantities) –

  • brightness_center (u.Quantities) –

  • velocity_dispersion (u.Quantities) –

  • radius_emi (u.Quantities) –

  • x0_emi (u.Quantities) –

  • y0_emi (u.Quantities) –

  • PA_emi (u.Quantities) –

  • inclination_emi (u.Quantities) –

  • header (Optional[fits.Header]) –

  • z (float) –

x0_dyn: u.Quantity
y0_dyn: u.Quantities
PA_dyn: u.Quantities
inclination_dyn: u.Quantities
radius_dyn: u.Quantities
velocity_sys: u.Quantities
mass_dyn: u.Quantities
brightness_center: u.Quantities
velocity_dispersion: u.Quantities
radius_emi: u.Quantities
x0_emi: u.Quantities
y0_emi: u.Quantities
PA_emi: u.Quantities
inclination_emi: u.Quantities
header: fits.Header | None = None
z: float = 0.0
wcs: WCS | None
pixelscale: u.Equivalency | None
freq_rest: u.Quantities | None
vpixelscale: u.Equivalency | None
diskmassscale: u.Equivalency | None
to_physicalscale()

Convert values to physicalscales.

Return type:

None

vmax()

Maximum rotation velcoity.

classmethod from_inputparams(inputparams, header=None, z=0.0)

Constructer from InputParams

Parameters:

  • inputparams (InputParams | InputParamsArray) –

  • header (Header | None) –

  • z (float) –

Return type:

FitParamsWithUnits

tokult.fitting.get_bound_params(x0_dyn=(-inf, inf), y0_dyn=(-inf, inf), PA_dyn=(0.0, 6.283185307179586), inclination_dyn=(0.0, 1.5707963267948966), radius_dyn=(0.0, inf), velocity_sys=(-inf, inf), mass_dyn=(-inf, inf), brightness_center=(0.0, inf), velocity_dispersion=(0.0, inf), radius_emi=(0.0, inf), x0_emi=(-inf, inf), y0_emi=(-inf, inf), PA_emi=(0.0, 6.283185307179586), inclination_emi=(0.0, 1.5707963267948966))

Return bound parameters.

Parameters:

  • x0_dyn (tuple[float, float]) –

  • y0_dyn (tuple[float, float]) –

  • PA_dyn (tuple[float, float]) –

  • inclination_dyn (tuple[float, float]) –

  • radius_dyn (tuple[float, float]) –

  • velocity_sys (tuple[float, float]) –

  • mass_dyn (tuple[float, float]) –

  • brightness_center (tuple[float, float]) –

  • velocity_dispersion (tuple[float, float]) –

  • radius_emi (tuple[float, float]) –

  • x0_emi (tuple[float, float]) –

  • y0_emi (tuple[float, float]) –

  • PA_emi (tuple[float, float]) –

  • inclination_emi (tuple[float, float]) –

Return type:

tuple[tokult.fitting.InputParams, tokult.fitting.InputParams]

tokult.function module

Modules of functions

tokult.function.gaussian(x, center, sigma, area)

Gaussian function.

Parameters:

  • x (ndarray) –

  • center (ArrayLike) –

  • sigma (float) –

  • area (ArrayLike) –

Return type:

ndarray

tokult.function.reciprocal_exp(r, norm, rnorm)

Exponential function

Parameters:

  • r (ndarray) –

  • norm (float) –

  • rnorm (float) –

Return type:

ndarray

tokult.function.freeman_disk(r, phi, mass_dyn, rnorm, incl)

Freeman disk function

Parameters:

  • r (ndarray) –

  • phi (ndarray) –

  • mass_dyn (float) –

  • rnorm (float) –

  • incl (float) –

Return type:

ndarray

tokult.function.maximum_rotation_velocity(mass_dyn, rnorm)

Maximum rotation velocity of Freeman disk function

Parameters:

  • mass_dyn (Quantity | ndarray | float) –

  • rnorm (Quantity | ndarray | float) –

Return type:

Quantity | ndarray | float

tokult.misc module

miscellaneous functions

tokult.casa module

Modules to analyze measurement sets. These modules are under construction.

tokult.casa_dummy module

Dummy CASA modules

tokult.core module

Core modules of tokult.

class tokult.core.Tokult(datacube, dirtybeam=None, gravlens=None)

Bases: object

Interface of Tokult.

Users specify data to launch an instance object and start fitting through the instance. This class contains observed data, psf, and lensing parameters, along with useful functions to manipulate data and models.

Parameters:

  • datacube (DataCube) –

  • dirtybeam (Optional[DirtyBeam], optional) – Defaults to None.

  • gravlens (Optional[GravLens], optional) – Defaults to None.

Examples

>>> import tokult
>>> tok = tokult.Tokult.launch('data.fits', 'psf.fits',
                             ('x-arcsec-deflect.fits', 'y-arcsec-deflect.fits'))
classmethod launch(data, beam=None, gravlens=None, header_data=None, header_beam=None, header_gravlens=None, index_data=0, index_beam=0, index_gravlens=0)

Constructer of Tokult.

Construct an instance easier than to use the init constructer.

Parameters:

  • data (Union[np.ndarray, str]) – Observed data. The format is a data array or a fits file name.

  • beam (Union[np.ndarray, str, None], optional) – Dirty beam or point spread function (PSF). The format is a data array or a fits file name. Defaults to None.

  • gravlens (Union[tuple[np.ndarray, ...], tuple[str, ...]], None, optional) – Gravitational lensing parameters. The format is a tuple containing the three data array or fits file names of parameters: x_arcsec_deflect and y_arcsec_deflect. Defaults to None.

  • header_data (Optional[fits.Header], optional) – Header of data. Defaults to None. This is necessary when the data is not given in a fits file.

  • header_beam (Optional[fits.Header], optional) – Header of psf. Defaults to None. This is necessary when beam is not given in a fits file.

  • header_gravlens (Optional[fits.Header], optional) – Header of gravlens. Defaults to None. This is necessary when gravlens is not given in fits files.

  • index_data (int, optional) – Index of fits extensions of the data fits file. Defaults to 0.

  • index_beam (int, optional) – Index of fits extensions of the beam fits file. Defaults to 0.

  • index_gravlens (int, optional) – Index of fits extensions of the lens fits files. Defaults to 0.

Return type:

Tokult

Examples

>>> tok = tokult.Tokult.launch(
             'data.fits', 'psf.fits',
             (x_arcsec_deflect.fits', y_arcsec_deflect.fits'))
imagefit(init, bound=None, fix=None, optimization='mc', niter=1, nperturb=1000, nwalkers=64, nsteps=5000, pool=None, is_separate=False, mask_for_fit=None, uvcoverage=None, progressbar=False)

Fit a 3d model to the data cube on the image plane.

Parameters:

  • init (Sequence[float]) – Initial parameters of fitting.

  • bound (Optional[tuple[Sequence[float], Sequence[float]], optional) – Boundaries of parameters. Defaults to None. When None is given, the default parameter boundaries are used. The boundaries can be easily set using get_bound_params. Currently, in the mcmc method, only flat prior distributions are available through this argument.

  • fix (Optional[fitting.FixParams], optional) – Defaults to None.

  • optimization (str, optional) – Defaults to ‘mc’.

  • niter (int, optional) – Number of iterations of fitting, used in the least square method. Defaults to 1.

  • nperturb (int, optional) – Number of perturbations in the Monte Carlo method. Defaults to 1000.

  • nwalkers (int, optional) – Number of walkers, used in the MCMC method. Defaults to 64.

  • nsteps (int, optional) – Number of steps, used in the MCMC method. Defaults to 5000.

  • pool (Optional[Pool], optional) – multiprocessing.pool for a multi-process MCMC fitting. Defaults to None.

  • is_separate (bool, optional) – If True, parameters regarding kinematics and emission are separated; and thus fitting uses all the 14 parameters. If False, the parameters are the same and the number of free parameters are reduced. Defaults to False.

  • mask_for_fit (Optional[np.ndarray], optional) – Mask specifying pixels used for fitting. Defaults to None.

  • progressbar (bool, optional) – If True, a progress bar is shown. Defaults to False.

  • uvcoverage (ndarray | None) –

Returns:

Fitting results and related parameters.

Return type:

fitting.Solution

Examples

>>> sol = tok.imagefit(init, bound, optimization='mc')
uvfit(init, bound=None, fix=None, optimization='mcmc', niter=1, nwalkers=64, nsteps=5000, pool=None, is_separate=False, mask_for_fit=None, progressbar=False)

Fit a 3d model to the data cube on the uv plane.

Parameters:

  • init (Sequence[float]) – Initial parameters of fitting. a function to guess initial parameters: tokult.initialguess().

  • bound (Optional[tuple[Sequence[float], Sequence[float]], optional) – Boundaries of parameters. Defaults to None. When None is given, the default parameter boundaries are used. The boundaries can be easily set using get_bound_params. Currently, in the mcmc method, only flat prior distributions are available through this argument.

  • fix (Optional[fitting.FixParams], optional) – Fix parameters during fitting. See FixParams. Defaults to None.

  • optimization (str, optional) – Method to optimize the 3D model. - ‘ls’: least square method. - ‘mcmc’: Malcov Chain Monte Carlo method. Defaults to ‘mcmc’.

  • niter (int, optional) – Number of iterations of fitting, used in the least square method. Defaults to 1.

  • nperturb (int, optional) – Number of perturbations in the Monte Carlo method. Defaults to 1000.

  • nwalkers (int, optional) – Number of walkers, used in the MCMC method. Defaults to 64.

  • nsteps (int, optional) – Number of steps, used in the MCMC method. Defaults to 5000.

  • pool (Optional[Pool], optional) – multiprocessing.pool for a multi-process MCMC fitting. Defaults to None.

  • is_separate (bool, optional) – If True, parameters regarding kinematics and emission are separated; and thus fitting uses all the 14 parameters. If False, the parameters are the same and the number of free parameters are reduced. Defaults to False.

  • mask_for_fit (Optional[np.ndarray], optional) – Mask specifying pixels used for fitting. In uv fitting, specifying the uv-coverage is important, which is passed through this argument. Defaults to None.

  • progressbar (bool, optional) – If True, a progress bar is shown. Defaults to False.

Returns:

Fitting results and related parameters.

Return type:

fitting.Solution

Examples

>>> sol = tok.uvfit(init, bound, optimization='mcmc')

Note

The input parameters are the same as imagefit.

initialguess(is_separate=False)

Guess initial input parameters for fitting.

Fit tow-dimensional moment-0 (flux) map and moment-1 (velocity) map then Estimate input parameters from the 2-d fitting results.

Parameters:

is_separate (bool, optional) – If True, parameters regarding kinematics and emission are separated; and thus fitting uses all the 14 parameters. If False, the parameters are the same and the number of free parameters are reduced. Defaults to False.

Returns:

Best-guessed input parameters.

Return type:

fitting.InputParams

Examples

>>> init = tok.initialguess()

Note

Initial parameters are crucial for parameter fitting, especially in the least-square and Monte Carlo methods and being related with speed of convergence in the MCMC method.

use_region(xlim=None, ylim=None, vlim=None)

Use a region of datacube used for fitting.

Parameters:

  • xlim (Optional[tuple[int, int]], optional) – The limit of the x-axis. Defaults to None.

  • ylim (Optional[tuple[int, int]], optional) – The limit of the y-axis. Defaults to None.

  • vlim (Optional[tuple[int, int]], optional) – The limit of the v-axis. Defaults to None.

Return type:

None

Examples

>>> tok.use_region((32, 96), (32, 96), (5, 12))

Note

In uvfit, the v-axis limit must be specified smaller than original cube size, because uvfit estimates the noise level using the pixels outside vlim.

use_redshifts(z_source, z_lens, z_assumed=inf)

Set the redshifts of the source and the lens galaxies.

The redshifts are used to compute the gravitational lensing effects and to convert the parameters to the physical units.

Parameters:

  • z_source (float) – The source (galaxy) redshift.

  • z_lens (float) – The lens (cluster) redshift.

  • z_assumed (float, optional) – The redshift assumed in the gravitational parameters. If D_s / D_L = 1, the value should be infinite (np.inf). Defaults to np.inf.

Return type:

None

Examples

>>> tok.use_redshift(z_source=6.2, z_lens=0.9)
change_datacube(data_or_fname, header=None, index_hdul=0, xlim=None, ylim=None, vlim=None)

Change the variable datacube.

May be useful to change datacube of an instance.

Nonte:

This method should be used before use_region and use_redshift.

Parameters:

  • data_or_fname (ndarray | str) –

  • header (Header | None) –

  • index_hdul (int) –

  • xlim (tuple[int, int] | None) –

  • ylim (tuple[int, int] | None) –

  • vlim (tuple[int, int] | None) –

Return type:

None

change_dirtybeam(data_or_fname, header=None, index_hdul=0)

Change the variable dirtybeam.

May be useful to change dirtybeam of an instance.

Nonte:

This method should be used before use_region and use_redshift.

Parameters:

  • data_or_fname (ndarray | str) –

  • header (Header | None) –

  • index_hdul (int) –

Return type:

None

change_gravlens(*, data_or_fname_xy_arcsec_deflect=None, data_or_fname_xy_pixel_deflect=None, data_or_fname_psi_arcsec=None, header=None, index_hdul=0)

Change the variable gravlens.

May be useful to change gravlens of an instance.

Nonte:

This method should be used before use_region and use_redshift.

Parameters:

  • data_or_fname_xy_arcsec_deflect (tuple[numpy.ndarray, ...] | tuple[str, ...] | None) –

  • data_or_fname_xy_pixel_deflect (tuple[numpy.ndarray, ...] | tuple[str, ...] | None) –

  • data_or_fname_psi_arcsec (ndarray | str | None) –

  • header (Header | None) –

  • index_hdul (int) –

Return type:

None

construct_modelcube(params)

Construct modelcube from the input parameters.

Construct a 3D model and set it to an internal variable modelcube. If you want to use a model outside Tokult instances, please use ModelCube.create() instead.

Parameters:

params (tuple[float, ...]) – Input parameters.

Return type:

None

Examples

Change a part of the best-fit parameters and construct the model.

>>> params = sol.best._replace(PA_dyn=0.0)
>>> tok.construct_modelcube(params)

Note

This method needs the global parameters to be set already. You may need to fit the data once, before using this method.

calculate_normweight()

Calculate the normalization weight used in uvfit.

The obtained value is almost equal to sum-of-weight, but different by a factor of a few.

Returns:

The normalization weight

Return type:

float

class tokult.core.Cube(imageplane, header=None, xlim=None, ylim=None, vlim=None)

Bases: object

3D data cube.

Examples

>>>
Parameters:

  • imageplane (np.ndarray) –

  • header (Optional[fits.Header]) –

  • xlim (Optional[tuple[int, int]]) –

  • ylim (Optional[tuple[int, int]]) –

  • vlim (Optional[tuple[int, int]]) –

imageplane

Cutout 3D data cube on the image plane.

Type:

np.ndarray

uvplane

Cutout 3D data cube on the uv plane. This is the Fourier transformation of imageplane.

Type:

np.ndarray

original

Original-size, 3D data cube.

Type:

np.ndarray

header

Header of the fits data. Defaults to None.

Type:

Optional[fits.Header]

cutout(xlim=None, ylim=None, vlim=None)

Cutout 3D cube from original.

Parameters:

  • xlim (Optional[tuple[int, int]], optional) – The limit of the x-axis. Defaults to None.

  • ylim (Optional[tuple[int, int]], optional) – The limit of the y-axis. Defaults to None.

  • vlim (Optional[tuple[int, int]], optional) – The limit of the v-axis. Defaults to None.

Return type:

None

Examples

>>> cube.cutout((32, 96), (32, 96), (5, 12))
rms(is_originalsize=False)

Compute the rms noise of the data cube.

Compute the rms noise using pixels outside of the region used for imageplane, by assuming that the pixels are not affected by any objects and reflect pure noises.

Parameters:

  • is_originalsize (bool, optional) – If False, the computed rms noise is

  • True (limited at vlim of imageplane. If) –

  • is (the rms noise) –

  • False. (computed using the original-size data cube. Defaults to) –

Returns:

the one-dimensional array containing the rms noises at each pixel (channel) along the velocity axis.

Return type:

np.ndarray

Examples

>>> rms = cube.rms()

Note

This method may not return the correct rms if multiple objects are detected in the Field of View.

moment0(is_originalsize=False)

Moment-0 (integrated-flux) map.

The moment-0 map is the flux map integrated along the velocity axis. The default computed area is the one defined by Cube.cutout().

Parameters:

is_originalsize (bool, optional) – If False, compute the moment-0 map using the cutout region. If True, using the original-size data. Defaults to False.

Returns:

Two-dimensional moment-0 map.

Return type:

np.ndarray

Examples

>>> mom0 = cube.moment0()
rms_moment0(is_originalsize=False)

RMS noise of the moment 0 map.

RMS noise is computed using the region outside the cutout region, where the object is located.

Parameters:

is_originalsize (bool, optional) – If False, the moment-0 map is computed using the cutout region. If True, using the original- size data. Defaults to False.

Returns:

rms of the moment-0 map.

Return type:

float

pixmoment1(thresh=0.0)

Moment-1 (velocity) map.

Parameters:

  • thresh (float, optional) – Threshold of the pixel values on the moment-

  • threshold (0 map. In the pixels below this) –

  • inserted. (np.nan is) –

  • 0.0. (Defaults to) –

Returns:

Two-dimensional moment-1 map.

Return type:

np.ndarray

Examples

To output pixels whose moment-0 values are two times higher than the rms noise of the moment-0 map.

>>> mom1 = cube.pixmoment1(thresh=2 * cube.rms_moment0())

Note

The units of the moment-1 map is pixel. You may change the units by multiplying the results by the velocity-bin width.

pixmoment2(thresh=0.0)

Moment-2 (velocity-dispersion) map.

Parameters:

  • thresh (float, optional) – Threshold of the pixel values on the moment-

  • threshold (0 map. In the pixels below this) –

  • inserted. (np.nan is) –

  • 0.0. (Defaults to) –

Returns:

Two-dimensional moment-2 map.

Return type:

np.ndarray

Examples

To output pixels whose moment-0 values are two times higher than the rms noise of the moment-0 map.

>>> mom2 = cube.pixmoment2(thresh=2 * cube.rms_moment0())

Note

The units of the moment-2 map is pixel. You may change the units by multiplying the results by the velocity-bin width.

noisy(rms, convolve=None, seed=None, is_originalsize=False, uvcoverage=None, rms_of_standardnoise=None)

Create a noisy mock data cube.

The noisy cube is created by adding noise to the contained 3D data cube. This means that convolve should be the same as applied to the contained data cube. This method is useful to perturb the data cube for the Monte Carlo estiamtes of fitting errors.

Parameters:

  • rms (Union[float, np.ndarray]) – RMS of the added noise cube. The rms is computed at each pixel (channel) along the velocity axis.

  • convolve (Optional[Callable], optional) – Convolution function. Defaults to None.

  • seed (Optional[int], optional) – Random seed. Defaults to None.

  • is_originalsize (bool, optional) – If False, the size of the noisy cube the same as the cutout imageplane. If True, the cube is the original size. Defaults to False.

  • uvcoverage (Optional[np.ndarray], optional) – Mask on the uv plane. The pixels with False are set to 0.0. Defaults to None.

  • rms_of_standardnoise (ndarray | None) –

static rfft2(data, zero_padding=False)

Wrapper of misc.rfft2.

This method add the new argument zero_padding for observed data.

Parameters:

  • data (np.ndarray) – Data cube on the image plane.

  • zero_padding (bool, optional) – If True, zero-padding the pixels with None. Defaults to False.

Returns:

Fourier-transformed data cube on the uv plane.

Return type:

np.ndarray

Examples

>>> uv = cube.rfft2(image, zero_padding=True)
static create_noise(rms, shape, convolve=None, seed=None, uvcoverage=None, rms_of_standardnoise=None)

Create a noise cube.

Parameters:

  • rms (Union[float, np.ndarray]) – RMS noise of the cube.

  • shape (tuple[int, ...]) – Shape of the cube.

  • convolve (Optional[Callable], optional) – Convolution function. Defaults to None.

  • seed (Optional[int], optional) – Random seed. Defaults to None.

  • uvcoverage (Optional[np.ndarray], optional) – Mask on the uv plane. Defaults to None.

  • rms_of_standardnoise (ndarray | None) –

Returns:

Noise cube.

Return type:

np.ndarray

Examples

>>> noise = cube.create_noise(rms, shape, func_convlution)
class tokult.core.DataCube(imageplane, header=None, xlim=None, ylim=None, vlim=None)

Bases: Cube

Cube class to contain an observed datacube.

Parameters:

  • imageplane (np.ndarray) –

  • header (Optional[fits.Header]) –

  • xlim (Optional[tuple[int, int]]) –

  • ylim (Optional[tuple[int, int]]) –

  • vlim (Optional[tuple[int, int]]) –

perturbed(convolve=None, seed=None, is_originalsize=False, uvcoverage=None, rms_of_standardnoise=None)

Perturb the data cube with the same noise level and return it.

This method is useful to perturb the data cube for the Monte Carlo estiamtes of fitting errors.

Parameters:

  • convolve (Optional[Callable], optional) – Convolution function. Defaults to None.

  • seed (Optional[int], optional) – Random seed. Defaults to None.

  • is_originalsize (bool, optional) – If False, the output is the perturbed imagepalne. If True, the perturbed original Defaults to False.

  • uvcoverage (Optional[np.ndarray], optional) – Mask on the uv plane. Defaults to None.

  • rms_of_standardnoise (ndarray | None) –

Returns:

Perturbed data cube.

Return type:

np.ndarray

Examples

>>> cube_perturbed = datacube.perturbed(convolve=func_fullconvolve)
classmethod create(data_or_fname, header=None, index_hdul=0)

Constructer of DataCube.

Parameters:

  • data_or_fname (Union[np.ndarray, str]) – Data array or fits file name.

  • header (Optional[fits.Header], optional) – Header of the fits file, necessary if data_or_fname is a data array. Defaults to None.

  • index_hdul (int, optional) – Index of fits extensions of the fits file. Defaults to 0.

Returns:

Data cube.

Return type:

DataCube

Examples

>>> datacube = DataCube.create('data.fits')

Note

When the file name is give, the loaded data is squeezed; that is, the axis with zero size is dropped. Specifically, the polarization axis of the ALMA fits data may be dropped.

static loadfits(fname, index_hdul=0)

Read a data cube from a fits file.

Parameters:

  • fname (str) – Fits file name.

  • index_hdul (int, optional) – Index of fits extensions of the fits file. Defaults to 0.

Returns:

Tuple of the data and the fits header.

Return type:

tuple[np.ndarray, fits.Header]

Note

When the file name is give, the loaded data is squeezed; that is, the axis with zero size is dropped. Specifically, the polarization axis of the ALMA fits data may be dropped.

class tokult.core.ModelCube(imageplane, raw=None, xlim=None, ylim=None, vlim=None)

Bases: Cube

Cube class to contain a modeled datacube.

This class is especially for the best-fit model cube.

Parameters:

  • imageplane (np.ndarray) –

  • raw (Optional[np.ndarray]) –

  • xlim (Optional[tuple[int, int]]) –

  • ylim (Optional[tuple[int, int]]) –

  • vlim (Optional[tuple[int, int]]) –

classmethod create(params, datacube, lensing=None, convolve=None, create_interpolate_lensing=None, upsampling_rate=(1, 1, 1))

Constructer of ModelCube.

Parameters:

  • params (tuple[float, ...]) – Input parameters.

  • datacube (DataCube) – Data cube. The size of the model cube is based on this data cube.

  • lensing (Optional[Callable], optional) – Lensing function. Defaults to None.

  • convolve (Optional[Callable], optional) – Convolving function. Defaults to None.

  • create_interpolate_lensing (Callable | None) –

  • upsampling_rate (tuple[int, ...]) –

Returns:

Model cube.

Return type:

ModelCube

Examples

>>> model = ModelCube.create(params, tok.datacube,
                             lensing=tok.gravlens.lensing,
                             convolve=tok.dirtybeam.fullconvolve)
to_mockcube(rms, convolve=None, seed=None, is_originalsize=False, uvcoverage=None)

Convert to and output noisy mock cube.

Parameters:

  • rms (Union[float, np.ndarray]) – RMS noise added to the model cube, after convolution.

  • convolve (Optional[Callable], optional) – Convolution function. This convolve both raw model cube and noise. Defaults to None.

  • seed (Optional[int], optional) – Random seed. Defaults to None.

  • is_originalsize (bool, optional) – If False, the output mock cube is the same size as imageplane. If True, the size is the same as original. Defaults to False.

  • uvcoverage (Optional[np.ndarray], optional) – Mask on the uv plane. Defaults to None.

Returns:

Mock data cube.

Return type:

np.ndarray

Examples

>>> mock = modelcube.to_mockcube(
               tok.datacube.rms(),
               tok.dirtybeam.fullconvolve,
               is_original=True)
class tokult.core.DirtyBeam(beam, header=None)

Bases: object

Contains dirtybeam, i.e., Point Spread Functions (PSF) of Cube.

Contained data is dirtybeam images as a function of frequency.

Parameters:

  • beam (np.ndarray) –

  • header (Optional[fits.Header]) –

classmethod create(data_or_fname, header=None, index_hdul=0)

Constructer of DirtyBeam.

Parameters:

  • data_or_fname (Union[np.ndarray, str]) – Data array or fits file name.

  • header (Optional[fits.Header], optional) – Header of the fits file. Defaults to None.

  • index_hdul (int, optional) – Index of fits extensions of the fits file. Defaults to 0.

Returns:

instance of DirtyBeam.

Return type:

DirtyBeam

convolve(image)

Convolve imageplane with dirtybeam (psf) in two dimension.

Perform two-dimensional convolution at each pixel (channel) along the velocity axis.

Parameters:

image (np.ndarray) – Image to be convolved. Note that the size must be the same as the attribute imageplane.

Returns:

2D-convolved cube.

Return type:

np.ndarray

Examples

>>> convolved_image = dirtybeam.convole(image)
fullconvolve(image, uvcoverage=None, is_noise=False)

Convolve original with dirtybeam (psf) in two dimension.

Difference between convolve() and fullconvolve() is the size of the input image. This method fullconvolve treat the image with the same size as the dirtybeam.original.

Parameters:

  • image (np.ndarray) – Image to be convolved. Note that the size must be the same as the attribute original.

  • uvcoverage (Optional[np.ndarray], optional) – Mask on the uv plane. Defaults to None.

  • is_noise (bool, optional) – True if image is data. False if noise. Defaults to False.

Returns:

2D-convolved cube.

Return type:

np.ndarray

Examples

>>> convolved_image = dirtybeam.fullconvole(tok.modelcube.raw)

How to create convolved noise.

>>> rng = numpy.random.default_rng()
>>> noise = rng.standard_normal(size=shape)
>>> noise = dirtybeam.fullconvolve(
                noise, uvcoverage=uvcoverage, is_noise=True)
cutout(xlim, ylim, vlim)

Cutout a cubic region from the dirty beam cube.

Parameters:

  • xlim (Union[tuple[int, int], slice]) – The limit of the x-axis.

  • ylim (Union[tuple[int, int], slice]) – The limit of the y-axis.

  • vlim (Union[tuple[int, int], slice]) – The limit of the v-axis.

Return type:

None

cutout_to_match_with(cube)

Cutout a region with the same size of the input cube.

Parameters:

cube (DataCube) – Datacube. The size of cube.original must be the same as the dirtybeam.original. This method makes the size of the dirtybeam.imageplane the same as cube.imageplane.

Return type:

None

static loadfits(fname, index_hdul=0)

Read the dirty beam from a fits file.

Parameters:

  • fname (str) – Fits file name.

  • index_hdul (int, optional) – Index of fits extensions of the fits file. Defaults to 0.

Returns:

Tuple of the data and the fits header.

Return type:

tuple[np.ndarray, fits.Header]

Caution

The data shape of DirtyBeam must be the same as the Datacube. This requirement is naturaly satisfied if the input dirty-beam and the image-cube fits files are simulationsly created with CASA.

class tokult.core.GravLens(x_arcsec_deflect, y_arcsec_deflect, header, z_source=None, z_lens=None, z_assumed=None)

Bases: object

Deal with gravitational lensing effects based on a given lens models.

Contents are lensing parameters depending on positions.

Parameters:

  • x_arcsec_deflect (np.ndarray) –

  • y_arcsec_deflect (np.ndarray) –

  • header (fits.Header) –

  • z_source (Optional[float]) –

  • z_lens (Optional[float]) –

  • z_assumed (Optional[float]) –

classmethod create(*, data_or_fname_xy_arcsec_deflect=None, data_or_fname_xy_pixel_deflect=None, data_or_fname_psi_arcsec=None, header=None, index_hdul=0, z_source=None, z_lens=None, z_assumed=inf)

Constructer of GravLens.

Either of the first three arguments are required to construct GravLens. If more thean one among the three are given, the earier argument take a priority (i.e., xy_arcsec_deflect > xy_pixel_deflect > psi_arcsec).

Parameters:

  • (Optional[Union[tuple[np.ndarray (data_or_fname_xy_arcsec_deflect) – tuple[str, …]]]): Tuple of the data arrays or fits file names of lensing parmeters, x-arcsec-deflect and y-arcsec-deflect. Defaults to None.

  • ...] – tuple[str, …]]]): Tuple of the data arrays or fits file names of lensing parmeters, x-arcsec-deflect and y-arcsec-deflect. Defaults to None.

  • data_or_fname_xy_arcsec_deflect (tuple[numpy.ndarray, ...] | tuple[str, ...] | None) –

  • data_or_fname_xy_pixel_deflect (tuple[numpy.ndarray, ...] | tuple[str, ...] | None) –

  • data_or_fname_psi_arcsec (ndarray | str | None) –

  • header (Header | None) –

  • index_hdul (int) –

  • z_source (float | None) –

  • z_lens (float | None) –

  • z_assumed (float) –

Return type:

GravLens

:paramtuple[str, …]]]): Tuple of the data arrays or fits file names of

lensing parmeters, x-arcsec-deflect and y-arcsec-deflect. Defaults to None.

Parameters:

  • (Optional[Union[tuple[np.ndarray (data_or_fname_xy_pixel_deflect) – tuple[str, …]]]): Tuple of the data arrays or fits file names of lensing parmeters, x-pixel-deflect and y-pixel-deflect. Defaults to None.

  • ...] – tuple[str, …]]]): Tuple of the data arrays or fits file names of lensing parmeters, x-pixel-deflect and y-pixel-deflect. Defaults to None.

  • data_or_fname_xy_arcsec_deflect (tuple[numpy.ndarray, ...] | tuple[str, ...] | None) –

  • data_or_fname_xy_pixel_deflect (tuple[numpy.ndarray, ...] | tuple[str, ...] | None) –

  • data_or_fname_psi_arcsec (ndarray | str | None) –

  • header (Header | None) –

  • index_hdul (int) –

  • z_source (float | None) –

  • z_lens (float | None) –

  • z_assumed (float) –

Return type:

GravLens

:paramtuple[str, …]]]): Tuple of the data arrays or fits file names of

lensing parmeters, x-pixel-deflect and y-pixel-deflect. Defaults to None.

Parameters:

  • data_or_fname_psi_arcsec (Optional[Union[np.ndarray, str]]) – Data array or fits file name of a lensing parmeter, psi. Note that this method compute the gradient of psi to obtain the deflection angles, so that significantly strong gravitational lensing might not be traced by psi. Defaults to None.

  • header (Optional[fits.Header], optional) – Header of the fits file. This method assumes that lensing parameter maps, x-arcsec-deflect and y-arcsec-deflect, have the same size and coordinates. Defaults to None.

  • index_hdul (int, optional) – Index of fits extensions of the fits file. Defaults to 0.

  • z_source (Optional[float], optional) – The source (galaxy) redshift. Defaults to None.

  • z_lens (Optional[float], optional) – The lens (cluster) redshift. Defaults to None.

  • z_assumed (float, optional) – The redshift assumed in the gravitational parameters. If D_s / D_L = 1, the value should be infinite (np.inf). Defaults to np.inf.

  • data_or_fname_xy_arcsec_deflect (tuple[numpy.ndarray, ...] | tuple[str, ...] | None) –

  • data_or_fname_xy_pixel_deflect (tuple[numpy.ndarray, ...] | tuple[str, ...] | None) –

Returns:

Instance of GravLens.

Return type:

GravLens

lensing(xgrid, ygrid)

Convert coordinates (x, y) from the image plane to the source plane.

Parameters:

  • xgrid (np.ndarray) – Array of the x coordinates on the image plane.

  • ygrid (np.ndarray) – Array of the y coordinates on the image plane.

Returns:

Tuple of coordinates on the source plane.

Return type:

tuple[np.ndarray, …]

Examples

>>> xx_source, yy_source = lensing(xx_image, yy_image)
create_interpolate_lensing(xgrid, ygrid)

Retrun a LensingInterpolate instance.

Parameters:

  • xgrid (np.ndarray) – 2D array of the x coordinate.

  • ygrid (np.ndarray) – 2D array of the y coordinate.

Returns:

[description]

Return type:

LensingInterpolate

Examples

>>> lensing_interp = gl.create_interpolate_lensing(xgrid, ygrid)
>>> x0_s, y0_s = lensing_interp(x0_i, y0_i)
class LensingInterpolate(xx, yy, x_pixel_deflect, y_pixel_deflect)

Bases: object

Interpolate lensing effects to a data point.

This class method is implemented to convert the center of the model disk to the image plane.

Parameters:

  • xx (np.ndarray) –

  • yy (np.ndarray) –

  • x_pixel_deflect (np.ndarray) –

  • y_pixel_deflect (np.ndarray) –

match_wcs_with(cube)

Match the world coordinate system with the input data cube.

Use the wcs of cube.imageplane; therefore, the matched lensing parameter map become smaller than the original map.

Parameters:

cube (DataCube) – DataCube including the header information. This method uses the wcs included in the header of the data cube and the GravLens instance.

Return type:

None

Examples

>>> gravlens.match_wcs_with(datacube)
use_redshifts(z_source, z_lens, z_assumed=inf)

Correct the lensing parameters using the redshifts.

Parameters:

  • z_source (float) – The source (galaxy) redshift.

  • z_lens (float) – The lens (cluster) redshift.

  • z_assumed (float, optional) – The redshift assumed in the gravitational parameters. If D_s / D_L = 1, the value should be infinite (np.inf). Defaults to np.inf.

Return type:

None

reset_redshifts()

Reset the redshift infomation.

Return type:

None

compute_deflection_angles()

Compute deflection angles in arcsec and pixels using redshifts

static convert_xy_arcsec_to_pixel(x_arcsec, y_arcsec, header)

Convert deflection angles of x and y in arcsec to in pixels.

Use the internal header “CDELT” for the conversion.

Parameters:

  • x_arcsec (np.ndarray) – Deflection angle of x given in arcsec.

  • y_arcsec (np.ndarray) – Deflection angle of y given in arcsec.

  • header (fits.Header) – Header including units information

Returns:

Tuple of the deflection angles of x

and y in pixels.

Return type:

tuple[np.ndarray, np.ndarray]

Examples

>>> x_pix, y_pix = gl.convert_xy_arcsec_to_pixel(x_arcsec, y_arcsec)
Nonte:

Assumes that the units of “CDELT1” and “CDELT2” are degree.

static convert_xy_pixel_to_arcsec(x_pixel, y_pixel, header)

Convert deflection angles of x and y in pixel to in arcsec.

Use the internal header “CDELT” for the conversion.

Parameters:

  • x_pixel (np.ndarray) – Deflection angle of x given in pixel.

  • y_pixel (np.ndarray) – Deflection angle of y given in pixel.

  • header (fits.Header) – Header including units information.

Returns:

Tuple of the deflection angles of x

and y in arcsec.

Return type:

tuple[np.ndarray, np.ndarray]

Examples

>>> x_arcsec, y_arcsec = gl.convert_xy_pixel_to_arcsec(x_pix, y_pix, header)
Nonte:

Assumes that the units of “CDELT1” and “CDELT2” are degree.

static gradient(psi, header)

Compute gradient of 2D image.

This method is used to compute deflection angles from the deflection potential psi.

Parameters:

  • psi (np.ndarray) – 2D image of the deflection potential. The units are given in arcsec, meaning that differentiation of psi with respect to the angle in arcsec gives the deflection angles in arcsec.

  • header (fits.Header) – Header including units information.

Returns:

Tuple of the deflection angles of y

and x. Note that the order is (y, x).

Return type:

tuple[np.ndarray, np.ndarray]

Examples

>>> y_arcsec, x_arcsec = gl.gradient(psi, header=header)
Nonte:

Assumes that the units of “CDELT1” and “CDELT2” are degree.

static get_angular_distance_ratio(z_source, z_lens, z_assumed=inf)

Angular distance ratio of D_LS to D_S, normalized by assumed D_LS/D_S.

Lensing parameter maps are distributed using some D_LS/D_S at specific redshifts. This method provides a new factor that can be multiplied by the lensing parameter maps to correct the redshift dependency.

Parameters:

  • z_source (float) – The source (galaxy) redshift.

  • z_lens (float) – The lens (cluster) redshift.

  • z_assumed (float, optional) – The redshift assumed in the gravitational parameters. If D_s / D_L = 1, the value should be infinite (np.inf). Defaults to np.inf.

Returns:

Angular distance ratio, D_LS/D_S

Return type:

float

Examples

>>> distance_ratio = gravlens.get_angular_distance_ratio(6.2, 0.9)
>>> x_deflect_new = x_deflect_old * distance_ratio
static loadfits(fname_x_deflect, fname_y_deflect, index_hdul=0)

Read gravlens from fits file.

Parameters:

  • fname_x_deflect (str) – Fits file name of the deflect map of x.

  • fname_y_deflect (str) – Fits file name of the deflect map of y.

  • index_hdul (int, optional) – Index of fits extensions of the fits file. Assumes that all the fits files include the lensing parameter maps at the same extension index. Defaults to 0.

Returns:

Tuple of three objects;

deflection angles (x and y) and header.

Return type:

tuple[np.ndarray, np.ndarray, fits.Header]

tokult.example module

example documents