GalPaK3D‘s API

class galpak.GalPaK3D(cube, variance=None, redshift=None, seeing=None, line=None, instrument=None, verbose=True, flux_image=None, crval3=None, crpix3=None, cunit3=None, cdelt3=None, ctype3=None, cunit1=None, force_header_update=False)[source]

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.
redshift: float
The redshift of the galaxy we’re observing in the measure cube. This is used in the estimation of the mass of the galaxy. If this is not set, GalPak will not try to compute the mass. This has no influence over the MCMC run, it will still try to guess the galaxy’s z position.
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.
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)[source]

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

galaxy: GalaxyParameters
The parameters upon which the simulated galaxy will be built.
shape: Tuple of 3
The 3D shape of the resulting cube. Eg: (21,21,21)

flux_profile: see run_mcmc() rotation_curve: see run_mcmc() rotation_curve: see run_mcmc()

Returns a HyperspectralCube

create_convolved_cube(galaxy, shape)[source]

Creates a cube containing a convolved simulation of a galaxy according to the provided parameters. 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 shape of the resulting cube. Eg: (21,21,21)

flux_profile: see run_mcmc() rotation_curve: see run_mcmc() rotation_curve: see run_mcmc()

Returns a HyperspectralCube

plot_correlations(filepath=None, nbins=15, fontsize=12)[source]

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)[source]

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=12)[source]

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.
sort_by_chi: bool
True to sort the chain by decreasing reduced chi2
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, flux_profile='exponential', hz_profile='gaussian', flux_image=None, rotation_curve='arctan', disk_dispersion='thick', chi_stat='gaussian', redshift=None, min_boundaries=None, max_boundaries=None, known_parameters=None, initial_parameters=None, min_acceptance_rate=5.0, random_scale=None, verbose=True)[source]

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.
flux_profile: ‘exponential’ | ‘gaussian’ | ‘de_vaucouleurs’ | ‘user’
The flux profile of the observed galaxy. The default is ‘exponential’. See http://en.wikipedia.org/wiki/Sersic%27s_law If ‘user’ provided flux map, specify flux_image. Currently unsupported
hz_profile: ‘gaussian’ [default] | ‘exponential’ | ‘sech2’
The flux profile perpendicular to the disk. The default is ‘gaussian’ .
flux_image: string
filename of user provided flux image (fits) to be used UNSUPPORTED
rotation_curve: ‘arctan’ | ‘mass’ | ‘exp’ | ‘tanh’ | ‘isothermal’
The profile of the velocity v(r) can be in
  • ‘arctan’ (default) : ~ Vmax arctan(r/rV), rV=turnover radius
  • ‘tanh’ : Vmax tanh(r/rV), rV=turnover radius
  • ‘exp’ : inverted exponential, 1-exp(-r/rV)
  • ‘mass’ : a constant light-to-mass ratio v(r)=sqrt(G m(<r) / r)
  • ‘isothermal’ : an isothermal rotation curve v(r)=Vmax * sqrt(1-rV/r * arctan(r/rV)
disk_dispersion: ‘thick’|’thin’|’infinitely_thin’
The local disk dispersion from the rotation curve and disk thickness from Binney & Tremaine 2008
see Genzel et al. 2008.
GalPak has 3 components for the dispersion:
  • a component from the rotation curve arising from mixing velocities of a disk with non-zero thickness
  • a component from the local disk dispersion specified by disk_dispersion
  • a spatially constant dispersion, [which is the output parameter velocity_dispersion]
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)
redshift: float
The redshift of the observed galaxy, used in mass calculus. Will override the redshift provided at init ; this is a convenience parameter. If this is not set anywhere, GalPak will not try to compute the mass.
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 following

galaxy.radius = 3.0 galaxy.rv = 1.0 galaxy.maximum_velocity = 0.0 galaxy.velocity_dispersion = 5.0 galaxy.flux = flux

If any of these values are NaN, they will be replaced by the mean of the boundaries (default values).

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 deconvolution is faster when this is set to False.
save(name, clobber=False)[source]

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 clobber option is always true for this file.

  • <name>_mcmc.png

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

  • <name>_correlations.png

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

  • <name>true_maps.png

    A PNG image generated by the plot_true_vfield method. Note: the clobber 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’.
clobber: bool
When set to true, will OVERWRITE existing files.