LineList class and functions

class specpolFlow.LineList(ion, wl, loggf, Elo, Jlo, Eup, Jup, landeLo, landeUp, landeEff, rad, stark, waals, depth, configLo, configUp, refs)

Container for a set of spectral line data, usually from VALD.

This usually contains:

• nLines - number of lines in the line list

• ion - array of strings of species identifiers (element or molecule and ionization)

• wl - array of wavelengths

• loggf - array of oscillator strengths (log gf)

• Elo - array of excitation potentials for the lower level in the transition (in eV)

• Jlo - array of J quantum numbers for the lower level

• Eu - array of excitation potentials for the upper level in the transition (in eV)

• Jup - array of J quantum numbers for the upper level

• landeLo - array of Lande factors for the lower level

• landeUp - array of Lande factors for the upper level

• landeEff - array of effective Lande factors for the transition

• rad - array of radiative damping coefficients

• stark - array of quadratic Stark damping coefficients

• waals - array of van der Waals damping coefficients

• depth - depth at the centre of the spectral line, as estimated by VALD

• configLo - array of strings with the electron configuration and term symbols for the lower level

• configUp - array of strings with the electron configuration and term symbols for the upper level

• refs - array of references for the sources of the line data (optional)

air_to_vacuum()

Convert the line list from wavelength in air to wavelength in vacuum (assuming dry air at 15 C and 1 atmosphere of pressure) and return the modified line list.

This function requires the LineList to have wavelengths in angstroms.

Return type:

LineList

doppler_shift(velocity)

Doppler shift the line list by the input radial velocity (in km/s) and return the modified line list.

Parameters:

velocity – the radial velocity in km/s

Return type:

LineList

insert(i, newval)

Insert lines from a LineList at a specific index. Returns a new LineList combining the two line lists (does not operate in place)

Parameters:

• i – index to insert at

• newval – LineList of new values to insert

Return type:

LineList

save(fname)

Write a line list to a text file. This outputs using the VALD version 3 ‘extract stellar’ ‘long’ format.

A few details (e.g. references at the end of the file) are omitted since they are not saved in the LineList class.

Parameters:

fname – the file name to save the output to

vacuum_to_air()

Convert the line list from wavelength in vacuum to wavelength in air (assuming dry air at 15 C and 1 atmosphere of pressure) and return the modified line list.

This function requires the LineList to have wavelengths in angstroms.

Return type:

LineList

specpolFlow.plot_lineList(llist, depthCut=0.0, maxLabels=None, scaleDepths=0.25, cont=1.01, rise=0.05, nrows=1, padding=4.0, vpadding=6.0, romanIon=False, avoidOverlaps=True, dynamicUpdate=True, linewidth=1.0, linecolor='grey', linestyle='-', fontsize=8, rotation='vertical', bindKeys=True, ax=None, lineKwargs={}, **kwargs)

Plot a line list, with tick marks at the positions of lines and text labels for the species of line.

This will either generate new matplotlib figure and axes objects with the plot, or if an existing axes object is passed to the function (with the ax keyword) the line list will be plotted in that axes.

By default, this function will try to adjust the positions of the labels so that they don’t overlap.

You can limit the lines shown to only those deeper than a threshold depth with depthCut. The maximum number of labels drawn can be limited with maxLabels, which can be useful for efficiency. In this case tick marks are still drawn for all lines, only the number text labels is limited. Labels are shown for the maxLabels deepest lines in the window. Drawing labels is quite slow, so for a large line list limiting the number of labels drawn is usually a good idea.

Parameters:

• llist – the line list to plot, as a LineList object

• depthCut – only lines with a depth value greater than this will be plotted.

• maxLabels – the maximum number of line labels that will be drawn at one time. Only labels for the maxLabels deepest lines depths will be drawn, although tick marks for all lines will be drawn. Drawing labels is relatively slow, and drawing a large number can make this routine run slowly (as well as being hard to read!). Defaults to plotting all labels.

• scaleDepths – scale the depths of the tick marks by this value. Tick depths are proportional to the line depth parameter. (Tick marks extend down to 1.0 - llist.depth*scaleDepths)

• cont – draw tick marks from the depth up to this value (typically set this at or just above the continuum level).

• rise – place the labels this much above the cont level.

• nrows – the number of rows of labels to be drawn

• padding – spacing to leave between labels (in pixels), when avoidOverlaps is True.

• vpadding – vertical spacing to leave between rows of labels (in pixels), only used when avoidOverlaps is True.

• romanIon – if True, convert the numbers in the ion strings to use roman numerals. Roman numerals for ionization stage are typically nicer for publication quality figures.

• avoidOverlaps – if True, shift the positions of labels to avoid having the text overlap. If too many labels are plotted overlaps will still occur (try changing maxLabels or depthCut). Defaults to True.

• dynamicUpdate – update the label positions of every time the figure changes. This keeps labels from overlapping or being cut off if the x-axis changes (e.g. when using ax.set_xlim() or through panning or zooming in an interactive window). If you set this to False, use ax.set_xlim() before running plot_lineList(). (note: this function connects to the Axes ‘xlim_changed’ event and the Figure ‘resize_event’, and stores some data in the Figure object as fig.dynamicLineList) Defaults to True.

• linewidth – matplotlib line width for the tick marks

• linecolor – matplotlib color for the tick marks

• linestyle – matplotlib line style for the tick marks

• fontsize – font size for the labels

• rotation – orientation of the line label text, can be ‘horizontal’, ‘vertical’, or a float with an angle in degrees.

• bindKeys – If True, set up some keys to interactively adjust the range viewed in the plot, by panning and zooming (using matplotlib). Only active if dynamicUpdate is True. Keys used are: arrow keys – pan left, right, up, and down; i – zoom in; o – zoom out; z – activate matplotlib’s zoom tool; a – autoscale the zoom to show all data; A – autoscale the y-axis only;

• ax – the matplotlib axes object to plot the lines in. If this is None, then a new figure and axes will be generated.

• lineKwargs – a dictionary of additional keyword arguments that are passed to the matplotlib LineCollection function. e.g. {‘zorder’:10.0, ‘alpha’:0.2, ‘lw’:5.0}

• kwargs – any remaining keyword arguments are passed to the matplotlib ax.text() function when creating the labels for lines.

Returns:

a matplotlib figure object, and an axes object containing the plot.

specpolFlow.line_list_zeros(nLines)

Generate a line list of zeros and blank text.

Used by read_VALD (It can be a bit faster to allocate all the array space at once.)

Parameters:

nLines – the number of lines in the LineList of zeros

Return type:

LineList

specpolFlow.read_VALD(fname)

Read a list of spectral line data from VALD and return a LineList.

This expects VALD version 3 line list, in an ‘extract stellar’ ‘long’ format.

Parameters:

fname – the file name for the VALD line list.

Return type:

LineList

specpolFlow.getEffectiveLande(landeLo, landeUp, Jlo, Jup)

Calculate an effective Lande factor for a transition.

This uses the upper and lower level Lande factors and J quantum numbers. The effective Lande factor is similar to an average weighted by the splitting pattern of the line. It parameterizes the displacement of the centre of gravity of the sigma components of a Zeeman split line.

Parameters:

• landeLo – Lower level Lande factor

• landeUp – Upper level Lande factor

• Jlo – Lower level J quantum number

• Jup – Upper level J quantum number

Returns:

Effective Lande factor for the transition

specpolFlow.estimateLande(J, config, verbose=False)

Estimate a Lande factor for a level (if VALD doesn’t have one).

This supports levels in LS coupling, JJ coupling, and JK coupling. Levels in LK coupling are not supported. This relies on VALD3’s text format for electron term symbols and configurations.

Parameters:

• J – The J quantum number for this level

• config – The text string from VALD with the electron configuration and term symbol for the level

• verbose – Report warnings for levels in unsupported coupling schemes if True

Returns:

The Lande factor estimated for this level. If the Lande factor can’t be estimated this will be 99.0.

specpolFlow.get_LS_numbers(config)

Extract the L and S quantum numbers from a VALD term symbol text string, for a level in LS coupling.

Parameters:

config – the electron configuration and term symbol text string

Returns:

The L and S quantum numbers (if a parsing error occurs, negative values are returned)

specpolFlow.get_JJ_numbers(config)

Extract the L1, S1, J1, L2, S2, and J2 quantum numbers for a level in JJ coupling from VALD’s electron configuration and term symbol text string.

This should cover the J1-J2 case (where two subgroups combine to produce J1 and J2, which combine to produce the total J), the J1-j case (where one subgroup makes J1, which combines with an additional electron with j to produce J), and it should work for the j-j case (for two equivalent electrons with their own j, which combine to make J).

Parameters:

config – the electron configuration and term symbol text string

Returns:

The L1, S1, J1, L2, S2, and J2 quantum numbers (if a parsing error occurs, negative values are returned)

specpolFlow.get_JK_numbers(config)

Extract the L1, S1, J1, L2, S2, and K quantum numbers for a level in JK coupling from VALD’s electron configuration and term symbol text string.

This is sometimes called J1-l or J1-L2 coupling.

Parameters:

config – the electron configuration and term symbol text string

Returns:

The L1, S1, J1, L2, S2, and K quantum numbers (if a parsing error occurs, negative values are returned)