GalPaK3D’s API

class galpak.GalPaK3D(cube, variance=None, line=None, seeing=None, instrument=None, crval3=None, crpix3=None, cunit3=None, cdelt3=None, ctype3=None, cunit1=None, force_header_update=False)

GalPaK3D is a tool to extract Galaxy Parameters and Kinematics from 3-Dimensional data, using reverse deconvolution with Bayesian analysis Markov Chain Monte Carlo. (random walk)

cube: HyperspectralCube|string

The actual data on which we’ll work ; it should contain only one galaxy. Can be a HyperspectralCube object, a string filename to a FITS file, or even MPDAF’s mpdaf.obj.Cube.

seeing: float

Aka the Point Spread Function’s Full Width Half Maximum. This convenience parameter, when provided, will override the FWHM value of the instrument’s PSF.

line: None[default] | dict to fit doublets, use a dictionary with

line[‘wave’]=[l, lref] eg. [3726.2, 3728.9] # Observed or Rest line[‘ratio’]=[0.8, 1.0] eg. [0.8, 1.0] # The primary line for redshifts is the reddest

instrument: Instrument

The instrument configuration to use when simulating convolution. The default is MUSE.

crval3: float

A value for the cube’s header’s CRVAL3 when it is missing. You should update your cube’s header.

crpix3: float

A value for the cube’s header’s CRPIX3 when it is missing. You should update your cube’s header.

cunit3: float

A value for the cube’s header’s CUNIT3 when it is missing. You should update your cube’s header.

cdelt3: float

A value for the cube’s header’s CDELT3 when it is missing. You should update your cube’s header.

cunit1: float

A value for the cube’s header’s CUNIT1 (&2) when it is missing. You should update your cube’s header.

force_header_update: bool

Set to True to force the update of the above header cards, when their values are not missing. Note: These will not be saved into the FITS file. (if the cube is one)

create_clean_cube(galaxy, shape, final=False)

Creates a cube containing a clean simulation of a galaxy according to the provided model.

galaxy: GalaxyParameters

The parameters upon which the simulated galaxy will be built.

shape: Tuple of 3

The 3D (z, y, x) shape of the resulting cube. Eg: (21, 21, 21)

Returns a HyperspectralCube

create_convolved_cube(galaxy, shape)

Creates a cube containing a convolved simulation of a galaxy according to the provided model. The convolution is done by the instrument you provided upon instantiation of this class.

galaxy: GalaxyParameters

The parameters upon which the simulated galaxy will be built.

shape: Tuple of 3

The 3D (Z, Y, X) shape of the resulting cube. Eg: (21, 21, 21)

Returns a HyperspectralCube

plot_correlations(filepath=None, nbins=15, fontsize=10)

Plot the correlations between parameters.

filepath: string

If specified, will write the plot to a file instead of showing it, at the provided absolute or relative filepath. The extension of the file must be either png or pdf. Eg: filepath=’/home/me/my_galaxy/galpak/run_correlations.png’

fontsize: int

to change the fontsize

plot_images(filepath=None, z_crop=None)

Plot a mosaic of images of the cropped (along z) cubes, and then either show it or save it to a file.

filepath: string

If specified, will write the plot to a file instead of showing it. The file will be created at the provided absolute or relative filepath. The extension of the file must be either png or pdf.

z_crop: None|int

The maximum and total length of the crop (in pixels) along z, centered on the galaxy’s z position. If you provide zero or an even value (2n), the closest bigger odd value will be used (2n+1). By default, will not crop.

plot_mcmc(filepath=None, plot_likelihood=False, adapt_range='5stdev', fontsize=10)

Plot the MCMC chain details, and then either show it or save it to a file.

filepath: string

If specified, will write the plot to a file instead of showing it. The file will be created at the provided filepath, be it absolute or relative. The extension of the file must be either png or pdf.

plot_likelihood: bool

True to plot -log[chi2] instead

adapt_range: string

‘boundaries’ to adapt the range to boundaries ‘minmax’ [default] to adapt the range to min/max values ‘3stdev’ to adapt the range to 3 x stdev ‘5stdev’ to adapt the range to 5 x stdev

fontsize: int

to change the fontsize

run_mcmc(max_iterations=15000, method_chain='last', last_chain_fraction=60, percentile=95, model=None, chi_stat='gaussian', min_boundaries=None, max_boundaries=None, known_parameters=None, initial_parameters=None, min_acceptance_rate=5.0, random_scale=None, verbose=True, save_error_maps=True)

Main method_chain of GalPak, computes and returns the galaxy parameters as a GalaxyParameters object using reverse deconvolution with a MCMC.

Also fills up the following attributes :

• chain
• psf3d
• deconvolved_cube
• convolved_cube
• residuals_cube (Data-Model in units of sigma)

• residuals_map (average of data-model in units of sigma or = 1/N_z.

  Sum_z Residuals_cube. sqrt(Nz) )

• acceptance_rate

• galaxy (same object as returned value)

  with Vmax forced to be positive [and 180 added to PA]

• stdev (also available as galaxy.stdev)
• true_flux_map
• true_velocity_map
• true_disp_map

Stops iteration if acceptance rate drops below min_acceptance_rate % or when max_iterations are reached.

max_iterations: int

Maximum number of useful iterations.

method_chain: ‘chi_sorted’|’chi_min’|’last’

Method used to determine the best parameters from the chain.

• ‘last’ (default) : mean of the last_chain_fraction(%) last parameters of the chain
• ‘chi_sorted’ : mean of the last_chain_fraction(%) best fit parameters of the chain
• ‘chi_min’ : mean of last_chain_fraction(%) of the chain around the min chi

last_chain_fraction: int

Last Chain fraction (in %) used to compute the best parameters. Defaults to 60.

model = DiskModel()

see class DiskModel

chi_stat: ‘gaussian’ [default] | ‘Mighell’ | ‘Neyman’

The chi2 statitics https://heasarc.gsfc.nasa.gov/xanadu/xspec/manual/XSappendixStatistics.html Mighell http://adsabs.harvard.edu/abs/1999ApJ…518..380M Humphrey 2009, http://adsabs.harvard.edu/abs/2009ApJ…693..822H

• ‘gaussian’ (default): Sum (D - M)^2 / e
• ‘Neyman’ Sum (D - M )^2 / max(D,1)
• ‘Mighell’ Sum (D + min(D,1) - M)^2 / (D+1)

min_boundaries: ndarray|GalaxyParameters

The galaxy parameters will never be less than these values. Will override the default minimum boundaries for the parameters. If any of these values are NaN, they will be replaced by the default ones.

max_boundaries: ndarray|GalaxyParameters

The galaxy parameters will never be more than these values. Will override the default minimum boundaries for the parameters. If any of these values are NaN, they will be replaced by the default ones.

known_parameters: ndarray|GalaxyParameters

All set parameters in this array will be skipped in the MCMC, the algorithm will not try to guess them.

initial_parameters: ndarray|GalaxyParameters

The initial galaxy parameters of the MCMC chain. If None, will use the inital parameters provided by the model. The galaxy parameters not initialized by the model or by this parameter will be set to the mean of the boundaries.

min_acceptance_rate: float

In %, the acceptance rate is the number of useful iterations divided by the total number of iterations. If it gets below the failure_rate treshold, iterations stop.

random_scale: float

Scale the amplitude of the MCMC sampling by these values. This is an important parameter to adjust for reasonable acceptance rate. The acceptance rate should be around 30-50%. If the acceptance rate is <20-30% (too low), decrease random_scale IF the acceptance rate is >50-60% (too high), increase random_scale

verbose: boolean

Set to True to output a detailed log of the process. The run is faster when this is left to False.

save(name, overwrite=False)

Saves the results of the MCMC to files :

• <name>_galaxy_parameters.txt

  A plain text representation of the parameters of the galaxy.

• <name>_galaxy_parameters.dat

  An asciitable representation of the parameters of the galaxy.

• <name>_chain.dat

  An asciitable representation of the Markov Chain. Each line holds one set of galaxy parameters and its associated reduced chi.

• <name>_run_parameters.txt

  A plain text representation of the run_parameters.

• <name>_instrument.txt

  A plain text representation of the instrument parameters.

• <name>_convolved_cube.fits

  A FITS file containing the PSF-convolved result cube.

• <name>_deconvolved_cube.fits

  A FITS file containing the pre-convolution clean cube.

• <name>_residuals_cube.fits

  A FITS file containing the diff between input data and simulation.

• <name>_true_flux_map.fits

  A FITS file containing the true flux map [intrinsic]

• <name>_true_vel_map.fits

  A FITS file containing the true velocity map [intrinsic]

• <name>_true_sig_map.fits

  A FITS file containing the true dispersion map [intrinsic]

• <name>_obs_flux_map.fits

  A FITS file containing the observed flux map [intrinsic]

• <name>_obs_vel_map.fits

  A FITS file containing the observed velocity map [intrinsic]

• <name>_obs_sig_map.fits

  A FITS file containing the observed dispersion map [intrinsic]

• <name>_images.png

  A PNG image generated by the plot_images method. Note: the overwrite option is always true for this file.

• <name>_mcmc.png

  A PNG image generated by the plot_mcmc method. Note: the overwrite option is always true for this file.

• <name>_correlations.png

  A PNG image generated by the plot_correlations method. Note: the overwrite option is always true for this file.

• <name>true_maps.png

  A PNG image generated by the plot_true_vfield method. Note: the overwrite option is always true for this file.

The .dat files can be easily read using asciitable and its asciitable.FixedWidth Reader :

asciitable.read('example.chain.dat', Reader=asciitable.FixedWidth)

Warning

The generated files are not compressed and may take up a lot of disk space.

name: string

An absolute or relative name that will be used as prefix for the save files. Eg: ‘my_run’, or ‘/home/me/science/my_run’.

overwrite: bool

When set to true, will OVERWRITE existing files.