LSD class and functions

LSD class and functions#

class specpolFlow.LSD(vel, specI, specSigI, specV=None, specSigV=None, specN1=None, specSigN1=None, specN2=None, specSigN2=None, header=None)#

Holds the LSD profile data.

This usually includes numpy arrays:

  • vel - velocity grid for the LSD profile

  • specI - the Stokes I profile

  • specSigI - the uncertainties on Stokes I

  • specV - the polarization profile, most often Stokes V

  • specSigI - the uncertainties on the polarization profile

  • specN1 - the Null1 profile

  • specSigN1 - the uncertainties on specN1

  • specN2 - the Null2 profile, if it exists, otherwise zeros

  • specSigN2 - the uncertainties on Null2 if they exist

  • header - an optional text header for the LSD profile file

And integers:

  • numParam - The number of Stokes I, V, & Null profiles used (usually 1, 3, or 4)

  • npix - the number of pixels (points in velocity) in the LSD profile

calc_bis(Ic=1.0, cog='I', biswidth=None, plotFit=False, fullOutput=False)#

Calculate the bisector velocity span to this LSD profile for a given continuum level. This follows the line bisector and velocity span definitions by Gray (1982) and Queloz et al. (2001), respectively. An uncertainty on the velocity span is estimated from the standard deviation of points in the upper and lower portions of the bisector.

Parameters:

  • Ic – The continuum level to use the the BIS calculation (float, default=1.0)

  • cog – The value, or calculation method for the center of gravity. The choices are: ‘I’: center of gravity of I, ‘V’: center of gravity of V, ‘IV’: center of gravity of I*V, or a float: a user defined value in km/s.

  • biswidth – Distance from the line center for the BIS calculation. One element = same on each side of line center. Two elements, left and right of line center. Not defined: using the entire profile.

  • plotFit – If True, plot the bisector curve and the LSD profile with matplotlib

  • fullOutput – If True, the return velocity span, top and bottom velocity values, and line bisector. If False just return the velocity span.

Returns:

The velocity span, and error (Float). If fullOutput is True then also include average velocity at the top & bottom part of the bisector (Float) and numpy arrays with the line bisector & associated intensity levels.

calc_bz(cog='I', norm='auto', lambda0=500.0, geff=1.2, velrange=None, bzwidth=None, plot=True, **kwargs)#

Calculate the Bz of an LSD profile

Parameters:

  • cog – The value or calculation method for the center of gravity. The choices are: ‘I’: center of gravity of Stokes I, ‘V’: center of gravity of Stokes V, ‘IV’: center of gravity of I*V, ‘min’: velocity of the minimum of Stokes I, or a float: a user defined value in km/s.

  • norm – calculation method for the continuum. The choices are: ‘auto’: the median of I outside of velrange (if defined), or the full range (if velrange is not defined), or float: a user defined value to use for Ic.

  • lambda0 – wavelength of the transition in nanometers (default=500). For an LSD profile, this is the lambda value the LSD profile shape was scaled with.

  • geff – effective Lande factor of the transition. For an LSD profile, this is the geff value the LSD profile shape was scaled with.

  • velrange – range of velocity to use for the determination of the line center and the continuum. If bzwidth is not given, this range will also be used for the integration range in the Bz calculation. If not given, the whole LSD profile will be used.

  • bzwidth – distance from the line center (from the cog) used for the integration range in the Bz calculation. One element = same on each side of line center. Two elements = left and right of line center. Not given (default): instead use velrange for this.

  • plot – whether or not a graph is generated and returned.

  • kwargs – additional keyword arguments are passed to the matplotlib plotting routines, if a plot is generated.

Returns:

a dictionary with Bz (in G) and FAP calculations, optionally also a matplotlib figure.

calc_fap()#

Helper function that calculates the FAP for Stokes V, null1, and null2, for the LSD profile.

The False Alarm Probability (FAP) is the probability that the observed data are consistent with the null hypothesis of no magnetic field. In this case, the null hypothesis is a flat line in Stokes V (an offset from 0 is allowed to account for continuum polarization). The probability is evaluated from chi^2.

If you would like a specific range in velocity, simply slice the LSD object beforehand. Note that the calcBz function also returns the FAP inside the spectral line, over the same velocity range as used in the Bz calculation.

Returns:

the values FAP V, FAP N1, FAP N2.

coadd(*args)#

coadd this LSD profile with other LSD profiles

Currently the LSD profiles must all be on the same velocity grid, interpolation is not supported. Recommend extracting all LSD on the same velocity grid to avoid having to interpolate. Coadding here essentially averages LSD profiles weighted by 1/sigma**2.

Parameters:

args – other LSD objects (or a list or tuple of them) to coadd with this one

Return type:

LSD

cog_I(Ic=1.0, fullOutput=False)#

Helper function to return the center of gravity of Stokes I for the LSD profile, for a given continuum level.

Parameters:

  • Ic – the continuum level to use the the COG calculation (float, default=1.0)

  • fullOutput – If True, return the error of the velocity of the center of gravity

Returns:

the velocity of the center of gravity, optionally also its error

cog_IV(Ic=1.0)#

Helper function to return the center of gravity of (Stokes I)*(Stoke V) for the LSD profile, for a given continuum level.

Parameters:

Ic – the continnum level to use the the COG calculation (float, default=1.0)

Returns:

the velocity of the center of gravity

cog_V()#

Helper function to return the center of gravity of the Stokes V LSD profile.

Returns:

the velocity of the center of gravity

cog_min()#

Helper function to return the velocity of the minimum of the Stokes I LSD profile.

Returns:

the velocity of the Stokes I minimum

cog_rv(velrange, norm='auto')#

Calculate a radial velocity using the center of gravity (i.e. first moment) of the Stokes I profile.

This uses function the cog_I function, but provides the convenience of estimating the continuum level automatically and performing the calculation on a user specified velocity range.

Parameters:

  • norm – calculation method for the continuum. The choices are: ‘auto’: the median of I outside of velrange; or float: a user defined value to use for Ic.

  • velrange – range of velocity to use for the determination of the line center and the continuum. (The integration range for the first moment.) This should be a starting and ending velocity as two elements inside a list (or tuple).

Returns:

the velocity of the center of gravity, and its uncertainty

fit_gaussian_rv(velrange=None, plotFit=False, fullOutput=False, scaleErrs=False)#

Fit a Gaussian function to this LSD profile, to determine a radial velocity.

Parameters:

  • velrange – Range of velocities included in the fit (a tuple or list with 2 elements). If not given, the whole range will be used.

  • plotFit – If True, plot the fit to the LSD profile with matplotlib

  • fullOutput – If True, return all the Gaussian best fit parameters, rather than just the RV and RV error

  • scaleErrs – If True, scale the errors on the fitting parameters by the square root of the reduced chi^2

Returns:

Tuple of best fit RV and RV error; If fullOutput is True, then also includes continuum & error, amplitude & error, and width & error

norm(normValue)#

Return a renormalized LSD profile. Divides the I, V, and Null profiles, and their uncertainties, by a value.

Parameters:

normValue – the value to renormalize (divide) the LSD profile by

Return type:

LSD

plot(figsize=(10, 10), sameYRange=True, plotZeroLevel=True, fig=None, **kwargs)#

Plot the LSD profile

This generates a matplotlib figure. To display the figure, after running this function, use ‘import matplotlib.pyplot as plt’ and ‘plt.show()’. To save the figure, you can use ‘fig.savefig(“fileName.pdf”)’ on the new figure object.

Parameters:

  • figsize – the size of the figure being created

  • sameYRange – optionally set the Stokes V and Null plots to have the same y scale

  • plotZeroLevel – optionally include a dashed line at 0 for the V and Null plots

  • fig – optionally, a matplotlib figure used for plotting the LSD profile. By default (or if None) a new figure will be generated.

Returns:

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

save(fname)#

Save the LSD profile to a file. This saves to a text file in Donati’s format.

Parameters:

fname – the name of the file the LSD profile to saves to.

scale(scale_int, scale_pol)#

Return an LSD profile with rescaled amplitudes of the LSD profile (see also set_weights()).

Parameters:

  • scale_int – scale the intensity profile by this

  • scale_pol – scale the polarization and null profiles by this

Return type:

LSD

set_weights(wint_old, wpol_old, wint_new, wpol_new)#

Return an LSD profile with different mask normalization/scaling weights (see also scale()).

Parameters:

  • wint_old – The current intensity weight (d)

  • wpol_old – The current polarization weight (g*d*lambda)

  • wint_new – The new intensity weight (d)

  • wpol_new – The new polarization weight (g*d*lambda)

Return type:

LSD

vshift(velShift)#

Return an LSD profile, with a shift to the velocities of the LSD profile.

Parameters:

velShift – the change in velocity to be added

Return type:

LSD

specpolFlow.read_lsd(fname)#

Read in an LSD profile and return an instance of the LSD class.

The LSD profiles are in Donati’s text format; however, the two lines of header in Donati’s format are optional.

Parameters:

fname – the name of the file containing the LSD profile

Return type:

LSD

specpolFlow.run_lsdpy(obs, mask, outLSDName=None, velStart=-200.0, velEnd=200.0, velPixel=None, normDepth=0.2, normLande=1.2, normWave=500.0, removeContPol=True, trimMask=True, sigmaClipIter=0, sigmaClip=500, outModelName=None, plotLSD=True, outPlotLSDName=None)#

Run the LSDpy code and return an LSD object (a convenience wrapper around the lsdpy.main() function).

This requires LSDpy to be installed and in your Python path, which should be installed if you installed specpolFlow with pip (see folsomcp/LSDpy ).

While some reasonable default values are included, pay attention to the parameters: velPixel, normDepth, normLande, normWave, and outName.

Arguments are:

Parameters:

  • obs – name of the input observed spectrum file

  • mask – name of the input LSD mask file

  • outLSDName – if provided, save the output LSD profile to this file (Default = None, not saved)

  • velStart – float, starting velocity for the LSD profile (km/s)

  • velEnd – float, ending velocity (km/s)

  • velPixel – float, velocity pixel size (km/s). If not provided, this will be the median pixel size in the observation, however it is recommended to set this explicitly.

  • normDepth – float, normalizing line depth

  • normLande – float, normalizing effective Lande factor

  • normWave – float, normalizing wavelength

  • removeContPol – flag for whether continuum polarization is subtracted from the LSD profile (Default = True)

  • trimMask – flag for whether very closely spaced lines should be removed from the line mask (Default = True)

  • sigmaClipIter – int, number of iterations for sigma clipping, rejecting possible bad pixels based on the fit to Stokes I. Set to 0 for no sigma clipping. (Default = 0, no sigma clipping)

  • sigmaClip – float, if sigma clipping, reject pixels where the observation differs from the model by more than this number of sigma. Should be a large value so only very bad pixels are rejected. (Default = 500.)

  • outModelName – if provided, save the output model spectrum to this file (Default = None, not saved)

  • plotLSD – flag for whether to plot the LSD profile (using matplotlib) (Default = True)

  • outPlotLSDName – if provided, save the the plotted figure of the LSD profile to this file (e.g. ‘figProf.pdf’). Supports the output file formats using the matplotlib savefig function.

Returns:

an LSD profile object, and a ‘Spectrum’ object containing the model spectrum (the fit to the observation, i.e. the convolution of the line mask and LSD profile)