ultrapyfit.utils package

Submodules

ultrapyfit.utils.ChirpCorrection module

Created on Mon Mar 15 21:40:16 2021

@author: lucas

class ultrapyfit.utils.ChirpCorrection.ChirpCorrection(time, data, wavelength, gvd_estimation, function=None)

Bases: object

Class that corrects the group velocity dispersion (GVD) or chirp from a data set. The algorithm is based on the one proposed by Nakayama et al. (https://doi.org/10.1063/1.1148398), which used the data itself to correct the chrip.

x

x-vector, normally time vector

Type

1darray

data

Array containing the data, the number of rows should be equal to the len(x)

Type

2darray

wavelength

wavelength vector

Type

1darray

corrected_data

Array containing the data corrected, has the same shape as the original data

Type

2darray

gvd

contains the estimation of the dispersion and is used to correct the data

Type

1darray

GVD_corrected

True if the data has been corrected

Type

bool

correct_chrip(verify=False)

Modified algorithm from Nakayama et al. to correct the chrip using the data itself.

verify: bool (default False)

If True a figure will pop out after the correction of the chirp, which allows to inspect the correction applied and decline or accept it

verifiedGVD()

Function pops out a window that allows to check the correction of the chirp.

class ultrapyfit.utils.ChirpCorrection.Dispersion

Bases: object

Class that calculate the dispersion of different dispersive medium using the Sellmeier equation. It only contain static methods. The default dispersive media are BK7, SiO2 and CaF2

BK7 = {'b1': 1.03961212, 'b2': 0.231792344, 'b3': 1.01046945, 'c1': 60006986697.0, 'c2': 20017914398.0, 'c3': 103.560653}
CaF2 = {'b1': 0.5675888, 'b2': 0.4710914, 'b3': 38.484723, 'c1': 0.050263605, 'c2': 0.1003909, 'c3': 34.64904}
SiO2 = {'b1': 0.69616, 'b2': 0.4079426, 'b3': 0.8974794, 'c1': 46791482597.0, 'c2': 13512063098.0, 'c3': 97.9340025}
static dispersion(wavelength, element_name, excitation)

Returns the index diffraction of a dispersive media at every wavelength pass (x). See https://en.wikipedia.org/wiki/Sellmeier_equation

Parameters

  • wavelength (1d numpy array or iterable) – Wavelength vector to calculate the dispersion

  • element_name (str) – a valid key for an attribute in the class, for example “BK7” “SiO2” and “CaF2”

  • excitation (int or float) – reference value to calculate the dispersion normally should be the “Excitaion (pump)” wavelength used to excite the sample

static fprime(x, b1, b2, b3, c1, c2, c3)

Returns the index diffraction of a dispersive media at every wavelength pass (x).

Parameters

  • x (int or float) – value of wavelength at which the dispersion is calculated

  • x – Wavelength vector to calculate the dispersion

  • b1, b2, b3, c1, c2, c3 – Values for the Sellmeier equation of a certain dispersive medium

static indexDifraction(x, b1, b2, b3, c1, c2, c3)

Returns the index diffraction of a dispersive media at every wavelength pass (x). See https://en.wikipedia.org/wiki/Sellmeier_equation

Parameters

  • x (int or float) – value of wavelength at which the dispersion is calculated

  • b1, b2, b3, c1, c2, c3 (float) – Values for the Sellmeier equation of a certain dispersive medium

class ultrapyfit.utils.ChirpCorrection.EstimationGVD(time, data, wavelength, excitation=None, function=None)

Bases: ChirpCorrection

Basic class to estimate and correct the GVD or chrip

time

normally the time vector

Type

1darray

data

Array containing the data, the number of rows should be equal to the len(x)

Type

2darray

wavelength

wavelength vector

Type

1darray

excitation

Contains the excitation wavelength of the pump laser used

Type

int or float (default None)

corrected_data

Array containing the data corrected, has the same shape as the original data

Type

2darray

gvd

contains the estimation of the dispersion and is used to correct the data

Type

1darray (default None)

chirp_corrector

use to correct the data

Type

instance of ChirpCorrection class

details(**kwargs)
estimate_GVD()

Method to estimate the GVD should be overwrite

estimate_GVD_from_grath()

Method to estimate the GVD graphically should be overwrite

get_corrected_data()
class ultrapyfit.utils.ChirpCorrection.EstimationGVDPolynom(time, data, wavelength, function=None)

Bases: EstimationGVD

Class that allows to calculate the dispersion GVD or chirp fitting a polynomial to the data.

estimate_GVD_from_grath(qt=None)

Allows to estimates the total chirp manually by clicking on the figure that pops out. The final chirp is estimated fitting a polynomial to the selected points in the figure.

fitPolGVD(x, y)

fit a polynomial to the data point X and Y, automatically calculates the dispersion (gvd attribute) with the output of the polynomial fit and the wavelength attribute vector.

static polynomi(params, x, order)

Returns the values of a polynomial from a lmfit parameters object

class ultrapyfit.utils.ChirpCorrection.EstimationGVDSellmeier(time, data, wavelength, excitation, function=None)

Bases: EstimationGVD

Class that calculate the dispersion GVD or chirp using the Sellmeier equation. It only contain static methods. The default dispersive media are BK7, SiO2 and CaF2

BK7

contains the millimeters of BK7

Type

int (Default 0)

SiO2

contains the millimeters of SiO2

Type

int (Default 0)

CaF2

contains the millimeters of CaF2

Type

int (Default 0)

GVD_offset

contains an offset time value, that can be used to correct the t0 of the experimental data

Type

int (default 0)

dispersion_BK7

contains dispersion curve of BK7

Type

1darray

dispersion_SiO2

contains dispersion curve of BK7

Type

1darray

dispersion_CaF2

contains dispersion curve of BK7

Type

1darray

estimate_GVD(CaF2=0, SiO2=0, BK7=0, offset=0, verify=True)

Estimates the total chirp as the sum of the dispersion introduced by all crystal elements

Parameters

  • BK7 (int (Default 0)) – contains the millimeters of BK7

  • SiO2 (int (Default 0)) – contains the millimeters of SiO2

  • CaF2 (int (Default 0)) – contains the millimeters of CaF2

  • offset (int (default 0)) – contains an offset time value, that can be used to correct the t0 of the experimental data

  • verify (bool (default True)) – If True, after correction a figure that allows to verify the correction will pop out.

estimate_GVD_from_grath(qt=None, function=None)

Allows to estimates the total chirp manually using sliders on the figure that pops out. The final chirp is the sum of the dispersion introduced by all elements.

ultrapyfit.utils.Preprocessing module

Created on Sun Nov 22 12:52:02 2020

@author: lucas

exception ultrapyfit.utils.Preprocessing.ExperimentException(msg)

Bases: Exception

General Purpose Exception.

class ultrapyfit.utils.Preprocessing.Preprocessing

Bases: object

Class containing main preprocessing functions as static methods

All methods assumes tha the data array pass has: 1) data is a 2darray that has no wavelength or time data points, time and wavelength are given as separate 1d arrays. 2) In the original data set the number of rows shape is the time points and the number of columns the wavelength points. (Some functions work independently of the orientation of the data)

The transient data pass should be:

data 2d_arrays (time point rows and wavelength columns) time 1d_arrays wavelength 1d_arrays e.g.: data.shape = (50,250)

data has 250 wavelength points and 50 time points

static average_time_points(data, time, starting_point, step, method='log', grid_dense=5)

Average time points collected (rows). This function can be use to average time points. Useful in multiprobe time-resolved experiments or flash- photolysis experiments recorded with a Photo multiplier tube where the number of time points is very long and are equally spaced. (The function assumes time vector is sorted from low to high values)

Parameters

  • data (ndarray) – Normally in the original data set the number of rows should be the time points and the number of columns the Columns points. Although this function works with transposes data sets

    e.g.: data.shape = (50,250)

    data has 250 wavelength points and 50 time points

  • time (1darray or) – time vector

  • starting_point (int or float) – time points higher than this the function will be applied

  • step (int, float or None) – step to consider for averaging data points

  • method (‘log’ or ‘constant’ (default: ‘log’)) – If constant: after starting_point the the function will return average time points between the step.

    If log the firsts step is step/grid_dense and the following points are (step/grid_dense)*n where n is point number

  • grid_dense (int or float higher than 1 (default: 5)) – density of the log grid that will be applied. To high values will not have effect if: start_point + step/grid_dense is lower than the difference between the first two consecutive points higher than start_point. The higher the value the higher the grid dense will be. return. (only applicable if method is ‘log’)

  • e.g. – time [1,2,3,4 …. 70,71,72,73,74] step = 10 starting_point = 5 method ‘constant’

    time points return are [1,2,3,4,5,10,20,30,40…]

    method ‘log’

    time points return are [1,2,3,4,5,6,9,14,21,30,41,54,67.5]

Return type

initial data and time vector averaged

static baseline_substraction(data, number_spec=2, only_one=False)

Subtract a initial spectrum or an average of initial spectra (normally before time = 0) to the entire data set.

Parameters

  • data (ndarray) – Original data set where the number of rows should be the time points and the number of columns the wavelength points

    e.g.: data.shape = (50,250)

    data has 250 wavelength points and 50 time points

  • number_spec (int or list) – This parameter defines the number of spectra to be subtracted. If int should be the index of the spectrum to be subtracted If list should be of length 2 and contain initial and final spectra index that want to be subtracted

  • only_one (bool (default False)) – if True only the spectrum (at index number_spec) is subtracted if False an average from the spectrum 0 to number_spec is subtracted (only applicable if number_spec is an int)

  • e.g.1 (number_spec = [2,5] an average from spectra 2 to 5 is subtracted) – (where 2 and 5 are included)

  • e.g.2 (number_spec = 5 an average from spectra 0 to 5 is subtracted) – if only_one = False; if not only spectrum 5 is subtracted

Return type

ndarray of size equal data

static calibration_with_polynom(array, pixels: list, wavelength: list, order=2)

Computes a calibration of an array from a set of given lists of points, pixels and wavelength, using a polynomial fit between the point in the two list.

Parameters

  • array (1darray) – Original data array to be calibrated

  • pixels (list) – list containing a set of values from the original array.

  • wavelength (list) –

    list containing a set of values to which the values given in the

    pixels list correspond in reality.

  • order (int (default 2)) – Order of the polynomial use to fit pixels and wavelength. Notice that the order should be smaller than the len of the list

Return type

ndarray of size equal data

static correct_chrip(data, wavelength, time, method='selmeiller', return_details=False)
static cut_columns(data, columns, mini=None, maxi=None, innerdata=None)

Cut columns of the data set and wavelength vector according to the closest values of mini and maxi margins given. (The function assumes column vector is sorted from low to high values)

Parameters

  • data (ndarray) – Normally in the original data set the number of rows should be the time points and the number of columns the Columns points. Although this function works with transposes data sets

    e.g.: data.shape = (50,250)

    data has 250 wavelength points and 50 time points

  • columns (1darray or None) – Wavelength vectors where regions are cut. If None an array from 0 to data number of columns is created and returned after cutting. The parameters mini and maxi should be given according to indexes

  • mini (int, float or None (default: None)) – data higher than this value is kept

  • maxi (int, float or None (default: None)) – data lower than this value is kept

  • innerdata (cut or select (default: None)) – Only need if both mini and right maxi are given indicates if data inside the mini and maxi limits should be cut or selected.

Return type

initial data and columns vector cut in the areas indicated

static cut_rows(data, rows, mini=None, maxi=None)

Cut rows of the data set and time vector according to the closest values of mini and maxi margins given. Contrary to cut_columns functions, inner cut are not available since in time resolved spectroscopy is not logical to cut a complete area of recorded times. Therefore, giving mini and maxi margins will result in selection of inner time values. (The function assumes rows vector is sorted from low to high values)

Parameters

  • data (ndarray) – Normally in the original data set the number of rows should be the time points and the number of columns the Columns points. Although this function works with transposes data sets

    e.g.: data.shape = (50,250)

    data has 250 wavelength points and 50 time points

  • rows (1darray or) – Normally time vector where regions are cut.

  • mini (int, float or None (default: None)) – data higher than this value is kept

  • maxi (int, float or None (default: None)) – data lower than this value is kept

Return type

initial data and rows vector cut in the areas indicated

static del_points(points, data, dimension_vector, axis=0)

Delete rows or columns from the data set according to the closest values given in points to the values found in dimension_vector. The length of dimension_vector should be equivalent to one of the data dimensions.

Notice that the function will automatically detect the dimension of the delete rows or columns in data if any of their dimensions is equal to the length of the dimension_vector. In case that both dimensions are the same the axis should be given, by default is 0, which is equivalent to the time dimension.

i.e.: points = [3,5] dimension_vector = [0.7, 1.4, 2.1, 2.8, 3.5, 4.2, 4.9, 5.6] len(dimension_vector) >>> 8 data.shape >>> (8, 10)

returns

return_data: data array where rows 3 and 6 are deleted return_data.shape >>> (6, 10) return_dimension_vector >>> [0.7, 1.4, 2.1, 3.5, 4.2, 5.6]

Parameters

  • points (int, list or None) – estimate values of time, the closes values of dimension_vector to the points given will be deleted

  • data (ndarray) – Original data set where the number of rows should be the time points and the number of columns the wavelength points

    e.g.: data.shape = (50,250) data has 250 wavelength points and 50 time points

  • dimension_vector (1darray) – wavelength or time vectors where points should be deleted

  • axis (int, 0 or 1 (default: None)) – indicates the axis where to cut in case data has identical number of rows and columns. (not needed in other cases)

Returns

  • initial data ndarrays with rows or columns deleted and dimension_vector

  • with points deleted.

static derivate_data(data, window_length=25, polyorder=3, deriv=1, mode='mirror')

Apply a Savitky-Golay filter to the data in the spectral range (rows). This function can be used to correct for baseline fluctuations and still perform a global fit or a single fit to obtain the decay times. Uses scipy.signal.savgol_filter. (check scipy documentation for more information)

Parameters

  • data (ndarray) – Normally in the original data set the number of rows should be the time points and the number of columns the Columns points. Although this function works with transposes data sets

    e.g.: data.shape = (50,250)

    data has 250 wavelength points and 50 time points

  • window_length (odd int value (default: 25)) – length defining the points for polynomial fitting

  • polyorder (int or float (default: 3)) – order of the polynomial fit

  • deriv (int, float or None (default: 1)) – order of the derivative after fitting

  • mode ((default: ‘mirror’)) – mode to evaluate bounders after derivation, check scipy.signal.savgol_filter for the different options

Return type

initial data and time vector averaged

static shit_time(time, value)

Shift the time vector by a value

Parameters

  • time (1darray) – time vector

  • value (int or float) – value shifting the time vector

Return type

time value shifted

static subtract_polynomial_baseline(data, wavelength, points, order=3)

Fit and subtract a polynomial to the data in the spectral range (rows). This function can be used to correct for baseline fluctuations typically found in time resolved IR spectroscopy.

Parameters

  • data (ndarray) – Normally in the original data set the number of rows should be the time points and the number of columns the Columns points. Although this function works with transposes data sets

    e.g.: data.shape = (50,250)

    data has 250 wavelength points and 50 time points

  • wavelength (1darray) – wavelength vector

  • points (list) – list containing the wavelength values where the different transient spectra should be zero

  • order (int or float (default: 3)) – order of the polynomial fit

Return type

initial data and time vector averaged

ultrapyfit.utils.divers module

Created on Fri Nov 13 15:13:09 2020

@author: Lucas

class ultrapyfit.utils.divers.DataSetCreator

Bases: object

Class that with static methods that can be use to generate examples of transient data, considering gaussian spectral shapes shapes. The output is a pandas dataFrame.

wave = DataSetCreator.generate_wavelength(350,700,500) time = DataSetCreator.generate_time(-2,500,120) shapes = DataSetCreator.generate_shape(5,wave, taus=[8, 30, 200],

signe = 0, sigma = 50)

data_set = DataSetCreator.generate_dataset(shapes, time, 0.12) After fitting the decay associated spectra should be equal to shapes, and the fitting times 8 30 and 200.

wave = DataSetCreator.generate_wavelength(400,700,500) peaks=[[470,550,650],[480,700],[500,600]] amplitudes=[[-10,-6,12],[-9,11],[-8,6]] fwhms=[[50,100,80],[40,70],[30,65]] shapes = DataSetCreator.generate_specific_shape(wave, taus=3, peaks=peaks, amplitudes=amplitudes, fwhms=fwhms) k1=1/5.0 k2=1/20.0 k3=1/100.0 kmatrix = [[-k1,0,0],[k1/3,-k2,0],[2*k1/3,0,-k3]] initials = [1.0,0,0] profiles = DataSetCreator.generate_profiles(500.0,5000,initials,kmatrix) data_set_conv = DataSetCreator.generate_dataset(shapes, profiles, 1.2) new_times = DataSetCreator.generate_time(data_set_conv.index[0],

data_set_conv.index[-1], 120)

data_set_conv_proj = DataSetCreator.timegrid_projection(data_set_conv,

new_times)

Above kmatrix represent model where species 1 bifurcates to species 2 and 3 (with 1/3 and 2/3 probablity, respectively), and each of them decay independently with 1/k2 and 1/k3. initials = [1/3.0, 1/3.0, 1/3.0] kmatrix = [[-k1,0,0],[0,-k2,0],[0,0,-k3]] Above kmatrix and initial conditions should generate just 3 exp decay (DAS equivalent) initials = [1.0,0,0] kmatrix = [[-k1,0,0],[k1,-k2,0],[0,k2,-k3]] Above kmatrix and initial conditions should generate sequential model (cascade, 1->2->3, EAS equivalent) Some comments about how to build kmatrix. It is just a matrix of rates, which when multiplied by concentration vector of given species results in derivative of concentration vector of the same/other species by time. In other words, dc_i/dt = sum of k_ij * c_j . In general derrivative of vector of c-s = kmatrix * vector of c-s. So for example, first row of kmatrix are k-s of species which decay to first species (positive values), except first one (k[0,0]) which must be negative because it describes decay of species one. (1) diagonal k-s must be negative, because they describe decay of given species, (2) If you sum all kij*cj parts in all rows, it should yield zero for the sum of populations to be preserved. If this condition is not satisfied, then it is still okay, assuming that there is more negative values and you are aware with the fact that your sum of c-s decays to zero (typical to TR spectroscopy). (3) Firstly you can start with defining diagonal elements, which are negative reciprocals of lifetimes of given species (4) Then You decide to which species each species decay, and you balance this negative diagonal k in other species which has lower energy in energy ladder of states. (5) You can skip point 4 and just let given species decay to nothing (usually GS) or you can also divide any diagonal k to some portions in more than one different species. Then you have splitting (bifurcation), so one species decay to more than one species. In general it means, that in each column of kmatrix sum of k-s must be zero (concentration preserved over time) or negative (concentration goes down, so species decay to GS and TA signal goes to zero). After fitting the data parameters should reproduce model described by kmatrix. This class does not use graphical model generator, because its intention is to test all fitting code, so everything need to be implemented separately, and possibly in a different way to avoid mistake-compensation. There are still some minor problems (odeint function gives sometimes NaNs at output, but works if you run it again, so it seems that some SAS inputs are crashing it, needs to be checked),nevertheless usually works ok and gives reasonable results.

Comment: It seems that when using generate_specific_shape instead of generate_shape there is no errors!

static add_noise(data, scale=0.0005)

add gaussian random noise to the data :Parameters: * data (pandas DataFrame) – dataFrame without noise

  • scale (float (default 0.0005)) – time vector

Return type

pandas data frame equal size of data

static derrivatives(cs, t, kmatrix)

computes derivatives of concentrations over time, this is callback function for odeint.

Parameters

  • cs (numpy array 1D) – concentration of each population

  • t (float) – given time point, does not contribute anyway

  • kmatrix (numpy array 2D) – matrix of k-s, shape[1] must match shape[0] of cs (to properly perform product of matrixes)

Returns

  • 1D numpy array with shape[0] equal to cs.shape[0]. represents

  • derrivatives of concentrations over time

  • here is simple example

  • [[k_11, k_12] [[c_1]

  • [k_21, k_22]] [c_2]]

static gauss(x, amp, cen, sigma)

basic gaussian function

static generate_dataset(shape, time, fwhm=None)

generate the data set from the initial spectral shape form. The data has no noise. This can be added using the add_noise function. :Parameters: * shape (pandas DataFrame) – initial value of the output vector

  • time (1darray or pd.DataFrame) – time vector with delays will trigger generation from DAS (sums of exps) or pd.DataFrame generated by DataSetCreator.generate_profiles function will trigger generation from SAS

  • fwhm (None or float) – if None the time evolution will start instantly at time zero if positive float value, evolution will be convolved with gaussian of given FWHM

Return type

pandas data frame. data.shape() >>> (len(time), shape.shape[1])

static generate_profiles(final, points, initials, kmatrix)

SAS equivalent of DataSetCreator.generate_time function. It always starts from time zero and timegrid is linear (it has to be for odeint) Later one can project the data into another nonlinear grid, to reduce size of the data.

Parameters

  • final (np array) – final value of the output vector

  • points (int) – length of output the array important note: array must dense enough to cover well even short delays (where rapid changes take place), otherwise differential equations may be solved unaccurately. later one can see reproject time grid and reduce it to reasonable size.

  • initials (numpy array 1D) – initial (at time zero) concentration of each population

  • kmatrix (numpy array 2D, dimensions equal to initials) – matrix of k-s describes evolution of the system

Returns

  • 1D numpy array with shape[0] equal to cs.shape[0]. represents

  • derrivatives of concentrations over time

  • here is simple example

  • [[k_11, k_12] [[c_1]

  • [k_21, k_22]] [c_2]]

static generate_shape(number, wave, taus, scale=100, signe=1, sigma=2.25)

!WARNING: Sometimes this function generates NaNs instead values. Should be checked. function to generate the initial shape (DAS) of the data set. The number of taus defines the shape of the output. returns a pandasDataFrame where the index are taus and the columns the wavelength. The parameters of the curves are ramdomly generated.

Parameters

  • number (int) – defines number of maxima/minima int the output shape. Should be greater than len(taus). e.g.: if number is 5 and taus=[8, 30, 200]. The output is a three row dataFrame, where two rows have two maxima/minima and the third only one (2+2+1 = 5)

  • wave (np array) – array containing the wavelength vector

  • taus (list (for example [8, 30, 200]) or int) – list containing the associated decay times of the data or number of DAS, but then DAS won’t be labelled by taus, still can be used as SAS

  • scale (int (default 100)) – controls the intensity of the output data

  • signe (-1, 0 1) – Defines the if the curve is positive or negative 1: all positive 0: can be positive or negative -1: all negative

  • sigma – default base sigma value of the Gaussian curves (The final is randomly attribute)

Return type

pandas data frame. data.shape() >>> (len(taus), len(wave))

static generate_specific_shape(wave, taus, peaks, amplitudes, fwhms)

Alternative function to generate the initial shape (DAS or SAS) of the data set. This is not-random replacement for generate_shape, where you specify every propery of spectra. Returns a pandasDataFrame where the index are taus or species number and the columns are the wavelength.

Parameters

  • wave (np array) – array containing the wavelength vector

  • taus (list (for example [8, 30, 200]) or int) – list containing the associated decay times of the data or number of DAS, but then DAS won’t be labelled by taus, still can be used as SAS

  • peaks (2D array / list of lists of floats) – Defines positions of the peaks in generated spectra. First dimension enumerates number of spectrum and must be aligned with taus number/size. Second dimension dspecifies number of peak in given spectrum. Different spectra can have different number of peaks inside.

  • amplitudes (2D array / list of lists of floats) – The same as above, but specifies amplitudes of peaks (nonzero, positive or negative). Note that peaks are normal gauss, so area under will be abs(peaks[i][i])*1.0

  • fwhms (2D array / list of lists of floats) – The same as above, but specifies FWHMs (widths) of peaks (values must be positive).

Return type

pandas data frame. data.shape() >>> (len(taus), len(wave))

static generate_time(init, final, points, space='lin-log')

returns a vector that should be use as time. The points can be linear logarithmic or in a combined spaced way. :Parameters: * init (int) – initial value of the output vector

  • final (np array) – final value of the output vector

  • points (int) – length of output the array

  • space (str; lin-log, linear or log (default lin-log)) – linear: points are linearly spaced log: points are spaced log10 scale lin-log: linearly spaced for values < 1 and log10 spaced for values > 1

Return type

1d array

static generate_wavelength(init, final, points)

returns a positive vector that should be use as wavelength. The points are equally spaced. :Parameters: * init (int) – initial value of the output vector

  • final (np array) – final value of the output vector

  • points (int) – length of output the array

Return type

1d array (positive)

static norm_gauss(x, fwhm, x0=0.0)

just normal (area=1) gaussian distribution

static timegrid_projection(input_data, time)

generate the data set from another dataset, with changed grid of delays designed to reduce the number and distribution of timepoints after generation from target model this is interpolation-only algorithm, no bucket-averaging!

Parameters

  • input_data (pandas DataFrame) – generated dataset from DataSetCreator.generate_dataset

  • time (1darray or pd.DataFrame) – time vector with delays, which will be used to reproject the data, generated by DataSetCreator.generate_time must be within existing time grid of input_data (otherwise error will be thrown!)

Return type

pandas DataFrame, just input with exchanged tme grid

class ultrapyfit.utils.divers.FiguresFormating

Bases: object

Class containing static methods for axis matplotlib formatting

static axis_labels(ax, x_label=None, y_label=None)

add labels to the axis ax

Parameters

  • ax (matplotlib axis) – axis containing the figure

  • x_label (str (default None)) – string containing the x label,

  • y_label (str (default None)) – string containing the y label

static cover_excitation(ax, x_range, x_vector)

add a white rectangle on top of an area in the figure. Typically use to cover the excitation of the laser in the spectra figure of a pump-probe UV-vis experiment.

Parameters

  • ax (matplotlib axis) – axis containing the figure

  • x_range (list or tupple of length 2) – contains the initial and and final x values of x vector (normally wavelength)

  • x_vector (array) – the x vector plotted in the figure

static format_figure(ax, data, x_vector, size=14, x_tight=False, set_ylim=True, val=50)

Deprecated function, style in combination with use_style decorator should be use to format figures.

format ax figures Always does:

-add minor tick -set ticks directions in -add tick in top and left sides -set tick labels in scientific notations -add x = 0 horizontal line. line_style = (–)

Set margins of the data figure in x and y directions according to the different parameters.

Parameters

  • ax (matplotlib axis) – axis containing the figure

  • data (np array) – array containing the data plotted. Is used to get minimum and maximum values and adjust the y margins if set_ylim is True

  • x_vector (array) – the x vector plotted in the figure

  • size (int) – size of the the tick labels

  • x_tight (bool (default False)) – If True, set tight the x axis If False set limits according to max(x_vector)/val

  • val (int or float) – value for adjusting x vector if x_tight is False

class ultrapyfit.utils.divers.LabBook(**kws)

Bases: object

Class object that can store in combination with book_annotate the functions ran names as attributes where the values are strings with the function parameters names and the values passed.

clean()

Clean the LabBook except name attribute if given

delete(key, element='all')

method similar to delattr function. It deletes an entry on the lab according to key

Parameters

  • key (str) – name of the attribute

  • element (“all” or int (default “all”)) – if “all” all entries will be deleted if int the element of the list at this index is deleted

property get_attributes

return a list of attributes in the labBokk

property get_protected_attributes
print(creation=True, print_protected=False, single_line=False)

Print all attributes and their values as a Lab report

Parameters

  • creation (bool (default True)) – If True prints the day and hour of the LabBook creation

  • print_protected (bool (default False)) – Define if protected attributes starting with “_” are printed

  • single_line (bool (default False)) – If True attributes that are not a list, the name and value will be printed in a single line

class ultrapyfit.utils.divers.ReadData

Bases: object

readData(path, wavelength=0, time=0, wave_is_row=True, separator=',', decimal='.')

similar parameters and explanations as in “read_data” function

class ultrapyfit.utils.divers.TimeMultiplicator(value)

Bases: Enum

An enumeration.

a = 1e-18
static chose(value: str)
f = 1e-15
m = 0.001
n = 1e-09
p = 1e-12
s = 1.0
y = 1e-24
z = 1e-21
μ = 1e-06
class ultrapyfit.utils.divers.TimeUnitFormater(multiplicator: TimeMultiplicator = TimeMultiplicator.p)

Bases: object

Class to format a time number in a string with the corresponding unit, after indicating the unit measure.

i.e.:

formater = TimeUnitFormater(“m”) # formater for milisecond measurement

formater.value_formated(3046) >>> ‘3.05 s’

formater.value_formated(3046E-7) >>> ‘0.30 μs’

formater.value_formated(3046E3) >>> ‘50.77 mins’

formater.value_formated(3046E3, 4) >>> ‘50.7667 mins’

property multiplicator
value_formated(value, decimal=2)

Function to transform the number to string :Parameters: * value (int or float) – Value to be formatted

  • decimal (int (default 2)) – number of decimal numbers of the output string

class ultrapyfit.utils.divers.UnvariableContainer(**kws)

Bases: LabBook

Object where once an attribute has been set cannot be modified if self.__frozen = True

ultrapyfit.utils.divers.book_annotate(container, extend=True)

Decorator with arguments. This decorator is working only with LabBook class, or an object with modified __setattr__ method.

It is use to create a lab book where the functions names and parameters names and values given are saved in container (VariableContainer class). VariableContainer has a method print() for printing the lab book.

ultrapyfit.utils.divers.book_annotate_all_methods(book=None, cls=None)
ultrapyfit.utils.divers.define_weights(time, rango, typo='constant', val=5)

Returns a an array that can be apply in global fit functions as weights. The weights can be use to define areas where the minimizing functions is not reaching a good results, or to define areas that are more important than others in the fit. The fit with weights can be inspect as any other fit with the residual plot. A small constant value is generally enough to achieve the desire goal.

Parameters

  • time (1darray or None) – time vectors. the weight vector will have the same length w

  • rango (list (length 2)) – list containing initial and final time values of the range where the weights will be applied

  • typo (str (constant, exponential, r_exponential or exp_mix)) – defines the type of weighting vector returned

    constant: constant weighting value in the range exponential: the weighting value increase exponentially r_exponential: the weighting value decrease exponentially mix_exp: the weighting value increase and then decrease exponentially

    constant value 5, [1,1,1,1,…5,5,5,5,5,….1,1,1,1,1] exponential for val= 2 [1,1,1,1,….2,4,9,16,25,….,1,1,1,]

    for val= 3 [1,1,1,1,….3,8,27,64,125,….,1,1,1,]

    r_exponential [1,1,1,1,…25,16,9,4,2,…1,1,1,] exp_mix [1,1,1,1,…2,4,9,4,2,…1,1,1,]

  • val (int (default 5)) – value for defining the weights

Returns

  • a dictionary with the keys (parameters pass plus “apply”: True)

  • and “vector” (weighting vector. The dictionary can be used as kwargs)

  • in the global fitting function. Notice that only if apply is set

  • to True then the fitting will consider the weights vector.

ultrapyfit.utils.divers.froze_it(cls)
ultrapyfit.utils.divers.read_data(path, wavelength=0, time=0, wave_is_row=False, separator=',', decimal='.')

Read a data file from the indicated path and returns three arrays with shapes uses in the ultrapyfit. The function is bases in pandas read_csv, and uses the ReadData class.

For the rows or columns corresponding to the wavelength and time vectors the function deals with non numerical values such as units names (e.g.: ‘nm’ ‘ps’, ‘ns’), words and number in scientific notation E or e in any of the forms and combinations. For the rest of values (data values) the function assumes they are homogeneous. The function eliminates from the data rows or columns with non numerical numbers (Nan) in all the entries if not they are set to zero. It also sort the time points if these where non sorted as can be the case with some multi-probe experimental outputs data files.

The arrays return are:

time: 1darray of length equal to the number of rows in data

data: 2darray, where rows correspond to the time direction

and wavelength to the columns

wavelength: 1darray of length equal to the number of columns

in data

Parameters

  • path (str) – path to the data file

  • wavelength (int (default 0)) – defines the element where to find the wavelength vector in its direction which is defined by wave_is_row parameter. i.e.: if wavelength correspond to columns, wavelength=0 indicates is the first column of the data file if wavelength correspond to rows, then wavelength=0 is first row

  • time (int (default 0)) – defines the element where to find the time vector in its direction which is defined by wave_is_row parameter. i.e.: if times correspond to columns, time=0 indicates is the first column of the data file

  • wave_is_row (bool (default False)) – defines if in the original data set the wavelength correspond to the rows.

  • separator (str (default ‘,’)) – defines the separator in the data (any value that can be used in pandas read_csv is valid. For tab uses

  • decimal (int (default ‘.’)) – defines the decimal point in the data

Return type

3 arrays corresponding to time, data, and wavelength

ultrapyfit.utils.divers.select_traces(data, wavelength=None, space=10, points=1, avoid_regions=None)

select traces in the wavelength range

Parameters

  • data (ndarray) – Normally in the original data set the number of rows should be the time points and the number of columns the Columns points. Although this function works with transposes data sets

    e.g.: data.shape = (50,250)

    data has 250 wavelength points and 50 time points

  • wavelength (1darray or None) – Wavelength vectors where traces are selected. The len(wavelength), should be equal to the number of columns of data

    If None an array from 0 to data number of columns is created and returned after cutting. The parameters space should be given according to indexes

  • space (int or list or “auto” (default 10)) – If type(space) = int: a series of traces separated by the value indicated will be selected. If type(space) = list: the traces in the list will be selected. If space = auto, the number of returned traces is 10 and equally spaced along the wavelength vector and points is set to 0

  • points (int (default 1)) – binning points surrounding the selected wavelengths. e. g.: if point is 1 trace = mean(index-1, index, index+1)

  • avoid_regions (list of list (default None)) – Defines wavelength regions that are avoided in the selection when space is an integer. The sub_list should have two elements defining the region to avoid in wavelength values i. e.: [[380,450],[520,530] traces with wavelength values between

    380-450 and 520-530 will not be selected

Returns

  • 2d array with a selection of data traces, and 1darray with the corresponding

  • wavelength values

ultrapyfit.utils.divers.solve_kmatrix(exp_no, params)

Resolve the k_matrix from a parameters object for a target fit

Parameters

  • exp_no (int) – number of component of the K_matrix (diagonal elements)

  • params (lmfit parameters object) – object containing the parameters

Return type

Coefficients of each component eigenvalues and eigen matrix

Module contents