Mask and ExcludeMaskRegions classes and functions

Mask and ExcludeMaskRegions classes and functions#

class specpolFlow.Mask(wl, element, depth, excite, lande, iuse)#

The data for the LSD line Mask.

This usually contains the arrays:

  • wl - wavelengths of lines

  • element - the element+ion code for the line

  • depth - the depth of the line

  • lande - the effective Lande factor of the line

  • iuse - integer flag for whether the line is used

clean(regions)#

Remove lines inside a set of exclude regions from a mask.

Takes an ExcludeMaskRegions object, and returns a Mask object with the iuse values set to zero for spectral lines with wavelengths inside these regions.

Parameters:

regions – An ExcludeMaskRegions object

Return type:

Mask

get_weights(normDepth, normWave, normLande)#

Returns the calculated LSD weights of all the lines in the mask (includes lines with both the iuse flag 0 and 1).

This assumes the Stokes I lines are weighted as depth, and Stokes V is weighted as depth*wavelength*Lande factor.

Parameters:

  • normDepth – the normalizing line depth for the mask/LSD profile

  • normWave – the normalizing wavelength (nm) for the mask/LSD profile

  • normLande – the normalizing effective Lande factor for the mask/LSD profile

Returns:

weightI, weightV (as arrays)

prune()#

Return a Mask object with unused lines removed from the Mask.

Remove lines if iuse index is set to 0, restricting the Mask to only lines used in LSD.

Return type:

Mask

save(fname)#

Save the line Mask to a text file, in Donati’s and LSDpy format.

Parameters:

fname – the file name to output the Mask to

specpolFlow.read_mask(fname)#

Read in an LSD line mask file and return a Mask object.

The mask file will have one line of header and columns of:

  • Wavelength (nm)

  • Atomic number + (ionization state)*0.01

  • Line depth

  • Excitation potential of the lower level (eV)

  • Effective Lande factor

  • Flag for whether the line is used (1=use, 0=skip).

Parameters:

fname – the name of the file to read.

Return type:

Mask

class specpolFlow.ExcludeMaskRegions(start, stop, type)#

Class for a region object that records spectral regions to exclude from a Mask.

Usually contrains arrays of:

  • start - starting wavelengths for the regions

  • stop - ending wavelengths for the regions

  • type - optionally, text comments for the type of region (inside a numpy array with dtype=object)

save(fname)#

Save the ExcludeMaskRegions object to a text file.

The file contains one line for each region, with the start wavelength, end wavelength, and a type comment.

Parameters:

fname – the file path/name

to_dict()#

Return the ExcludeMaskRegions as a dictionary. This is useful to transform ExcludeMaskRegions objects to Panda dataframes.

specpolFlow.read_exclude_mask_regions(fname)#

Read in an ExcludeMaskRegions file into an ExcludeMaskRegions object.

The file should be a text file with one line for each region, containing the start wavelength, end wavelength, and the type comment.

Parameters:

fname – the path/name of the file

Return type:

ExcludeMaskRegions

specpolFlow.get_Balmer_regions_default(velrange=500)#

Generate an ExcludeMaskRegions object with regions around Balmer H-lines (alpha to epsilon) up to a given radial velocity, and a region that excludes the Balmer jump (from 360-392 nm).

Parameters:

velrange – velocity range around the H-line to be excluded (default 500 km/s)

Return type:

ExcludeMaskRegions

specpolFlow.get_telluric_regions_default()#

Generate an ExcludeMaskRegions object with regions containing heavy telluric line contamination in the optical.

Return type:

ExcludeMaskRegions

specpolFlow.make_mask(lineListFile, outMaskName=None, depthCutoff=0.0, wlStart=None, wlEnd=None, landeStart=None, landeEnd=None, elementsUsed=[], elementsExclude=[], atomsOnly=True, includeNoLande=False, defaultLande=1.0)#

Generate an LSD line mask from a VALD line list and save it. This is the main interface for generating new line masks with Python scrips.

This generates an LSD line mask from atomic lines in the list, and estimates Lande factors for lines where possible. Lines for which no Lande factor can be estimated are omitted by default. This assumes input line list wavelengths in A, and returns a mask in nm.

Parameters:

  • lineListFile – The name of the file containing the line list (in the VALD3 ‘extract stellar’ ‘long’ format)

  • outMaskName – The name of the to write the mask to (set this to None to avoid saving a file, default)

  • depthCutoff – Only include lines in the mask deeper than this value (defaults to 0, all lines included)

  • wlStart – Optionally, only use lines with wavelengths above this (note: value in nm!)

  • wlEnd – Optionally, only use lines with wavelengths below this (note: value in nm!)

  • landeStart – Optionally, only use lines with effective Lande factors above this

  • landeEnd – Optionally, only use lines with effective Lande factors below this

  • elementsUsed – Optionally, provide a list of elements to include in the line mask. This should be a list of strings with the element symbols, e.g. [‘C’, ‘O’, ‘Si’, ‘Fe’] (an empty list or a list starting with ‘all’ will include all elements)

  • elementsExclude – Optionally, provide a list of elements to exclude from the line mask. Also a list of strings with the element symbols.

  • atomsOnly – Only include atomic lines (no molecular lines) and exclude H lines (defaults to True)

  • includeNoLande – Include lines in the mask even if no Lande factor can be estimated for them (defaults to False)

  • defaultLande – The value of the effective Lande factor to use if no value can be estimated (only used if includeNoLande = True)

Return type:

Mask

specpolFlow.convert_list_to_mask(lineList, depthCutoff=0.0, atomsOnly=True, includeNoLande=False, defaultLande=1.0)#

Convert a lineList to an LSD line mask.

This estimates Lande factors when VALD doesn’t have a known value. This can also automatically reject any H lines and any molecular lines. Note, this assumes an input line list in A, and returns a mask in nm. See also the make_mask() function.

Parameters:

  • lineList – The line list object to be converted to a mask

  • depthCutoff – Only include lines deeper than this depth cutoff (defaults to 0, all lines included)

  • atomsOnly – Flag to use only atomic lines (no molecular lines) and exclude H lines (defaults to True)

  • includeNoLande – Flag to include lines in the mask even if no Lande factor can be estimated for them (defaults to False)

  • defaultLande – The value of the effective Lande factor to use for lines where no value can be estimated (only used if includeNoLande = True)

Return type:

Mask

specpolFlow.filter_mask(mask, depthCutoff=0.0, wlStart=None, wlEnd=None, landeStart=None, landeEnd=None, elementsUsed=[], elementsExclude=[])#

Remove lines from an LSD line mask, based on their depth, wavelength, effective Lande factor, or element.

Usually, only one of elementsUsed and elementsExclude should be used. Both can be used, in that case only elements in elementsUsed are included, and then any elements in elementsExclude are removed from that. (Filtering by element currently only works for atomic lines, not molecular lines)

Parameters:

  • mask – The line mask object to filter lines out of

  • depthCutoff – Only include lines in the mask deeper than this value (defaults to 0, all lines included)

  • wlStart – Optionally, only use lines with wavelengths above this (note: value in nm!)

  • wlEnd – Optionally, only use lines with wavelengths below this (note: value in nm!)

  • landeStart – Optionally, only use lines with effective Lande factors above this

  • landeEnd – Optionally, only use lines with effective Lande factors below this

  • elementsUsed – Optionally, provide a list of elements to include in the line mask. This should be a list of strings with the element symbols, e.g. [‘C’, ‘O’, ‘Si’, ‘Fe’] (an empty list or a list starting with ‘all’ will include all elements)

  • elementsExclude – Optionally, provide a list of elements to exclude from the line mask. Also a list of strings with the element symbols.

Return type:

Mask

specpolFlow.cleanMaskUI(maskName, obsName, outMaskName=None, inExcludeName=None, outExcludeName='excludeRanges.dat', batchMode=False)#

Run an interactive tool for LSD line mask cleaning.

This opens a window with a plot of the line mask, a reference observation, and a model LSD spectrum (convolution of a line mask and LSD profile). The parameters for the LSD calculation are taken from the defaults in the cleanMaskUISubroutines lsdParams() function.

This saves a copy of the cleaned mask to a file, and also returns a copy as a Mask object and the regions excluded from the mask as an ExcludeMaskRegions object.

Parameters:

  • maskName – File name, or a Mask object, for the input line mask to clean.

  • obsName – File name for the reference observation to compare with.

  • outMaskName – File name for the output cleaned mask, defaults to [maskName].clean

  • inExcludeName – File name for reading a set of regions to be excluded from the line mask.

  • outExcludeName – File name for saving the set of regions excluded from the mask. (may be the same as inExcludeName)

  • batchMode – Flag for skipping the GUI. False = open the GUI (the default). True = skip the GUI, just read inExcludeName and apply those exclude regions.

Returns:

a Mask object with the cleaned mask, and an ExcludeMaskRegions with the selected exclude regions.