Kinematics

Classes for kinematic data.

API

Classes:

BayesLOSVD(**kwargs)	Bayes LOSVD kinematic data
GaussHermite(**kwargs)	LOSVDs described by a Gauss Hermite expansion
Histogram([xedg, y, normalise])	LOSVD histograms
Kinematics([weight, type, hist_width, ...])	Abstract class for Kinematics

class kinematics.BayesLOSVD(**kwargs)

Bayes LOSVD kinematic data

Methods:

center_v_systemic([v_systemic])	Center the LOSVD histograms on systemtic velocity
convert_losvd_columns_to_one_multidimensional_column()	Convert 1D to multi-dim columns
convert_multidimensional_losvd_columns_to_univariate()	Convert multi-dim columns to 1D
get_observed_values_and_uncertainties(...)	Get LOSVD mean/uncertainties
load_hdf5(filename)	Load a hdf5 file of BAYES-LOSVD output
map_binID_blosvd_to_binID_dynamite(binID_blosvd)	Map BayesLOSVD binIDs to DYNMAITE binIDs.
rebin_orblib_to_observations(losvd_histograms)	Rebin orblib to velocity spacing of observations
save_data_table([outfile])	Special save method for BayesLOSVD data.
set_default_hist_bins([oversampling_factor])	Set default LOSVD nbins for orblibs
set_default_hist_center()	Sets orbit histogram center to 0
set_default_hist_width([scale])	Set orbit histogram width
set_mean_v_and_sig_v_per_aperture()	get mean and dispersion
transform_orblib_to_observables(...)	trasform orbit library to observed kinematics
write_aperture_and_bin_files([filename, ...])	Write aperture.dat and bins.dat files
write_losvds_to_ecsv_format([filename, outfile])	Convert BayesLOSVD output to ECSV

center_v_systemic(v_systemic='flux_weighted')

Center the LOSVD histograms on systemtic velocity

Uses velocity spacing of the data divided by oversampling_factor. Also forces nbins to be odd, so that central bin in 0-centered.

Parameters:

v_systemicstring or float. If ‘flux_weighted’, then use the flux

weighted mean-velocity of the kinematics. Otherwise, provide a float directly.

Returns:

Sets the result to attribute self.hist_bins

convert_losvd_columns_to_one_multidimensional_column()

Convert 1D to multi-dim columns

ECSV files can save 1D columns, but useful to work with multi-dim columns for the LOSVSD. This method converts.

Returns:

Re-sets self.data['losvd'] and self.data['dlosvd'] to multi-dim

columns

convert_multidimensional_losvd_columns_to_univariate()

Convert multi-dim columns to 1D

ECSV files can save 1D columns, but useful to work with multi-dim columns for the LOSVSD. This method converts.

Returns:

Re-sets self.data['losvd'] and self.data['dlosvd'] to 1D columns

called self.data['losvd_{i}'] and self.data['dlosvd_{i}'] for

i = 1, …, N_LOSVD_bins

get_observed_values_and_uncertainties(weight_solver_settings)

Get LOSVD mean/uncertainties

Parameters:

weight_solver_settingsdict

Returns:

tuple

(observed_values, uncertainties), where: - observed_values array of shape (n_aperture, n_vbins) - uncertainties array of shape (n_aperture, n_vbins)

load_hdf5(filename)

Load a hdf5 file of BAYES-LOSVD output

Borrowed from bayes_losvd_load_hdf5.py

Parameters:

filenamestring

the hdf5 file of BayesLOSVD output

Returns:

dict

data read from BayesLOSVD output file

map_binID_blosvd_to_binID_dynamite(binID_blosvd)

Map BayesLOSVD binIDs to DYNMAITE binIDs.

Assumes that the table self.data has colums binID_BayesLOSVD and binID_dynamite which define the mapping. Any binID_blosvd with no corresponding binID_dynamite are given binID_dynamite=0.

Parameters:

binID_blosvdarray

array of BayesLOSVD binIDs

Returns:

type

corresponding array of DYNMAITE binIDs

rebin_orblib_to_observations(losvd_histograms)

Rebin orblib to velocity spacing of observations

Creates a matrix f, the fraction of the j’th orblib vbin in the i’th data vbin. Multiplies orblib losvd_histograms by f to rebin.

Parameters:

losvd_histogramsdyn.kinematics.Histogram

a histogram object of the orblib LOSVD

Returns:

dyn.kinematics.Histogram

a orblib LOSVD re-binned to the data velocity spacing

save_data_table(outfile=None)

Special save method for BayesLOSVD data.

Handles conversion from multi-dim –> 1D columns. Should supercede the generic method dyn.data.Data.save

Parameters:

outfilestring

Name of output file

set_default_hist_bins(oversampling_factor=10)

Set default LOSVD nbins for orblibs

Uses velocity spacing of the data divided by oversampling_factor. Also forces nbins to be odd, so that central bin in 0-centered.

Parameters:

oversampling_factorfloat

scale factor to divide the data velocity spacing

Returns:

Sets the result to attribute self.hist_bins

set_default_hist_center()

Sets orbit histogram center to 0

set_default_hist_width(scale=2.0)

Set orbit histogram width

Set it to a multiple of data histogram width. Default 2 i.e. double to width of observed data. Sets result to attribute self.hist_width

Parameters:

scalefloat

scale factor

set_mean_v_and_sig_v_per_aperture()

get mean and dispersion

Returns:

creates columns self.data['v'] and self.data['sigma']

transform_orblib_to_observables(losvd_histograms, weight_solver_settings)

trasform orbit library to observed kinematics

This is a placeholder method. Specific implementations/subclasses of Kinematics should replace this with methods which transform an orbit library LOSVD to that particular type of kinematics.

Parameters:

losvd_histogramsdyn.kinematics.Histogram

the LOSVD of an orbit library

weight_solver_settingsdict

weight solver settings

Returns:

object

the orbit library LOSVD transofrmed to observed kinematics

write_aperture_and_bin_files(filename=None, angle_deg=0.0, center='max_flux', aperture_filename='aperture.dat', bin_filename='bins.dat')

Write aperture.dat and bins.dat files

Parameters:

filenamestring

filename XXX_results.hdf5 of BAYES-LOSVD output (all bins combined)

angle_degfloat

Angle in degrees measured counter clockwise from the galaxy major axis to the X-axis of the input data

centertuple or string

either pair of floats (x0,y0) defining center in pixel co-ordinates or string ‘max_flux’

aperture_filenamestring

name of aperture file

bin_filenamestring

name of bins file

write_losvds_to_ecsv_format(filename=None, outfile='bayes_losvd_kins.ecsv')

Convert BayesLOSVD output to ECSV

Reads in the hdf5 BayesLOSVD output file for all spatial bins. Saves the median and 68% Bayesian Credible Interval of the LOSVD in each LOSVD bin, into an astropy ECSV file.

Parameters:

filenamestring

BayesLOSVD hdf5 output file for all spatial bins.

outfilestring

desired name of output ECSV file

Returns:

None

class kinematics.GaussHermite(**kwargs)

LOSVDs described by a Gauss Hermite expansion

Using the Capellari et al 2016 convention

Methods:

convert_file_from_old_format(...)	Convert old format of GH kinematics to new format
evaluate_hermite_polynomials(coeffients, w)	Evaluate Hermite polynomials
evaluate_losvd(v, v_mu, v_sig, h)	evaluate LOSVDs
evaluate_losvd_normalisation(h)	Evaluate LOSVD normalisation
get_gh_expansion_coefficients([v_mu, v_sig, ...])	Calcuate GH expansion coeffients given an LOSVD
get_hermite_polynomial_coeffients([max_order])	Get Hermite poly coeffients
get_highest_order_gh_coefficient([max_gh_check])	Get max order GH coeeff from data table
get_observed_values_and_uncertainties(...)	Extract mean/sigma from the GH kinematics
read_file_old_format(filename)	Read the old format of GH kinematics
set_default_hist_bins([f_sig])	Sets default nbins so they are roughly f_sig*min(sig)
set_default_hist_center()	Sets default histogram center to 0.
set_default_hist_width([n_sig])	Sets default histogram width
standardise_velocities(v, v_mu, v_sig)	Take away v_mu, divide by v_sig
transform_orblib_to_observables(...)	trasform orbit library to observed kinematics

convert_file_from_old_format(filename_old_format, filename_new_format)

Convert old format of GH kinematics to new format

Old format is that used in triaxialschwarzschild AKA schwpy codes

Parameters:

filename_old_formatstring

filename of old/shwpy format of GH kinematics file

filename_new_formatstring

desired filename of new Astropy ECSV format

Returns:

None

creates a an astropy ECSV file at filename_new_format

evaluate_hermite_polynomials(coeffients, w, standardised=True, v_mu=None, v_sig=None)

Evaluate Hermite polynomials

Parameters:

coeffientsarray (n_herm, n_herm)

coefficients of hermite polynomials as given by method get_hermite_polynomial_coeffients

warray

if standardised==True then w is array of shape (n_regions, n_vbins) of standardised (AKA whitened) velocities else, w is array of shape (n_vbins,) of physical velocities and arrays v_mu and v_sig with shape (n_regions,) must be set

standardisedBoolean

whether or not velocities w have been standardised by aperture v/sig

v_muNone or array shape (n_regions,)

aperture v_mu’s

v_sigNone or array shape (n_regions,)

aperture v_sigma’s

Returns:

array shape (n_herm, n_regions, n_vbins)

array[i,j,:] is the i’th Hermite polynomial evaluated at standardised velocities w in the j’th region

evaluate_losvd(v, v_mu, v_sig, h)

evaluate LOSVDs

Evaluate the quantity

\[\mathrm{LOSVD}(v) = \frac{1}{v_\sigma} \mathcal{N}(w; 0, 1^2) \Sigma_{m=0}^{M} h_m H_m(w)\]

where normalised velocity \(w = (v-v_\mu)/v_\sigma\)

Parameters:

varray

input velocity array

v_muarray (n_regions,)

gauss hermite v parameters

v_sigarray (n_regions,)

gauss hermite sigma parameters

harray (n_hists, n_regions, n_herm)

gauss hermite expansion coefficients

Returns:

array shape same as v

values of gauss hermite expansion evaluated at v

evaluate_losvd_normalisation(h)

Evaluate LOSVD normalisation

Evaluate the normalising integral

\[\int_{-\infty}^{\infty} \mathrm{LOSVD}(v) dv\]

which for a GH expansion is given by

\[\Sigma_{m=0}^{M} b_m a_m\]

where

• \(a_m\) are the coefficients of w in the polynomial \(\Sigma_{m=0}^{M} h_m H_m(w)\)

• \(b_m\) =

  • 1 if m=0

  • 0 if m is odd

  • (m-1)!! if m is non-zero and even

and !! is a ‘double factorial’ - which does not mean two factorials but the product integers < n with same even/odd parity as n

Parameters:

v_sigarray (n_regions,)

gauss hermite sigma parameters

harray (n_hists, n_regions, n_herm)

gauss hermite expansion coefficients for some number of histograms and regions

Returns:

array (n_hists, n_regions)

get_gh_expansion_coefficients(v_mu=None, v_sig=None, vel_hist=None, max_order=4)

Calcuate GH expansion coeffients given an LOSVD

Expand LOSVD around a given v_mu and v_sig using eqn 7 of vd Marel & Franx 93

Parameters:

v_muarray (n_regions,)

gauss hermite v parameters

v_sigarray (n_regions,)

gauss hermite sigma parameters

vel_histHistogram object

velocity histograms where vel_hist.y has shape (n_orbits, n_vbins, n_regions)

max_orderint

maximum order hermite polynomial desired in the expansion e.g. max_order = 1 –> use h0, h1 i.e. number of hermite polys = max_order + 1

Returns:

harray (n_hists, n_regions, max_order+1)

where h[i,j,k] is order k GH coeffient of histogram i in region j

get_hermite_polynomial_coeffients(max_order=None)

Get Hermite poly coeffients

Normalised as in eqn 14 of Capellari 16

Parameters:

max_orderint

maximum order hermite polynomial desired e.g. max_order = 3 means use h0, h1, h2, h3

Returns:

array (max_order+1, max_order+1)

coeffients[i,j] = coef of x^j in polynomial of order i

get_highest_order_gh_coefficient(max_gh_check=20)

Get max order GH coeeff from data table

Checks the data table for columns titled [‘h{i}’] and [‘dh{i}’], and return the largest i such that both exist

Parameters:

max_gh_checkint, optional

check up to this order

Returns:

int

the highest order GH present in the data table

get_observed_values_and_uncertainties(weight_solver_settings)

Extract mean/sigma from the GH kinematics

Parameters:

weight_solver_settingstype

Description of parameter weight_solver_settings.

Returns:

tuple

(observed_values, uncertainties), where: - observed_values is array of GH exapnsion coefficients of shape (n_apertures, max_gh_order) - uncertainties is array of uncertainties on GH exapnsion coefficients of shape (n_apertures, max_gh_order)

read_file_old_format(filename)

Read the old format of GH kinematics

Old format is that used in triaxialschwarzschild AKA schwpy codes

Parameters:

filenamestring

filename of old format of GH kinematics file

Returns:

Astropy table

the GH kinematics data

set_default_hist_bins(f_sig=0.1)

Sets default nbins so they are roughly f_sig*min(sig)

Parameters:

f_sigfloat

fraction of minimum sigma to (approximately) set histogram bin width

set_default_hist_center()

Sets default histogram center to 0.

set_default_hist_width(n_sig=3.0)

Sets default histogram width

Set it to

\(2 * max(|v| + n_\mathrm{sig}*\sigma)\)

i.e. double the largest velcoity present in the observed LOSVD

Parameters:

n_sigfloat

number of sigma above mean velocity to extend the velocity histogram

standardise_velocities(v, v_mu, v_sig)

Take away v_mu, divide by v_sig

Parameters:

varray

input velocity array

v_muarray (n_regions,)

gauss hermite v parameters

v_sigarray (n_regions,)

gauss hermite sigma parameters

Returns:

array (n_regions,) + v.shape

velocities whitened by array v_mu, v_sigma

transform_orblib_to_observables(losvd_histograms, weight_solver_settings)

trasform orbit library to observed kinematics

This is a placeholder method. Specific implementations/subclasses of Kinematics should replace this with methods which transform an orbit library LOSVD to that particular type of kinematics.

Parameters:

losvd_histogramsdyn.kinematics.Histogram

the LOSVD of an orbit library

weight_solver_settingsdict

weight solver settings

Returns:

object

the orbit library LOSVD transofrmed to observed kinematics

class kinematics.Histogram(xedg=None, y=None, normalise=False)

LOSVD histograms

Parameters:

xedgarray (n_bins+1,)

histogram bin edges

y(n_orbits, n_bins+1, n_apertures)

histogram values

normalisebool, default=True

whether to normalise to pdf

Attributes:

xarray (n_bins,)

bin centers

dxarray (n_bins,)

bin widths

normalisedbool

whether or not has been normalised to pdf

Methods:

get_mean()	Get the mean velocity
get_normalisation()	Get the normalsition
get_sigma()	Get the velocity dispersions
normalise()	normalises the LOSVDs
scale_x_values(scale_factor)	scale the velocity array

get_mean()

Get the mean velocity

Returns:

array shape (n_orbits, n_apertures)

mean velcoity of losvd

get_normalisation()

Get the normalsition

Calculates Sum_i losvd_i * dv_i

Returns:

float

the normalisation

get_sigma()

Get the velocity dispersions

Returns:

array shape (n_orbits, n_apertures)

velocity dispersion of losvd

normalise()

normalises the LOSVDs

Returns:

None

resets self.y to a normalised version

scale_x_values(scale_factor)

scale the velocity array

scales vel array, and dv

Parameters:

scale_factorfloat

Returns:

None

resets self.xedg, self.x, self.dx to rescaled versions

class kinematics.Kinematics(weight=None, type=None, hist_width='default', hist_center='default', hist_bins='default', **kwargs)

Abstract class for Kinematics

Specific implementations (e.g. GaussHermite) should be implemented as child classes

Methods:

get_observed_values_and_uncertainties(...)	Extract mean and uncertainties from the kinematic set
transform_orblib_to_observables(...)	trasform orbit library to observed kinematics
update(**kwargs)	Updates one or more attributes, including consistency check

get_observed_values_and_uncertainties(weight_solver_settings)

Extract mean and uncertainties from the kinematic set

This is a placeholder method. Specific implementations/subclasses of Kinematics should replace this with methods which extract the mean and uncertainties of that particular kinematic type.

Parameters:

weight_solver_settingstype

Description of parameter weight_solver_settings.

Returns:

tuple

(observed_values, uncertainties)

transform_orblib_to_observables(losvd_histograms, weight_solver_settings)

trasform orbit library to observed kinematics

This is a placeholder method. Specific implementations/subclasses of Kinematics should replace this with methods which transform an orbit library LOSVD to that particular type of kinematics.

Parameters:

losvd_histogramsdyn.kinematics.Histogram

the LOSVD of an orbit library

weight_solver_settingsdict

weight solver settings

Returns:

object

the orbit library LOSVD transofrmed to observed kinematics

update(**kwargs)

Updates one or more attributes, including consistency check

Parameters:

**kwargsattribute=value pairs

Returns:

None.

Raises:

ValueError

If class attribute does not exist

Inheritance Diagram