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 cm1 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 bottomleft pixel
 y – Y position of the bottomleft 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 cm1 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()
) region – Region to integrate (can be a list of pixel
coordinates as returned by the function

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 cm1 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 cm1 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 bottomleft pixel
 y – Y position of the bottomleft pixel
 b – Binning. If 0, only the central pixel is extracted.
 lines – Emission lines to fit (must be in cm1 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 cm1).
 line1 – Wavenumber of the line 1 (in cm1).
 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 (cm1)

get_fwhm_map
()¶ Return the theoretical FWHM map in cm1 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 YYYYMMDDTHH: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. See also
This is based on the astropy methods. See
http://docs.astropy.org/en/stable/coordinates/velocities.html for more information on how to use the returned quantities.

get_sky_lines
()¶ Return the wavenumber/wavelength of the sky lines in the filter range

get_theta_map
()¶ Return the incident angle map (in degree)

get_wcs
()¶ Return the WCS of the cube as a astropy.wcs.WCS instance

get_wcs_header
()¶ Return the WCS of the cube as a astropy.wcs.WCS instance

pix2world
(xy, deg=True)¶ Convert pixel coordinates to celestial coordinates
Parameters:  xy – A tuple (x,y) of pixel coordinates or a list of tuples ((x0,y0), (x1,y1), …)
 deg – (Optional) If true, celestial coordinates are returned in sexagesimal format (default False).
Note
it is much more effficient to pass a list of coordinates than run the function for each couple of coordinates you want to transform.

reproject
()¶ Reproject data cube in a distorsionless WCS.
Warning
The amount of available RAM must be larger than the cube size on disk.

reset_calibration_coeff_map
()¶ Reset the computed calibration coeff map alone

reset_calibration_laser_map
()¶ Reset the compute calibration laser map (and also the calibration coeff map). Must be called when the wavelength calibration has changed
..seealso ::
correct_wavelength()

reset_params
()¶ Read header again and reset parameters

set_dxdymaps
(dxmap_path, dymap_path)¶ Set microshift maps returned by the astrometrical calibration method.
Parameters:  dxmap_path – Path to the dxmap.
 dymap_path – Path to the dymap.

set_header
(hdr)¶ Set cube header

set_wcs
(wcs_path)¶ Reset WCS of the cube.
Parameters: wcs_path – Path to a FITS image containing the new WCS.

world2pix
(radec, deg=True)¶ Convert celestial coordinates to pixel coordinates
Parameters: xy – A tuple (x,y) of celestial coordinates or a list of tuples ((x0,y0), (x1,y1), …). Must be in degrees. Note
it is much more effficient to pass a list of coordinates than run the function for each couple of coordinates you want to transform.


class
orcs.core.
LineMaps
(dimx, dimy, lines, wavenumber, binning, div_nb, project_header=None, wcs_header=None, **kwargs)¶ Bases:
orb.core.Tools
Manage line parameters maps

__init__
(dimx, dimy, lines, wavenumber, binning, div_nb, project_header=None, wcs_header=None, **kwargs)¶ Init class
Parameters:  dimx – X dimension of the unbinned data
 dimy – Y dimension of the unbinned data
 lines – tuple of the line names
 wavenumber – True if the data is in wavenumber, False if it is in wavelength.
 binning – Binning of the data.
 div_nb – Number of divisions if the data is binned in quadrant mode.
 project_header – (Optional) FITS header passed to the written frames (default None).
 wcs_header – (Optional) WCS header passed to the written frames (default None).
 kwargs – Kwargs are
__init__()
kwargs.

_add_wcs_header
(hdr)¶ Add WCS header keywords to a header.
Parameters: hdr – Header to update

_get_map_header
(file_type, comment=None)¶ Return map header
Parameters:  file_type – Type of file
 comment – (Optional) Comments on the file type (default None).

_get_map_path
(line_name, param, binning=None)¶ Return the path to a map of one gaussian fit parameter for one given emission line.
Parameters:  line_name – Name of the emission line
 param – Parameter name
 binning – (Optional) Binning of the map. If not given instance binning is used (default None).

get_map
(param, x_range=None, y_range=None)¶ Get map values
Parameters:  param – Parameter
 x_range – (Optional) Data range along X axis (default None)
 y_range – (Optional) Data range along Y axis (default None)

set_map
(param, data_map, x_range=None, y_range=None)¶ Set map values.
Parameters:  param – Parameter
 data_map – Data
 x_range – (Optional) Data range along X axis (default None)
 y_range – (Optional) Data range along Y axis (default None)

write_maps
()¶ Write all maps to disk.
