Core module¶

ORCS Core library.

Note

ORCS is built over ORB so that ORB must be installed.

class orcs.core.HDFCube(cube_path, debug=False, **kwargs)¶

Bases: orb.core.HDFCube

Extension of orb.core.HDFCube

Core class which gives access to an HDF5 cube. The child class SpectralCube may be prefered in general for its broader functionality.

See also

orb.core.HDFCube

__init__(cube_path, debug=False, **kwargs)¶

Parameters:	cube_path – Path to the HDF5 cube. kwargs – Kwargs are `orb.core.HDFCube()` properties.

_extract_spectrum_from_region(region, subtract_spectrum=None, median=False, mean_flux=False, silent=False, return_spec_nb=False, return_mean_theta=False, return_gvar=False, output_axis=None)¶

Extract the integrated spectrum from a region of the cube.

All extraction of spectral data must use this core function because it makes sure that all the updated calibrations are taken into account.

Parameters:

region – A list of the indices of the pixels integrated in the returned spectrum.
subtract_spectrum – (Optional) Remove the given spectrum from the extracted spectrum before fitting parameters. Useful to remove sky spectrum. Both spectra must have the same size.
median – (Optional) If True the integrated spectrum is computed from the median of the spectra multiplied by the number of pixels integrated. Else the integrated spectrum is the pure sum of the spectra. In both cases the flux of the spectrum is the total integrated flux (Default False).
mean_flux – (Optional) If True the flux of the spectrum is the mean flux of the extracted region (default False).
return_spec_nb – (Optional) If True the number of spectra integrated is returned (default False).
silent – (Optional) If True, nothing is printed (default False).
return_mean_theta – (Optional) If True, the mean of the theta values covered by the region is returned (default False).
return_gvar – (Optional) If True, returned spectrum will be a gvar. i.e. a data vector with it’s uncetainty (default False).
output_axis – (Optional) If not None, the spectrum is projected on the output axis. Else a scipy.UnivariateSpline object is returned (defautl None).

Returns:

A scipy.UnivariateSpline object or a spectrum projected on the ouput_axis if it is not None.

_fit_integrated_spectra(regions_file_path, subtract=None, plot=True, verbose=True, snr_guess=None, max_iter=None)¶

Fit integrated spectra and their emission lines parameters.

Note

Raw function which needs self.inputparams to be defined before with :py:meth:~HDFCube._prepare_input_params.

Parameters:

regions_file_path – Path to a ds9 reg file giving the positions of the regions. Each region is considered as a different region.
subtract – Spectrum to subtract (must be a spline)
plot – (Optional) If True, plot each intergrated spectrum along with the its fit (default True).
verbose – (Optional) If True print the fit results (default True).
snr_guess – Guess on the SNR of the spectrum. Can only be None or ‘auto’. Set it to ‘auto’ to make a Bayesian fit. In this case two fits are made - one with a predefined SNR and the other with the SNR deduced from the first fit. If None a classical fit is made. (default None).
max_iter – (Optional) Maximum number of iterations (default None)

_fit_lines_in_region(region, subtract_spectrum=None, binning=1, snr_guess=None, mapped_kwargs=None, max_iter=None, timeout=None)¶

Raw function that fit lines in a given region of the cube.

All the pixels in the defined region are fitted one by one and a set of maps containing the fitted paramaters are written. Note that the pixels can be binned.

Note

Need the InputParams class to be defined before call (see _prepare_input_params()).

Note

The fit will always use the Bayesian algorithm.

Parameters:

region – Region to fit. Multiple regions can be used to define the fitted region. They do not need to be contiguous.
subtract_spectrum – (Optional) Remove the given spectrum from the extracted spectrum before fitting parameters. Useful to remove sky spectrum. Both spectra must have the same size.
binning – (Optional) Binning. The fitted pixels can be binned.
snr_guess – Guess on the SNR of the spectrum. Can only be None or ‘auto’. Set it to ‘auto’ to make a Bayesian fit. In this case two fits are made - one with a predefined SNR and the other with the SNR deduced from the first fit. If None a classical fit is made. (default None).
max_iter – (Optional) Maximum number of iterations (default None)
mapped_kwargs – If a kwarg is mapped, its value will be replaced by the value at the fitted pixel.

Timeout:

(Optional) max processing time per pixel. If reached, the given pixel is passed (default None).

Note

Maps of the parameters of the fit can be found in the directory created by ORCS: OBJECT_NAME_FILTER.ORCS/MAPS/.

Each line has 5 parameters (which gives 5 maps): height, amplitude, velocity, fwhm, sigma. Height and amplitude are given in ergs/cm^2/s/A. Velocity and broadening are given in km/s. FWHM is given in cm^-1.

The flux map is also computed (from fwhm, amplitude and sigma parameters) and given in ergs/cm^2/s.

Each fitted parameter is associated an uncertainty (*_err maps) given in the same unit.

_fit_lines_in_spectrum(spectrum, theta_orig, snr_guess=None, max_iter=None, **kwargs)¶

Raw function for spectrum fitting.

Note

Need the InputParams class to be defined before call

(see _prepare_input_params()).

Parameters:

spectrum – The spectrum to fit (1d vector).
theta_orig – Original value of the incident angle in degree.
snr_guess – Guess on the SNR of the spectrum. Necessary to make a Bayesian fit (If unknown you can set it to ‘auto’ to try an automatic mode, two fits are made - one with a predefined SNR and the other with the SNR deduced from the first fit). If None a classical fit is made.
max_iter – (Optional) Maximum number of iterations (default None)
kwargs – (Optional) Model parameters that must be changed in the InputParams instance.

_get_data_prefix()¶: Return data prefix

_get_integrated_spectrum_fit_path(region_name)¶

Return the path to an integrated spectrum fit

Parameters:	region_name – Name of the region

_get_integrated_spectrum_header(region_name)¶

Return integrated spectrum header

Parameters:	region_name – Region name

_get_integrated_spectrum_path(region_name)¶

Return the path to an integrated spectrum

Parameters:	region_name – Name of the region

_get_reprojected_cube_path()¶: Return the path to the reprojected cube

_prepare_input_params(lines, nofilter=False, **kwargs)¶

prepare the InputParams instance for a fitting procedure.

Parameters:	lines – Emission lines to fit (must be in cm-1 if the cube is in wavenumber. must be in nm otherwise). nofilter – (Optional) If True, Filter model is not added and the fit is made with a single range set to the filter bandpass. kwargs – Keyword arguments of the function `orb.fit._prepare_input_params()`.

correct_wavelength(sky_map_path)¶

Correct the wavelength of the cube based on the velocity of the sky lines computed with map_sky_velocity()

Parameters:	sky_map_path – Path to the sky velocity map.

Warning

the sky velocity map returned by the function SpectralCube.map_sky_velocity is inversed (a velocity of 80 km/s is indicated as -80 km/s). It is thus more a correction map that must be directly added to the computed velocity to obtain a corrected velocity. As this map can be passed as is, it means that the given sky velocity map must be a correction map.

extract_integrated_spectrum(region, **kwargs)¶

Extract a spectrum integrated over a given region (can be a list of pixels as returned by the function numpy.nonzero() or a ds9 region file).

Parameters:	region – Region to integrate (can be a list of pixel coordinates as returned by the function `numpy.nonzero()` or the path to a ds9 region file). If it is a ds9 region file, multiple regions can be defined and all will be integrated into one spectrum.

extract_spectrum(x, y, r, **kwargs)¶

Extract a spectrum integrated over a circular region of a given radius.

Parameters:	x – X position of the center y – Y position of the center r – Radius. If 0, only the central pixel is extracted. kwargs – Keyword arguments of the function `_extract_spectrum_from_region()`.
Returns:	(axis, spectrum)

extract_spectrum_bin(x, y, b, **kwargs)¶

Extract a spectrum integrated over a binned region.

Parameters:	x – X position of the bottom-left pixel y – Y position of the bottom-left pixel b – Binning. If 1, only the central pixel is extracted kwargs – Keyword arguments of the function `_extract_spectrum_from_region()`.
Returns:	(axis, spectrum)

fit_lines_in_integrated_region(region, lines, nofilter=False, snr_guess=None, max_iter=None, subtract_spectrum=None, mean_flux=False, **kwargs)¶

Fit lines of a spectrum integrated over a given region (can be a list of pixels as returned by the function numpy.nonzero() or a ds9 region file).

Parameters:

region – Region to integrate (can be a list of pixel coordinates as returned by the function numpy.nonzero() or the path to a ds9 region file). If it is a ds9 region file, multiple regions can be defined and all will be integrated into one spectrum.
lines – Emission lines to fit (must be in cm-1 if the cube is in wavenumber. must be in nm otherwise).
nofilter – (Optional) If True, Filter model is not added and the fit is made with a single range set to the filter bandpass.
subtract_spectrum – (Optional) Remove the given spectrum from the extracted spectrum before fitting parameters. Useful to remove sky spectrum. Both spectra must have the same size.
snr_guess – Guess on the SNR of the spectrum. Necessary to make a Bayesian fit (If unknown you can set it to ‘auto’ to try an automatic mode, two fits are made - one with a predefined SNR and the other with the SNR deduced from the first fit). If None a classical fit is made.
max_iter – (Optional) Maximum number of iterations (default None)
mean_flux – (Optional) If True the flux of the spectrum is the mean flux of the extracted region (default False).
kwargs – Keyword arguments of the function _fit_lines_in_spectrum().

Returns:

a tuple (axis, spectrum, fit_dict). fit_dict is a dictionary containing the fit results (same output as _fit_lines_in_spectrum())

fit_lines_in_region(region, lines, binning=1, nofilter=False, subtract_spectrum=None, snr_guess=None, max_iter=None, timeout=None, **kwargs)¶

Fit lines in a given region of the cube. All the pixels in the defined region are fitted one by one and a set of maps containing the fitted paramaters are written. Note that the pixels can be binned.

Parameters:

lines – Emission lines to fit (must be in cm-1 if the cube is in wavenumber. must be in nm otherwise).
region – Region to fit. Multiple regions can be used to define the fitted region. They do not need to be contiguous.
nofilter – (Optional) If True, Filter model is not added and the fit is made with a single range set to the filter bandpass.
subtract_spectrum – (Optional) Remove the given spectrum from the extracted spectrum before fitting parameters. Useful to remove sky spectrum. Both spectra must have the same size.
snr_guess – Guess on the SNR of the spectrum. Can only be None or ‘auto’. Set it to ‘auto’ to make a Bayesian fit. In this case two fits are made - one with a predefined SNR and the other with the SNR deduced from the first fit. If None a classical fit is made.
max_iter – (Optional) Maximum number of iterations (default None)
kwargs – Keyword arguments of the function _fit_lines_in_spectrum().

Timeout:

(Optional) max processing time per pixel. If reached, the given pixel is passed (default None).

Note

You can pass the fitting parameters (e.g. pos_cov, sigma_cov etc.) as maps (a 2d numy.ndarray instance or a path to a map). But you have to append the suffix ‘_map’ to the parameter you want to map. Any nan or inf in the map will be replaced by the median of the map. This mode can be used to map parameters at a given binning from the result of the fit made at a higher binning.

fit_lines_in_spectrum(x, y, r, lines, nofilter=False, snr_guess=None, max_iter=None, subtract_spectrum=None, mean_flux=False, **kwargs)¶

Fit lines of a spectrum extracted from a circular region of a given radius.

Parameters:

x – X position of the center
y – Y position of the center
r – Radius. If 0, only the central pixel is extracted.
lines – Emission lines to fit (must be in cm-1 if the cube is in wavenumber. must be in nm otherwise).
nofilter – (Optional) If True, Filter model is not added and the fit is made with a single range set to the filter bandpass.
subtract_spectrum – (Optional) Remove the given spectrum from the extracted spectrum before fitting parameters. Useful to remove sky spectrum. Both spectra must have the same size.
snr_guess – Guess on the SNR of the spectrum. Necessary to make a Bayesian fit (If unknown you can set it to ‘auto’ to try an automatic mode, two fits are made - one with a predefined SNR and the other with the SNR deduced from the first fit). If None a classical fit is made.
max_iter – (Optional) Maximum number of iterations (default None)
mean_flux – (Optional) If True the flux of the spectrum is the mean flux of the extracted region (default False).
kwargs – Keyword arguments of the function _fit_lines_in_spectrum().

Returns:

a tuple (axis, spectrum, fit_dict). fit_dict is a dictionary containing the fit results (same output as _fit_lines_in_spectrum())

fit_lines_in_spectrum_bin(x, y, b, lines, nofilter=False, subtract_spectrum=None, snr_guess=None, max_iter=None, mean_flux=False, **kwargs)¶

Fit lines of a spectrum extracted from a squared region of a given size.

Parameters:

x – X position of the bottom-left pixel
y – Y position of the bottom-left pixel
b – Binning. If 0, only the central pixel is extracted.
lines – Emission lines to fit (must be in cm-1 if the cube is in wavenumber. must be in nm otherwise).
nofilter – (Optional) If True, Filter model is not added and the fit is made with a single range set to the filter bandpass.
subtract_spectrum – (Optional) Remove the given spectrum from the extracted spectrum before fitting parameters. Useful to remove sky spectrum. Both spectra must have the same size.
snr_guess – Guess on the SNR of the spectrum. Necessary to make a Bayesian fit (If unknown you can set it to ‘auto’ to try an automatic mode, two fits are made - one with a predefined SNR and the other with the SNR deduced from the first fit). If None a classical fit is made.
max_iter – (Optional) Maximum number of iterations (default None)
mean_flux – (Optional) If True the flux of the spectrum is the mean flux of the extracted region (default False).
kwargs – Keyword arguments of the function orb.fit.fit_lines_in_spectrum().

Returns:

a tuple (axis, spectrum, fit_dict). fit_dict is a dictionary containing the fit results (same output as orb.fit.fit_lines_in_spectrum())

get_amp_ratio_from_flux_ratio(line0, line1, flux_ratio)¶

Return the amplitude ratio (amp(line0) / amp(line1)) to define from the flux ratio (at constant fwhm and broadening).

Parameters:	line0 – Wavenumber of the line 0 (in cm-1). line1 – Wavenumber of the line 1 (in cm-1). flux_ratio – Flux ratio: flux(line0) / flux(line1).

get_calibration_coeff_map()¶: Return the calibration coeff map based on the calibration laser map and the laser wavelength.

get_calibration_coeff_map_orig()¶: Return the original calibration coeff map (not the version computed by get_calibration_coeff_map())

get_calibration_laser_map()¶: Return the calibration laser map of the cube

get_calibration_laser_map_orig()¶: Return the original calibration laser map (not the version computed by get_calibration_laser_map())

get_deep_frame()¶: Return deep frame if if exists. None if no deep frame is attached to the cube.

get_filter_range()¶: Return the range of the filter in the unit of the spectral cube as a tuple (min, max)

get_flux_uncertainty()¶

Return the uncertainty on the flux at a given wavenumber in erg/cm2/s/channel. It corresponds to the uncertainty (1 sigma) of the spectrum in a given channel.

Parameters:	wavenumber – Wavenumber (cm-1)

get_fwhm_map()¶: Return the theoretical FWHM map in cm-1 based only on the angle and the theoretical attained resolution.

get_header()¶: Return cube header.

get_mask_from_ds9_region_file(region, integrate=True)¶

Return a mask from a ds9 region file.

Parameters:	region – Path to a ds9 region file. integrate – (Optional) If True, all pixels are integrated into one mask, else a list of region masks is returned (default True)

get_radial_velocity_correction(kind='heliocentric', date=None)¶

Return heliocentric or barycentric velocity correction to apply on: the observed target in km/s

Parameters:	kind – (Optional) ‘heliocentric’ or ‘barycentric’ (default ‘heliocentric’). date – (Optional) Corrected date for the observation. Must be a string with the following format YYYY-MM-DDTHH:MM:SS.S (default None).

For m/s precision the returned float should simply be added. But more care must be taken if a better precision is needed. Please see http://docs.astropy.org/en/stable/api/astropy.coordinates.SkyCoord.html#astropy.coordinates.SkyCoord.radial_velocity_correction for more informations.

Returns:	(heliocentric or barycentric) velocities.