ilex.data

acf(x, outs='unique')

Calculate normalised Auto-Correlation function using ‘fft’ method of real-valued data. If NaN values are present, the acf function will use a direct summation approach that ignores any NaN values.

Parameters:

• x (np.ndarray) – data array, 1D vector

• outs (str, optional) –

  describes output of acf function, by default “unique”

  [unique] - Take positive acf lags, exclude zero-lag peak [all] - Take full acf, including positive, negative and zero lags

Returns:

Auto-Correlation of x data

Return type:

np.ndarray

average(x: numpy.ndarray, axis: int = 0, N: int = 10, nan=False)

average in either frequency or time

Parameters:

• x (ndarray) – data to average over

• axis (int) – axis to average over

• N (int) – Averaging/donwsampling factor

• nan (bool, optional) – If True, using nanmean to ignore NaN values in array ‘x’, by default False

Returns:

x – Averaged data

Return type:

ndarray

calc_L(Q, U, Qerr=None, Uerr=None)

Calculate L

Parameters:

• Q (np.ndarray or float) – Stokes Q data

• U (np.ndarray or float) – Stokes U data

• Qerr (np.ndarray or float) – Stokes Q error

• Uerr (np.ndarray or float) – Stokes U error

Returns:

• L (np.ndarray) – L data

• Lerr (np.ndarray) – L errors

calc_Ldebiased(Q, U, Ierr, Qerr=None, Uerr=None)

Calculate De-biased Linear polarisation fraction (see Everett & Weisberg+2001)

Parameters:

• Q (np.ndarray) – Stokes Q data

• U (np.ndarray) – Stokes U data

• Ierr (np.ndarray) – Stokes U err data

• Qerr (np.ndarray) – Stokes Q error

• Uerr (np.ndarray) – Stokes U error

Returns:

• L_debias (np.ndarray) – Stokes L debias

• Lerr (np.ndarray) – L errors

calc_P(Q, U, V, Qerr=None, Uerr=None, Verr=None)

Calculate P

Parameters:

• Q (np.ndarray or float) – Stokes Q data

• U (np.ndarray or float) – Stokes U data

• V (np.ndarray or float) – Stokes V data

• Qerr (np.ndarray or float) – Stokes Q error

• Uerr (np.ndarray or float) – Stokes U error

• Verr (np.ndarray or float) – Stokes V error

Returns:

• P (np.ndarray) – P data

• Perr (np.ndarray) – P errors

calc_PA(Q, U, Qerr=None, Uerr=None, rad2deg=False)

Calculate Position Angle (PA) and PA angle

Parameters:

• Q (np.ndarray) – Stokes Q data

• U (np.ndarray) – Stokes U data

• Qerr (np.ndarray) – Stokes Q err data

• Uerr (np.ndarray) – Stokes U err data

• rad2deg (bool, optional) – If true, converts output to degrees, by default is False

Returns:

• PA (np.ndarray) – Position Angle (PA)

• PAerr (np.ndarray) – Position Angle err

calc_PAdebiased(stk, Ldebias_threshold=2.0, rad2deg=False)

Calculate time-dependant Position Angle masked using stokes L debiased

Parameters:

• stk (Dict(np.ndarray)) –

  Dictionary of Stokes data

  [tQ] - Stokes Q dynamic spectra

  [tU] - Stokes U dynamic spectra

  [tQerr] - Stokes Q average rms over time

  [tUerr] - Stokes U average rms over time

  [tIerr] - Stokes I average rms over time

• Ldebias_threshold (float, optional) – sigma threshold for masking PA, by default 2.0

• rad2deg (bool, optional) – If true, converts output to degrees, by default is False

Returns:

• PA (np.ndarray) – Position Angle (PA)

• PAerr (np.ndarray) – Position Angle err

calc_Pdebiased(Q, U, V, Ierr, Qerr=None, Uerr=None, Verr=None)

Calculate De-biased Linear polarisation fraction then calculate total polarisation (see Everett & Weisberg+2001)

Parameters:

• Q (np.ndarray) – Stokes Q data

• U (np.ndarray) – Stokes U data

• V (np.ndarray) – Stokes V data

• Ierr (np.ndarray) – Stokes U err data

• Qerr (np.ndarray) – Stokes Q error

• Uerr (np.ndarray) – Stokes U error

• Verr (np.ndarray) – Stokes V error

Returns:

• P_debias (np.ndarray) – P debias

• Perr (np.ndarray) – P errors

calc_freqs(cfreq, bw=336.0, df=1.0, upper=True)

Calculate Frequencies

Parameters:

• cfreq (float) – Central frequency [MHz]

• bw (float, optional) – Bandwidth [MHz], by default 336.0

• df (float, optional) – channel width [MHz], by default 1.0

• upper (bool, optional) – If true, freq band starts at top, by default True

Returns:

freqs – Frequency array

Return type:

np.ndarray

calc_ratio(I, X, Ierr=None, Xerr=None)

Calculate Stokes Ratio X/I

Parameters:

• I (np.ndarray) – Stokes I data

• X (np.ndarray) – Stokes [X] data, usually either Q, U or V

• Ierr (np.ndarray, optional) –

  Stokes I err data, by default None, if both Ierr and Xerr is given

  Stokes X/I err will also be calculated and returned

• Xerr (np.ndarray, optional) – Stokes [X] err data, by default None

Returns:

• XI (np.ndarray) – Stokes X/I data

• XIerr (np.ndarray, optional) – Stokes X/I err data, by default None

calc_stokes_abs_debias(X, Ierr)

Calculate the absolute Stokes profile, debiased as outlined in Karastergiou et al. 2003 and Posselt et al. 2022.

Works best if the Stokes profile is zero-mean, i.e. baseline subtracted.

Parameters:

• X (np.array or array-like) – Stokes profile

• Ierr (Uncertainties in Stokes I profile)

ccf(x, y, outs='unique')

Calculate normalised Cross-Correlation function using ‘fft’ method of real-valued data. Does NOT support NaN values

Parameters:

• x (np.ndarray) – data array, 1D

• y (np.ndarray) – data array, 1D

• outs (str, optional) –

  describes output of ccf function, by default “unique”

  [unique] - Take positive acf lags, including zero-lag peak [all] - Take full acf, including positive, negative and zero lags

Returns:

Cross-Correlation of x data

Return type:

np.ndarray

combine_zapchan(chan1, chan2)

Combine two zapchan strings together without duplication. If chan1 is NoneType, return chan2

Parameters:

• chan1 (str) – String of current channels

• chan2 (str) – String of channels to add

Returns:

zapstr – combined String of channels to zap

Return type:

str

downsample(x: numpy.ndarray, axis: int = -1, N: int = 1, nan=False, mode='mean')

Downsample in either frequency or time

Parameters:

• x (ndarray) – data to average over

• axis (int) – axis to average over

• N (int) – donwsampling factor

• nan (bool, optional) – If True, using nanmean to ignore NaN values in array ‘x’, by default False

• mode (str) – Method of downsampling, [“mean”, “sum”]

Returns:

x – Averaged data

Return type:

ndarray

f_weight(x, fW)

Apply frequency weights on a 2D array, it is assumed that the freq axis is axis = 0

Parameters:

• x (np.ndarray) – 2D array, (f, t)

• fW (np.ndarray or float) – frequency weights

Returns:

weighted 2D array

Return type:

np.ndarray

fday_rot(Q, U, f, RM, f0=None, pa0=0.0)

Apply Faraday rotation to 1D or 2D Stokes data

Parameters:

• Q (np.ndarray) – Stokes Q data

• U (np.ndarray) – Stokes U data

• f (np.ndarray) – frequency array

• RM (float) – Rotation Measure [rad/m2]

• f0 (float) – reference frequency [MHz]

• pa0 (float, optional) – reference position angle [rad], by default 0.0

Returns:

• Qrot (np.ndarray) – de-faraday rotated Stokes Q

• Urot (np.ndarray) – de-faraday rotated Stokes U

get_zapstr(chan, freq)

Create string of channels to zap based on given nan frequencies in stokes I dynamic spectrum

Parameters:

• chan (np.ndarray or array-like) – Stokes I freq array

• freq (np.ndarray or array-like) – Array of frequency values in [MHz]

Returns:

zap_str – string of frequencies to zap using zap_chan function

Return type:

str

norm(x, method='abs_max', nan=False)

Normalise data

Parameters:

• x (np.ndarray) – data to normalise

• method (str, optional) –

  method of normalising, by default “abs_max”

  [abs_max] - Normalise using absolute maximum abs(max)

  [max] - Normalise using maximum

  [unit] - normalise data between -1 and 1 - not implemented

• nan (bool, optional) – If True, using nanmax to ignore NaN values in array ‘x’, by default False

Returns:

normalised data

Return type:

np.ndarray

pslice(x: numpy.ndarray, start: float, end: float, axis: int = 0)

Slice 1D or 2D data in phase, between 0.0-1.0 which represents the start and end of ndarray along given axis. If array is 1D, given axis is set to 0.

Parameters:

• x (np.ndarray) – 1D or 2D data array

• start (float) – starting point of slice

• end (float) – ending point of slice

• axis (int, optional) – axis to slice along, can be 0 or 1(-1)

Returns:

y – sliced 1D or 2D data array

Return type:

np.ndarray

residuals(y, n=5)

Calculate residuals of a data array by subtracting the mean model. This function can handle NaN values

Parameters:

• y (np.ndarray) – data array

• n (int, optional) – max order for polynomial to fit to mean model of y, by default 5

Returns:

residuals of y

Return type:

np.ndarray

rotate_data(A, B, angle)

Rotate data in 2D

Parameters:

• A (np.ndarray) – First array

• B (np.ndarray) – Second array

• angle (float) – angle [rad] to rotate A and B in 2D

Returns:

• X (np.ndarray) – First array rotated

• Y (np.ndarray) – Second array rotated

scrunch(x: numpy.ndarray, axis: int = 0, weights=None, nan=False)

Scrunch data along a given axis, weights may also be applied.

Parameters:

• x (np.ndarray) – data to scrunch

• axis (int, optional) – axes to scrunch over, by default 0

• weights (array-like or float, optional) – weights to apply during scrunching, by default None

• nan (bool, optional) – If True, using nanmean to ignore NaN values in array ‘x’, by default False

Returns:

y – Weighted and scrunched data

Return type:

np.ndarray

t_weight(x, tW)

Apply time weights on a 2D array, it is assumed that the time axis is axis = 1

Parameters:

• x (np.ndarray) – 2D array, (f, t)

• fW (np.ndarray or float) – time weights weights

Returns:

weighted 2D array

Return type:

np.ndarray

unwrap_pa(f, pa, rm, pa0)

Unwrap polarisation position angle (PA) with a given RM

zap_chan(f, zap_str)

Zap channels, assumes contiguous frequency array

Parameters:

• f (np.ndarray) – frequency array used for zapping

• zap_str (str) –

  string used for zapping channels, in format -> “850, 860, 870:900”

  each element seperated by a ‘,’ is a seperate channel. If ‘:’ is used, user can specify a range of values

  i.e. 870:900 -> from channel 870 to 900 inclusive of both.

Returns:

y – zapped indicies in frequency

Return type:

np.ndarray