GalPaK3D’s API

class galpak.run(cube, variance=None, seeing=None, line=None, instrument=None, verbose=True, model=None, crval3=None, crpix3=None, cunit3=None, cdelt3=None, ctype3=None, cunit1=None, force_header_update=False, max_iterations=15000, method_chain='last', last_chain_fraction=60, percentile=95, mcmc_method='galpak', mcmc_sampling='AdaptiveCauchy', chi_stat='gaussian', min_boundaries=None, max_boundaries=None, known_parameters=None, initial_parameters=None, min_acceptance_rate=5.0, random_scale=None, **kwargs)[source]

Creates a GalPaK3D instance and runs it on provided cube. Refer to documentations of GalPaK3D and GalPaK3D.run_mcmc().

model: Model Class

default: DefaultModel

Use like this:

import galpak
g = galpak.run(cube='my.fits', instrument=myinstrument, model=mymodel)

print g.galaxy
g.save('my_run')
# etc.
class galpak.autorun(cube, variance=None, instrument=None, verbose=True, seeing=None, model=None, crval3=None, crpix3=None, cunit3=None, cdelt3=None, ctype3=None, cunit1=None, force_header_update=False, max_iterations=5000, method_chain='last', last_chain_fraction=60, percentile=95, chi_stat='gaussian', mcmc_method='galpak', mcmc_sampling='AdaptiveCauchy', min_boundaries=None, max_boundaries=None, known_parameters=None, initial_parameters=None, random_scale=1, MaxIter=25, target_acceptance=40, target_tolerance=5, **kwargs)[source]

Creates a GalPaK3D instance and runs it on provided cube. Refer to documentations of GalPaK3D and GalPaK3D.run_mcmc().

model: Model Class

default: ModelSersic

MaxIter: int

default: 25 maximum number of iterations for searching rscale

target_acceptancefloat

default: 40 target acceptance rate

Use like this:

import galpak
g = galpak.autorun(cube='my.fits', instrument=myinstrument, model=mymodel)

print g.galaxy
g.save('my_run')
# etc.
class galpak.GalPaK3D(cube, variance=None, model=None, seeing=None, instrument=None, quiet=False, 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.

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.

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

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

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()

old routine :return:

plot_geweke(filepath=None, fontsize=10, Nsigma=2, Nintervals=25, full_chain=False)
Plot the Geweke score for each parameter (from Geweke 1992: http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.27.2952)

and then either show it or save it to a file.

See also https://pymc-devs.github.io/pymc/modelchecking.html

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.

fontsize: int [None default]

to change the fontsize for plot if None will use rcParams

Nsigma: int [3 default]

sigma range for convergence test

Nintervals

Number of intervals for geweke statistics

full_chain: boolean

True if score for full chain

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(filename=None, method=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', mcmc_method='galpak', mcmc_sampling=None, min_boundaries=None, max_boundaries=None, known_parameters=None, initial_parameters=None, gprior_parameters=None, random_scale=None, min_acceptance_rate=10, verbose=True, emcee_nwalkers=30, **kwargs)[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’ | ‘MAP’
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

  • ‘MAP’: Parameters at Maximum At Posteriori, i.e. at chi_min

last_chain_fraction: int

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

model = DefaultModel()

see class DiskModel or ModelSersic

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

The chi2 statitics https://heasarc.gsfc.nasa.gov/xanadu/xspec/manual/XSappendixStatistics.html

mcmc_method: ‘galpak’ [default] | ‘emcee_walkers’| ‘emcee_MH’ | ‘dynesty’ | ‘multinest’
The MCMC method.

  • galpak: for the original MCMC algorithm using Cauchy proposal distribution

  • emcee_MH: emcee Metropolis Hasting

  • emcee_walkers: emcee multi-Walkers algorithms with Moves if version>=3.0

  • dynesty: unsupported

  • multinest: using Importance Nested Sampling w/ pyMultinest

  • pymc3: to be implemented

mcmc_sampling: None [default] | ‘Cauchy’ | ‘AdaptiveCauchy’ | ‘Normal’ | ‘DE’ | ‘walkers’

The sampling proposal distribution for MCMC_methods [galpak, emcee]

  • ‘Cauchy’ default when mcmc_method = ‘galpak’ or ‘emcee_MH’

    requires tuning random_scale

  • ‘AdaptiveCauchy’ for mcmc_method = ‘galpak [using last 500 or 750 iterations]

  • ‘Normal’ Gaussian sampling for ‘galpak’ or ‘emcee_MH’

  • ‘walkers’ (=StretchMove) default when mcmc_method =’emcee_walkers’

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.

gprior_parameters: ndarray | [2x GalaxyParameters]

Gaussian prior parameters

the algorithm will not try to guess them.

initial_parameters: ndarray|ModelParameters

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.

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

    A table representation of the parameters of the galaxy.

  • <name>_chain.dat

    A table 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>_3Dkernel.fits

    A FITS file containing the 3D kernel used

  • <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.pdf/png

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

  • <name>_mcmc.pdf/png

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

  • <name>_true_maps.pdf/png

    A PNG image generated by the plot_true_vfield method.

  • <name>_obs_maps.pdf/png

    The observed maps generated by the plot_obs_vfield method.

  • <name>_model.txt

    The model configuration

  • <name>_instrument.txt

    The instrument configuration

  • <name>_geweke.pdf/png

    The geweke diagnostics plot

  • <name>_galaxy_parameters_convergence.dat

    The convergence of each parameter based on the geweke diagnostics

  • <name>_corner.pdf/png

    The corner plot for the MCMC chain. Requires

  • <name>_stats.dat

    A ascii file containing the BIC/DIC etc criteria

The .dat files can be easily read using astropy.table and its ascii_fixedwidth format :

Table.read('example.chain.dat', format='ascii.fixed_width')

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.