The pycube API reference

pycube

The cubeClass class

Import modules useful for analyzing MUSE data and handling FITS files

The psf module

Module to create and subtract PSF model from MUSE cubes

pycube.psf.background_cube(datacontainer, sig_source_detect=3.0, min_source_area=12.0, source_mask_size=6.0, edges=50)

Creates two datacubes from an original IFUcube. One cube is the smoothed background with removed sources. The second is the associated mask used for to create the first cube.

Parameters:

• datacontainer (IFUcube object) – data initialized in cubeClass

• sig_source_detect (float, int, optional) – value of source significance to be detected (default is 3.)

• min_source_area (float, int, optional) – minimum area of sources to be considered for masking (default is 12.)

• source_mask_size (float, int, optional) – mask size (default is 6.)

• edges (int, float) – pixel count to be removed from the edges of the image (default is 50)

Returns:

• cube_bg (np.array) – data cube of the mask removed background

• mask_bg (np.array) – data cube of the masks implemented

pycube.psf.clean_fg(datacontainer, min_lambda=None, max_lambda=None, mask_z=None, mask_x=None, mask_y=None, mask_xy_rad=None, sig_source_detect=5.0, min_source_area=16.0, mask_size=6.0, max_source_size=50.0, max_source_ell=0.9, bg_source=False, rad_norm=1.0, edges=60, output='Object', debug=False, show_debug=False, deep_debug=False)

This macro removes sources from a cube creating a model from the data itself. The model will be created collapsing the cube between min_lambda and max_lambda (considering mask_z as mask for bad channels). The macro will search for sources in the image, and create a normalized model for each of them. Finally, the model is propagated in the entire cube and then removed.

Parameters:

• datacontainer (IFUcube object) – data intialized in cubeClass.py

• min_lambda (int) – min channel to create the image where to detect sources

• max_lambda (int) – max channel to create the image where to detect sources

• mask_z (np.array) – array of channels, when 1 (or True), the channel is removed

• mask_x (floats) – x,y location of a source NOT to be subtracted as f/g model. Any sources located within mask_xy_rad from mask_x, maskY will not be considered in the creation of the model.

• mask_y (floats) – x,y location of a source NOT to be subtracted as f/g model. Any sources located within mask_xy_rad from mask_x, maskY will not be considered in the creation of the model.

• mask_xy_rad (floats) – x,y location of a source NOT to be subtracted as f/g model. Any sources located within mask_xy_rad from mask_x, maskY will not be considered in the creation of the model.

• sig_source_detect (float) – detection sigma threshold for sources in the collapsed cube. Defaults is 5.0

• min_source_area (float) – min area for source detection in the collapsed cube. Default is 16.

• mask_size (float) – for each source, the model will be created in an elliptical aperture with size source_mask_size time the semi-minor and semi-major axis of the detection. Default is 6.

• max_source_size (float) – sources with semi-major or semi-minor axes larger than this value will not be considered in the foreground source model. Default is 50.

• max_source_ell (float) – sources with ellipticity larger than this value will not be considered in the foreground source model. Default is 0.9.

• bg_source (bool) – if True, an additional local background subtraction will be performed around each detected sources. Default is True

• rad_norm (float) – radius where to normalize the sources model. Default is 1.

• edges (int) – frame size removed to avoid problems related to the edge of the image

• output (string) – root file name for outputs

• debug (boolean, optional) – runs debug sequence to display output of function (default False)

• show_debug (boolean, optional) – runs debug sequence to display output of function (default False)

• deep_debug (boolean, optional) – runs debug sequence to display output of function (default False)

Returns:

datacopy_clean, datacopy_model – data cube from which the detected sources have been removed and the model of fg cleaning

Return type:

np.array

fg_sourcesdict

Dictionary containing relevant information on the detected sources including data, masks, flux, etc.

pycube.psf.clean_psf(datacontainer, psf_model, x_pos, y_pos, statcube=None, radius_pos=2.0, inner_rad=10.0, outer_rad=15.0, bg_psf=True, debug=False, show_debug=False)

Given a cube and a PSF model, the macro subtracts the PSF contribution along the wavelength axis. It assumes that the PSF model is normalized to one within rad_psf and that the PSF model is centered in the same location of the object you want to remove. This will be improved in the future.

Parameters:

• datacontainer (IFUcube object) – Data initialized in cubeClass.py

• psf_model (np.array) – array from running makePsf to be reduced in this function

• x_pos (float) – x-location of the source in pixel

• y_pos (float) – y-location of the source in pixel

• statcube (np.array, optional) – 3D variance array, can be accessed from datacontainer if an IFUcube object is called

• radius_pos (float) – radius where to perform the aperture photometry to remove the PSF contribution (default is 2.)

• inner_rad (float) – inner radius of the background region in pixel (default is 10.)

• outer_rad (float) – outer radius of the background region in pixel (default is 15.)

• bg_psf (bool) – if True, an additional local background subtraction will be performed around the source (default is True)

• debug (boolean, optional) – runs debug sequence to display output of function (default False)

• show_debug (boolean, optional) – runs debug sequence to display output of function (default False)

Returns:

psf_cube, psf_cube_model – PSF subtracted cube and PSF model cube

Return type:

np.array

pycube.psf.create_psf(datacontainer, x_pos, y_pos, statcube=None, min_lambda=None, max_lambda=None, mask_z=None, radius_pos=2.0, inner_rad=10.0, outer_rad=15.0, rad_psf=50.0, c_type='sum', norm=True, debug=False, show_debug=False)

Given an IFUcube, or 3D data and variance arrays, the macro collapses it’s data and variance along the z-axis between min_lambda and max_lambda. If mask_z is given, channels masked as 1 (or True) are removed. if c_type is set to ‘average’, the macro uses the stat information to perform a weighted mean along the velocity axis. In other words, each spaxel of the resulting image will be the weighted mean spectrum of that spaxels along the wavelengths. If norm is ‘True’ the macro normalize the flux of the PSF within radius_pos = 1.

Parameters:

• datacontainer (IFUcube Object, np.array) – data initiated in cubeClass.py, or 3D data array

• x_pos (float) – x-location of the source in pixel

• y_pos (float) – y-location of the source in pixel

• statcube (np.array, optional) – variance data array, optional if headers is IFUcube

• min_lambda (int, optional) – min channel to create collapsed image (default is None)

• max_lambda (int, optional) – max channel to create collapsed image (default is None)

• mask_z (np.array) – array of channels, when 1 (or True), the channel is removed (default is None)

• radius_pos (float) – radius where to perform the aperture photometry (default is 2.)

• inner_rad (float) – inner radius of the background region in pixels (default is 10.)

• outer_rad (float) – outer radius of the background region in pixels (default is 15.)

• rad_psf (float) – radius of the PSF image to be created. Outside these pixels values are set to zero (default is 50.)

• c_type (str) – type of combination for PSF creation: ‘average’ is weighted average ‘sum’ is direct sum of all pixels

• norm (bool) – if ‘True’ normalizes the central regions of the PSF to 1 (default is True)

• debug (boolean, optional) – runs debug sequence to display output of function (default False)

• show_debug (boolean, optional) – runs debug sequence to display output of function (default False)

Returns:

psfData, psfStat – PSF data and variance images

Return type:

np.array

pycube.psf.find_sources(datacontainer, statcube=None, min_lambda=None, max_lambda=None, mask_z=None, var_factor=5.0, threshold=4.0, sig_detect=2.0, min_area=3.0, deblend_val=0.005)

Automated scanning of given data and identifies good sources. If data is in 3D format, function will collapse given along lambda parameters

Parameters:

• datacontainer (np.array, IFUcube object) – 3D data cube of or data file initialized in cubeClass.py

• statcube (np.array, optional) – 3D variance of data, assumes IFUcube for datacube (default is None)

• min_lambda (float) – minimum wavelength value to collapse 3D image (default is None)

• max_lambda (float) – maximum wavelength value to collapse 3D image (default is None)

• mask_z (np.array) – range of z-axis values that the user can mask in the datacube during collapsing (default is None)

• var_factor (int, float, optional) – affects generated variance, if variance is auto-generated from image data (default is 5.)

• threshold (int, float, optional) – threshold value for sigma detection with seXtractor background subtraction (default is 4.)

• sig_detect (int, float, optional) – minimum signal detected by function (default is 2.)

• min_area (int, float, optional) – minimum area determined to be a source (default is 3.)

• deblend_val (float, optional) – value for sep extractor, minimum contrast ratio for object blending (default is 0.005)

Returns:

• x_pos (np.array) – x positions of objects

• y_pos (np.array) – y positions of objects

• maj_axis (np.array) – semi-major axis value of objects

• min_axis (np.array) – semi-minor axis of objects

• angle (np.array) – angle for elliptical masking

• all_objects (np.array) – directory for all objects found and their values

pycube.psf.sources_fg(datacube, statcube=None, sig_source_detect=5.0, min_source_area=16.0, source_mask_size=6.0, max_source_size=50.0, max_source_ell=0.9, rad_norm=1.0, edges=60, output='Object', debug=False, show_debug=False)

This macro search for sources in an image and save relevant information on them in a dictionary.

Parameters:

• datacube (np.array) – data in a 2D array

• statcube (np.array) – variance in a 2D array

• sig_source_detect (float) – detection sigma threshold for sources in the collapsed cube. Defaults is 5.0

• min_source_area (float) – min area for source detection in the collapsed cube. Default is 16.

• source_mask_size (float) – for each source, the model will be created in an elliptical aperture with size source_mask_size time the semi-minor and semi-major axis of the detection. Default is 6.

• max_source_size (float) – sources with semi-major or semi-minor axes larger than this value will not be considered in the foreground source model. Default is 50.

• max_source_ell (float) – sources with ellipticity larger than this value will not be considered in the foreground source model. Default is 0.9.

• rad_norm (float) – radius where to normalize the sources model. Default is 1.

• edges (int) – frame size removed to avoid problems related to the edge of the image

• output (string) – root file name for outputs

• debug (boolean, optional) – runs debug sequence to display output of function (default False)

• show_debug (boolean, optional) – runs debug sequence to display output of function (default False)

Returns:

• fgSources (dict) – Dictionary containing relevant information on the detected sources including data, masks, flux, etc.

• fgAllSources (astropy table) – Astropy table containing the information of all sources detected (i.e. without any cleaning). This is the direct output of the source finding algorithm.

• fgBackgroundFlux, fgBackgroundSigma (float) – Average background flux and sigma after source extractions

pycube.psf.stat_bg(datacontainer, statcube=None, min_lambda=None, max_lambda=None, mask_z=None, mask_xy=None, sig_source_detect=5.0, min_source_area=16.0, source_mask_size=6.0, edges=60, output='Object', sigma_clipping=False, debug=False, show_debug=False)

This estimates the sky background of a MUSE cube after removing sources. Sources are detected in an image created by collapsing the cube between min_lambda and max_lambda (considering mask_z as mask for bad channels). Average, std, and median are saved.

Parameters:

• datacontainer (IFUcube object, np.array) – data initialized in cubeClass.py or 3D data array

• statcube (np.array, optional) – 3D variance array (default is None)

• min_lambda (int, optional) – min channel to create the image where to detect sources

• max_lambda (int, optional) – max channel to create the image where to detect sources

• mask_z (np.array, optional) – array of channels, for collapse function to remove channels masked as 1 or True (default is None)

• mask_xy (int, bool, optional) – when 1 (or True), this spatial pixel will remove from the estimate of the b/g values (default is None)

• sig_source_detect (float, optional) – detection sigma threshold for sources in the collapsed cube (default is 5.0)

• min_source_area (float, optional) – min area for source detection in the collapsed cube (default is 16)

• source_mask_size (float, optional) – for each source, the model will be created in an elliptical aperture with size source_mask_size time the semi-minor and semi-major axis of the detection (default is 6.)

• edges (int, optional) – frame size removed to avoid problems related to the edge of the image (default is 60)

• output (string) – root file name for output (default is ‘Object’)

• sigma_clipping (boolean, optional) – Specifies whether sigma clipping of the data is necessary. Iterates through data and removes values significantly distant from the standard deviation High variance in correction value output may be corrected using this (default is False)

• debug (boolean, optional) – runs debug sequence to display output of function (default False)

• show_debug (boolean, optional) – runs debug sequence to display output of function (default False)

Returns:

• average_bg, median_bg, std_bg, var_bg, pixels_bg (np.array) – average, median, standard deviation, variance, and number of pixels after masking sources, edges, and NaNs of the background.

• mask_bg_2D (np.array) – 2D mask used to determine the background region. This mask has 1 if there is a source or is on the edge of the cube. It is 0 if the pixel is considered in the background estimate.

pycube.psf.subtract_bg(datacontainer, min_lambda=None, max_lambda=None, mask_z=None, mask_xy=None, sig_source_detect=5.0, min_source_area=16.0, source_mask_size=6.0, edges=60, output='Object', sigma_clipping=False, debug=False, show_debug=False)

This macro remove residual background in the cubes and fix the variance

vector after masking sources. Sources are detected in an image created by collapsing the cube between min_lambda and max_lambda (considering mask_z as mask for bad channels). If statcube is none, it will be created and for each channel, the variance of the background will be used.

Parameters:

• datacontainer (IFUcube object) – data initialized in cubeClass.py

• min_lambda (int) – min channel to create the image to detected sources

• max_lambda (int) – max channel to create the image to detected sources

• mask_z (np.array) – array of channels, when 1 (or True), the channel is removed when collapsing the cube to detect sources (default is None)

• mask_xy (int, bool, optional) – when 1 (or True), this spatial pixel will be removed from the estimate of the b/g values (default is None)

• sig_source_detect (float) – detection sigma threshold for sources in the collapsed cube (default is 5.0)

• min_source_area (float) – min area for source detection in the collapsed cube (default is 16.)

• source_mask_size (float) – for each source, the model will be created in an elliptical aperture with size source_mask_size time the semi-minor and semi-major axis of the detection (default is 6.)

• edges (int) – frame size removed to avoid problems related to the edge of the image (default is 60)

• output (string) – root file name for outputs

• sigma_clipping (boolean, optional) – Specifies whether sigma clipping of the data is necessary. Iterates through data and removes values significantly distant from the standard deviation High variance in correction value output may be corrected using this (default is False)

• debug (boolean, optional) – runs debug sequence to display output of function (default False)

• show_debug (boolean, optional) – runs debug sequence to display output of function (default False)

• Returns –

• ------- –

• datacube (np.array) – 3D data and variance cubes after residual sky subtraction and variance rescaled to match the background variance.

• statcube (np.array) – 3D data and variance cubes after residual sky subtraction and variance rescaled to match the background variance.

• bg_average (np.array) – average, median, standard deviation, variance, and number of pixels after masking sources, edges, and NaNs of the background.

• bg_median (np.array) – average, median, standard deviation, variance, and number of pixels after masking sources, edges, and NaNs of the background.

• bg_std (np.array) – average, median, standard deviation, variance, and number of pixels after masking sources, edges, and NaNs of the background.

• bg_var (np.array) – average, median, standard deviation, variance, and number of pixels after masking sources, edges, and NaNs of the background.

• bg_pixels (np.array) – average, median, standard deviation, variance, and number of pixels after masking sources, edges, and NaNs of the background.

• bg_mask_2d (np.array) – 2D mask used to determine the background region. This mask has 1 if there is a source or is on the edge of the cube. It is 0 if the pixel is considered in the background estimate.

The halos module

Module to search extended emission in PSF subtracted MUSE cubes

pycube.halos.clean_mask_halo(mask_halo, delta_z_min=2, min_vox=100, min_channel=None, max_channel=None, debug=False, show_debug=False)

Given the halo mask, the macro performs some quality check: * If a spatial pixel (x,y) has less than delta_z_min consecutive voxels identified along the z-axis, it will be removed from the mask * If the total number of voxels is less than min_vox the halo is considered as not detected and the mask is cleaned.

Parameters:

• mask_halo (np.array) – 3D mask of the halo location.

• delta_z_min (int, optional) – min size in the spectral axis to consider the voxel as part of the halo

• min_vox (int, optional) – voxel detection threshold value. If the number of voxels is less than this parameter, the halo is not to be detected (default 100)

• min_channel (np.array) – only voxels between channelMin and max_channel in the spectral direction will be considered in the creation of the cleanMask

• max_channel (np.array) – only voxels between channelMin and max_channel in the spectral direction will be considered in the creation of the cleanMask

• debug (boolean, optional) – runs debug sequence to display output of function (default False)

• show_debug (boolean, optional) – runs debug sequence to display output of function (default False)

Returns:

mask_halo_cleaned – cleaned 3D mask of the halo location.

Return type:

np.array

pycube.halos.halo_mask(chi_cube, x_pos, y_pos, z_pos, rad_bad_pix, rad_max, r_connect=2, threshold=2.0, threshold_type='relative', bad_pixel_mask=None, n_sigma_extreme=5.0, output='Object', debug=False, show_debug=False)

Given a PSF subtracted data cube (either smoothed or not) this macro, after masking some regions, performs a friends of friends search for connected pixels above a certain threshold in S/N. The first step is to identify the most significant voxel in proximity to the quasar position (given as x_pos, y_pos, z_pos). The code assumes that the position of the extended halo is known and proceeds to create the mask of connected pixels from this point and from the most significant voxel within a spherical radius of 3.*rad_bad_pix from (x_pos, y_pos, z_pos). From there the macro searches for neighbor pixels that are above the threshold and creates a mask for the extended emission.

Parameters:

• chi_cube (np.array) – 3D X cube output of smoothChiCube. This is constructed as data/noise (or as smooth(data)/smooth(noise)).

• x_pos (float) – position from where start to search for the presence of a halo. This is the position of the quasar in x and y and the expected position of the extended halo at the quasar redshift in z.

• y_pos (float) – position from where start to search for the presence of a halo. This is the position of the quasar in x and y and the expected position of the extended halo at the quasar redshift in z.

• z_pos (float) – position from where start to search for the presence of a halo. This is the position of the quasar in x and y and the expected position of the extended halo at the quasar redshift in z.

• rad_bad_pix (int) – radius of the circular region centred in x_pos, y_pos that will be masked. This is typically due to the absence of information at the quasar location caused by the normalization of the empirical PSF model to the central region.

• rad_max (int) – the circular region centred in x_pos and y_pos with radius rad_max will be masked and not considered in the search of extended emission. This helps to prevent boundary problems and to speed up the algorithm.

• r_connect (int) – default is r_connect=2. Connecting distance used in the FoF algorithm.

• threshold (float) – S/N threshold to consider a pixel as part of the extended emission. Default is 2.

• threshold_type (str) – ‘relative’: A pixel will be considered as a part of a halo if it is above ‘threshold’ times the sigma of the distribution of S/N of the pixels. ‘absolute’ : A pixel will be considered as a part of a halo if it is above the value of ‘threshold’.

• bad_pixel_mask (np.array, or mask of boolean) – 2D mask to remove spatial pixels from the estimate of the halo location. If 1 (or True) the spatial pixel will be removed.

• n_sigma_extreme (float, optional) – parameter for statFullCube and statFullCubeZ: if not None, voxels with values larger than sigmaExtreme times the standard deviation of the cube will be masked (default is 5.)

• output (string) – root file name for outputs

• debug (boolean, optional) – runs debug sequence to display output of function (default False)

• show_debug (boolean, optional) – runs debug sequence to display output of function (default False)

Returns:

mask_halo – mask where the detected extended emission is set to 1 and the background is set to 0. It has the same shape of the input chi_cube.

Return type:

np.array

pycube.halos.make_moments(datacontainer, psf_data, sub_stat, mask_halo, central_wave=None, s_smooth=None, truncate=5.0, debug=False, show_debug=False)

Given a PSF-Subtracted datacube, this macro extracts the moment 0, 1, 2 maps of the halo identified by mask_halo. Where:

mom0: is the integrated value

\[mom0 = sum[Flux*dlambda]\]

where sum is the sum along the channels

mom1: is the velocity field

\[mom1 = sum[DV*Flux] / sum[Flux]\]

where DV is the velocity difference of a channel from the centralWave

\[DV = (wavelength - centralWave) / centralWave * speed of light\]

mom2: is the velocity dispersion

\[mom2 = sqrt[ sum[ Flux*(DV-mom1)**2. ] / sum[Flux] ]\]

Parameters:

• datacontainer (fits object) – header file of datacube read in (ex. can use IFUcube.get_primary(), or s_data_headers)

• psf_data (np.array) – PSF subtracted data cube

• sub_stat (np.array) – background subtracted variance cube

• mask_halo (np.array) – mask where the detected extended emission is set to 1 and the background is set to 0. It has the same shape of the input datacube.

• central_wave (float) – wavelength in Ang. from which to calculate the velocity shifts. If None, the macro will calculate it from the spectrum of the halo.

• s_smooth (float) – smooth length in pixel in the spatial direction

• truncate (float) – number of sigma after which the smoothing kernel is truncated

• debug (boolean, optional) – runs debug sequence to display output of function (default False)

• show_debug (boolean, optional) – runs debug sequence to display output of function (default False)

Returns:

• mom0, mom1, mom2 (np.array) – moment maps in 2D arrays. Units for mom0 is flux, while units of mom1 and mom2 is velocity

• central_wave (float) – wavelength in Ang. from which the velocity shifts are calculated. It is equal to the input wavelength if not set to None.

pycube.halos.maxExtent(mask_halo_2D, x_pos=None, y_pos=None)

Given a 2D mask halo, the macro calculates the maximum extend of the halo in the spatial direction and the maximum distance from x_pos, y_pos (if given).

Parameters:

• mask_halo_2D (np.array) – 2D mask of the halo location

• x_pos (int, float, optional) – pixel maximums to limit the extended halo range

• y_pos (int, float, optional) – pixel maximums to limit the extended halo range

Returns:

• maxExtent (float) – maximum extent in pixels

• fromPixExtent (float) – maximum extent from (x_pos, y_pos) in pixels

pycube.halos.smooth_chicube(datacontainer, min_lambda, max_lambda, statcube=None, s_smooth=1.0, v_smooth=1.0, truncate=5.0)

Given a (PSF subtracted) IFUcube, the macro smooth both the datacube and the statcube with a 3D gaussian Kernel. The same sigma is considered in both spatial axes (a_smooth), while a different one can be set for the spectral axis (v_smooth).Note that the ‘stat’ cube is convolved as convol^2[statcube]. The smoothChiCube is than created as:

\[sChiCube = \frac{convol[datacube]}{\sqrt{(convol^2[statcube])}}\]

The chi_cube is simply:

\[chi\_cube = \frac{datacube}{\sqrt{(statcube)}}\]

Given that scipy has hard time to deal with NaNs, NaNs values in the dataCube are converted to zeroes, while the NaNs in the statCube to nanmax(statcube).

Parameters:

• datacontainer (IFUcube, np.array) – data initialized in cubeClass.py, or data in 3D array resulting from subtract_bg

• min_lambda (int) – minimum wavelength to collapse data

• max_lambda (int) – maximum wavelength to collapse data

• statcube (np.array, optional) – variance in 3D array, resulting array from subtract_bg

• s_smooth (float) – smooth length in pixel in the spatial direction

• v_smooth (float) – smooth length in pixel in the velocity direction

• truncate (float) – number of sigma after which the smoothing kernel is truncated

Returns:

chi_cube, sChiCube – X-cube and smoothed X-cube

Return type:

np.array

pycube.halos.spectral_mask_halo(mask_halo)

Given the halo mask, this macro returns a 2D mask in x and y and the min and max channel where the halo is detected in the z-axis.

Parameters:

mask_halo (np.array) – 3D mask of the halo location.

Returns:

• mask_halo_2D (np.array) – 2D mask of the halo location (collapsed along the z-axis).

• mask_halo_min_z, mask_halo_max_z (int) – min and max channel where the halo is detected along the z-axis

pycube.core

The background module

pycube.core.background.median_background(datacontainer)

Backgrounds should only be implemented on 2D array. For 3D files, collapse to a desired dimension before passing function. -> default background taking median of 2D data

Parameters:

datacontainer (2D array) – Collapsed data to calculate background from

Returns:

Median value of datacube’s background ignoring NaNs.

Return type:

float

pycube.core.background.sextractor_background(datacontainer, statcube, var_value)

Backgrounds should only be implemented on 2D array. For 3D files, collapse to a desired dimension before passing function. -> Performs SEP function https://github.com/kbarbary/sep to set up background.

Parameters:

• datacontainer (np.array) – Collapsed 2D array of 3D data

• statcube (np.array) – 2D stat array converted in function

• var_value (int, float) – Affects the threshold parameter for normalizing the mask

Returns:

SExtractor adjusted background of 2D array

Return type:

SEP object

The manip module

Module of helpful functions to aid PSF subtraction and emission searching modules in pycube

pycube.core.manip.annular_mask(data_flat, x_pos, y_pos, semi_maj=5.0, semi_min=5.0, delta_maj=2.0, delta_min=2.0, theta=0.0)

Returning a mask where annuli centered in x_pos and y_pos with inner axis (semi_maj, semi_min) and with outer axis (semi_maj + delta_maj, semi_min + delta_min) are marked as 1.

Parameters:

• data_flat (np.array) – data in a 2D array. The mask will have the same size of this.

• x_pos (np.array) – x-location of the sources in pixels

• y_pos (np.array) – y-location of the sources in pixels

• semi_maj (float, optional) – inner semi-major axis in pixel (default is 5.)

• semi_min (float, optional) – inner semi-minor axis in pixel (default is 5.)

• delta_maj (float, optional) – width of the semi-major axis in pixel (default is 2.)

• delta_min (float, optional) – width of the semi-minor axis in pixel (default is 2.)

• theta (float, optional) – angle wrt the x-axis in degrees (default is 0.)

Returns:

mask where sources are marked with 1 and background with 0. It has the same dimensions of the input datacube

Return type:

np.array

pycube.core.manip.channel_array(datacube, channel)

Given a 3D data cube, and a channel (x,y,z), creates a numpy array of values of channel range

Parameters:

• datacube (np.array) – 3D datacube to create range of channel values

• channel (str) – Dimension to create array from

Returns:

Range array of length of given dimension

Return type:

np.array

pycube.core.manip.collapse_container(datacontainer, min_lambda=None, max_lambda=None, mask_z=None, var_thresh=5.0)

Given an IFUcube, this function collapses along the z-axis given a range of values. If mask_z is specified, it will remove values masked as 1. If no variance (stat) data exists, it will be generated from the data.

Parameters:

• datacontainer (IFUcube object) – data passed through cubeClass.py

• min_lambda (int, optional) – Minimum wavelength

• max_lambda (int, optional) – Maximum wavelength

• mask_z (np.array, optional) – range of z-axis values that the user can mask in the datacube

• var_thresh (int, float, optional) –

  if no variance in container, this value determines standard deviation threshold

  to create variance cube from data (default is 5.)

Returns:

Condensed 2D array of 3D file.

Return type:

np.array

pycube.core.manip.collapse_cube(datacube, min_lambda=None, max_lambda=None, mask_z=None)

Given a 3D data/stat cube .FITS file, this function collapses along the z-axis given a range of values. If mask_z is specified, the function will remove all channels masked as 1.

Parameters:

• datacube (np.array) – 3D data cube

• min_lambda (int, optional) – Minimum wavelength to collapse file

• max_lambda (int, optional) – Maximum wavelength to collapse file

• mask_z (np.array, optional) – range of z-axis values to mask when collapsing

Returns:

Condensed 2D array of 3D file.

Return type:

np.array

pycube.core.manip.collapse_mean_container(datacontainer, min_lambda=None, max_lambda=None, mask_z=None, threshold=5.0)

Given an IFUcube, collapse it along the z-axis between min_lambda and max_lambda. If mask_z is given, channels masked as 1 (or True) are removed. The macro uses the stat information to perform a weighted mean along the velocity axis. In other words, each spaxel of the resulting image will be the weighted mean spectrum of that spaxels along the wavelengths.

Parameters:

• datacontainer (IFUcube object) – data passed through cubeClass.py

• min_lambda (int, optional) – minimum wavelength to collapse cube

• max_lambda (int, optional) – maximum wavelength to collapse cube

• mask_z (np.array, optional) – if specified, will remove channels masked with 1

• threshold (int, float, optional) – if no variance file in data, variance is created from the data. Parameter changes threshold of standard deviation for the creation of this variance (default is 5.)

Returns:

collapsed data and variance

Return type:

np.array

pycube.core.manip.collapse_mean_cube(datacube, statcube, min_lambda=None, max_lambda=None, mask_z=None)

Given 3D arrays of data and variance, this function collapses it along the z-axis between min_lambda and max_lambda. If mask_z is given, channels masked as 1 (or True) are removed. The macro uses the stat information to perform a weighted mean along the velocity axis. In other words, each spaxel of the resulting image will be the weighted mean spectrum of that spaxels along the wavelengths.

Parameters:

• datacube (np.array) – 3D data file

• statcube (np.array) – 3D variance file

• min_lambda (int) – minimum wavelength to collapse cube

• max_lambda (int) – maximum wavelength to collapse cube

• mask_z (np.array) – if specified, channels masked as 1 will be removed when collapsed

Returns:

2D collapsed and averaged data and variance cubes

Return type:

np.arrays

pycube.core.manip.convert_to_channel(datacontainer, datacube, channels='z')

Converts wavelength values in 3D MUSE data into channel value along z axis Specifically works with .FITS formatted MUSE data.

Parameters:

• datacontainer (IFUcube) – data initialized in cubeClass.py

• datacube (np.array) – 3D data array to be converted to channel

• channels (str, optional) – Channel dimension (‘x’, ‘y’, ‘z’ or ‘X’, ‘Y’, ‘Z’) to create channel range array (default: ‘z’)

Returns:

An array of channel values for given wavelength

Return type:

np.array

pycube.core.manip.convert_to_wave(datacontainer, datacube, channels='z')

Converts channel values in 3D MUSE data into wavelength values along z axis (wavelength). Specifically works with .FITS formatted MUSE data. Utilizes header vals (‘CRVAL3’ and ‘CD3_3’)

Parameters:

• datacontainer (IFUcube object) – data initialized in cubeClass.py

• datacube (np.array) – 3D array to be converted to wavelengths

• channels (str, optional) – Channel dimension (‘x’, ‘y’, ‘z’ or ‘X’, ‘Y’, ‘Z’) to create wavelength range array (default: ‘z’)

Returns:

An array of wavelength values for given channel

Return type:

np.array

pycube.core.manip.dust_correction(datacontainer)

Function queries the IRSA dust map for E(B-V) value and returns a reddening array. Works along z-axis of datacube http://irsa.ipac.caltech.edu/applications/DUST/ The query return E(B_V) from SFD (1998). This will be converted to the S&F (2011) one using: E(B-V)S&F = 0.86 * E(B-V)SFD

Parameters:

datacontainer (np.array) – 3D .fits file array / IFU cube object

Returns:

reddata, redstat – galactic dust corrected 3D arrays for data and variance

Return type:

np.array

pycube.core.manip.find_sigma(data)

Simple expression to calculate Sigma quickly. Taking square root of the median value of an array.

Parameters:

data (np.array) – 2D array of interest to generate sigma value

Returns:

Sigma value of given 2D array, ignoring NaNs

Return type:

float

pycube.core.manip.gaussian(x, norm, x0, sigma)

Returns gaussian given normalization, center, and sigma.

Parameters:

• x (np.array) – x-vector

• norm (float) – Normalization, center, and sigma of the gaussian

• x0 (float) – Normalization, center, and sigma of the gaussian

• sigma (float) – Normalization, center, and sigma of the gaussian

Returns:

gauss – The gaussian curve evaluated in x

Return type:

np.array

pycube.core.manip.location(data_flat, x_position=None, y_position=None, semi_maj=None, semi_min=None, theta=0.0)

User input function to create elliptical mask of given coordinates for a source in an image. Works also for multiple position inputs to create a mask of all sources present.

Parameters:

• data_flat (np.array) – 2D collapsed image

• x_position (int, float, optional) – User given x coord of stellar object

• y_position (int, float, optional) – User given y coord of stellar object

• semi_maj (int, float, optional) – Semi-major axis (default is 10)

• semi_min (int, float, optional) – Semi-minor axis default (default is 6)

• theta (int, float, optional) – Angle for ellipse rotation around object (default is 0)

Returns:

Mask of 2D array of with user defined stellar objects denoted as 1 with all other elements 0

Return type:

np.array

pycube.core.manip.nice_plot()

Universal plotting parameters in place for debug outputs of functions

pycube.core.manip.object_coord(datacontainer, ra, dec, radius)

Reads in IFUcube and user input of an object in RA and DEC as well as a search radius. RA and DEC specify where to extend radius to search for pixel value of center of object. Utilizes Photutils centroid_sources and header data to convert RA and DEC into pixel values.

Parameters:

• datacontainer (IFUcube Object) – data file initialized in cubeClass.py

• ra (float) – Right ascension of object in degrees

• dec (float) – Declination of object in degrees

• radius (int, float) – pixel radius value to search for center of specified object

Returns:

x_pos X pixel coordinate of object in datacube y_pos Y pixel coordinate of object in datacube

Return type:

float

pycube.core.manip.pixel_dist(z_pos1, y_pos1, x_pos1, z_pos2, y_pos2, x_pos2)

Given a pixel (1) and a set of locations (2), the macro returns the euclidean distance from (2) to (1)

Parameters:

• z_pos1 (float) – location of the pixel from which calculate the distances

• y_pos1 (float) – location of the pixel from which calculate the distances

• x_pos1 (float) – location of the pixel from which calculate the distances

• z_pos2 (np.array) – location of the pixels for which the distances from zPix1, y_pos1, xPix1 will be calculated

• y_pos2 (np.array) – location of the pixels for which the distances from zPix1, y_pos1, xPix1 will be calculated

• x_pos2 (np.array) – location of the pixels for which the distances from zPix1, y_pos1, xPix1 will be calculated

Returns:

dist – distance from (1) to (2)

Return type:

np.array

pycube.core.manip.q_spectrum(datacontainer, x_pos, y_pos, statcube=None, radius_pos=2.0, inner_rad=10.0, outer_rad=15.0, void_mask=None)

Performing quick spectrum extraction from a circular aperture on a cube. Background is calculated from the median of an annular aperture performing sigma clipping.

Parameters:

• datacontainer (IFUcube object) – original data read into cubeClass.py

• x_pos (np.array) – x-location of the source in pixel

• y_pos (np.array) – y-location of the source in pixel

• statcube (np.array, optional) – variance in 3D array if specifying a 3D array for datacube. Otherwise, pulls this array from IFUcube object (default is None)

• radius_pos (np.array, optional) – radius where to perform the aperture photometry (default is 2.)

• inner_rad (np.array, optional) – inner radius of the background region in pixel (default is 10.)

• outer_rad (np.array, optional) – outer radius of the background region in pixel (default is 15.)

• void_mask (np.array, optional) – mask of possible contaminants (1->the pixel will be removed from the photometry) (default is None)

Returns:

• spec_ap_phot (np.array) – spectra of selected object

• spec_var_ap_phot (np.array) – sigma of spectra

• spec_flux_bg (np.array) – background spectral flux

pycube.core.manip.q_spectrum_no_bg(datacontainer, x_pos, y_pos, statcube=None, radius_pos=2.0)

Performing quick spectrum extraction from a circular aperture on a cube without calculating background spectral flux

Parameters:

• datacontainer (np.array, IFUcube Object) – data in a 3D array or object initiated in cubeClass.py

• x_pos (int, float, np.array) – x-location of the source in pixel

• y_pos (int, float, np.array) – y-location of the source in pixel

• statcube (np.array, optional) – variance in 3D array if specifying a 3D array for datacube. Otherwise, pulls this array from IFUcube object (default is None)

• radius_pos (float) – radius where to perform the aperture photometry

Returns:

• spec_ap_phot (np.array) – spectra of selected object

• spec_var_ap_phot (np.array) – sigma of spectra

pycube.core.manip.q_spectrum_no_bg_mask(datacontainer, mask_xy, statcube=None)

Performing quick spectrum extraction from an aperture given by a 2D mask from a cube.

Parameters:

• datacontainer (IFUcube object, np.array) – data initialized in cubeClass.py or 3D array of data

• mask_xy (np.array) – 2D aperture where to perform the spectral extraction. Only spaxels marked as 1 are considered

• statcube (np.array) – 3D variance array

Returns:

• flux_obj – sum of object flux ignoring Nans

• err_flux_obj – sigma of variance

pycube.core.manip.quick_ap_photometry(datacopy, statcopy, x_pos, y_pos, radius_pos=2.0, inner_rad=10.0, outer_rad=15.0)

Performing quick circular aperture photometry on an image. An annular region with inner radius [inner_rad] and outer radius [outer_rad] will be used to estimate the background.

Parameters:

• datacopy (np.array) – image where the aperture photometry will be performed

• statcopy (np.array) – variance image that will be used to calculate the errors on the aperture photometry

• x_pos (int, float, np.array) – x-location of the source in pixel (converts to array)

• y_pos (int, float, np.array) – y-location of the source in pixel (converts to array)

• radius_pos (np.array, optional) – radius where to perform the aperture photometry (default is 2.)

• inner_rad (np.array, optional) – inner radius of the background region in pixel (default is 10.)

• outer_rad (np.array, optional) – outer radius of the background region in pixel (default is 15.)

Returns:

obj_flux, obj_err_flux, ave_flux – flux of object, sigma of flux, and average flux values

Return type:

np.array

pycube.core.manip.quick_ap_photometry_no_bg(datacopy, statcopy, x_pos, y_pos, obj_rad=2.0)

Performing quick circular aperture photometry on an image without background subtraction

Parameters:

• datacopy (np.array) – image where the aperture photometry will be performed

• statcopy (np.array) – variance image that will be used to calculate the errors on the aperture photometry

• x_pos (np.array) – x-location of the source in pixel

• y_pos (np.array) – y-location of the source in pixel

• obj_rad (np.array, optional) – radius where to perform the aperture photometry (default is 2.)

Returns:

flux_obj, err_flux_obj – fluxes and errors of the sources derived from datacopy and statcopy

Return type:

np.arrays

pycube.core.manip.small_cube(datacontainer, min_lambda=None, max_lambda=None)

Given an IFUcube, this function collapses along min_lambda and max_lambda. It also updates the wavelength information to be conformed to the new size. Note that min_lambda and max_lambda can be given both as wavelength and as channels. If the input value is <3000. it will be assumed to be channel number, otherwise wavelength in Angstrom will be considered.

Parameters:

• datacontainer (IFUcube object) – data intialized in cubeClass.py

• min_lambda (int, optional) – min channel to create collapsed image

• max_lambda (int, optional) – max channel to create collapsed image

Returns:

• s_primary_headers (hdu header) – primary header

• s_data_headers (hdu header) – fits header for DATA with corrected CRVAL3

• s_datacopy (np.array) – data in a 3D array trim from min_lambda to max_lambda

• s_stat_headers (hdu header) – fits header for STAT with corrected CRVAL3

• s_statcopy (np.array) – variance in a 3D array trim from min_lambda to max_lambda

pycube.core.manip.stat_fullcube(datacube, n_sigma_extreme=None)

Given a cube the macro calculate average, median, and sigma of all its voxels. NaNs are considered as bad pixels and removed.

Parameters:

• datacube (np.array) – 3D cube containing the voxels you want to get the statistic for.

• n_sigma_extreme (float, optional) – if not None, voxels with values larger than sigmaExtreme times the standard deviation of the cube will be masked (default is None)

Returns:

cube_average, cube_median, cube_std – average, median, and standard deviation of the cube.

Return type:

float

pycube.core.manip.stat_fullcube_z(datacube, n_sigma_extreme=None)

Given a cube the macro calculate average, median, and sigma of all its voxels along the spectral (z) axis. NaNs are considered as bad pixels and removed.

Parameters:

• datacube (np.array) – 3D cube containing the voxels you want to get the statistic for.

• n_sigma_extreme (np.array, optional) – if not None, voxels with values larger than sigmaExtreme times the standard deviation of the cube will be masked (default is None)

Returns:

cube_avg_z, cube_med_z, cube_std_z – average, median, and standard deviation of the cube along the spectral axis.

Return type:

np.arrays

pycube.datacontainers

datacontainer

class pycube.datacontainers.datacontainer.DataContainer(hdul=None, instrument=None, fits_file=None)

Base class to dictate the general behavior of a data container

Attributes:

datacube

class pycube.datacontainers.datacube.DataCube(hdul=None, instrument=None, fits_file=None)

This class is designed to dictate the behaviour of a datacube

image

class pycube.datacontainers.image.Image(hdul=None, instrument=None, fits_file=None)

This class is designed to dictat the behaviour of an image

pycube.ancillary

checks

Module that performs some useful and basic checks and transformations

pycube.ancillary.checks.check_checksums(hdul)

Test if the datasum and checksum keywords in a astropy.io.fits.HDUList are present and up-to-date

Parameters:

hdul (astropy.io.fits.HDUList) – list of astropy HDUs to be checked

Returns:

True all the HDUs in the input astropy.io.fits.HDUList have the correct datasum and checksum

Return type:

bool

pycube.ancillary.checks.fits_file_is_valid(fits_file, verify_fits=False, overwrite=False)

Check if a file exists and has a valid extension

The option verify_fits checks the header of the fits file using astropy.io.fits.verify

Parameters:

• fits_file (str) – fits file you would like to check

• verify_fits (bool) – if set to True, it will verify that the fits file is complaint to the FITS standard.

• overwrite (bool) – if True, overwrite the input fits file with the header corrections from verify_fits

Returns:

True if exists False and warning raised if not.

Return type:

bool

cleaning_lists

Module that performs some lists massaging to work well with arg.parser

pycube.ancillary.cleaning_lists.from_element_to_list(element, element_type=<class 'str'>)

Given an element it returns a list containing the element

It also checks all the elements in the list have the same type defined by element_type

Parameters:

• element (any) – element that will be put in the list

• element_type (any) – type of the element that should be contained in the list

Returns:

list containing element

Return type:

list

pycube.ancillary.cleaning_lists.from_element_to_list_of_quantities(element, unit=None)

Convert an input into a list of astropy.units.Quantity :param element: element that will be put in the list :type element: int, float, np.ndarray, Quantity object, list :param unit: An object that represents the unit to be associated with the input value :type unit: UnitBase instance

Returns:

list of quantities in the format element`*`unit

Return type:

list

pycube.ancillary.cleaning_lists.make_list_of_fits_files(args_input, verify_fits=False)

Cleaning an input list of fits files

Parameters:

• args_input (list) – input list of fits files that will be checked (usually is coming from parse_arguments() in a script)

• verify_fits (bool) – if set to True, it will verify that the fits file is complaint to the FITS standard

Returns:

list containing all the valid fits files given in input

Return type:

list

pycube.instruments

instrument

class pycube.instruments.instrument.Instrument

Class defining the behaviour of an ifu instrument in pycube.

Attributes:

name = None

Name of the spectrograph

telescope = None

Name of the telescope where the instrument is mounted

vlt_muse

class pycube.instruments.vlt_muse.VLTMuse

pycube.scripts

pycube_collapse

pycube_collapsed

Script to collapse a datacontainers along the spectra axis

Inputs:

• input_cube - Input data_cube

• wavelength_min - Minimum wavelength

• wavelength_max - Maximum wavelength

pycube.test

test_ancillary

pycube.test.test_ancillary.test_cleaning_lists()

Test that the list creator is working

test_msgs

pycube.test.test_msgs.test_indent()

Test for from pycube.msgs

The code checks if the msgs.indent() returns a 13 x spaces string