sas.sascalc.invariant package¶
Submodules¶
sas.sascalc.invariant.invariant module¶
This module implements invariant and its related computations.
- author:
Gervaise B. Alina/UTK
- author:
Mathieu Doucet/UTK
- author:
Jae Cho/UTK
- author:
Paul Butler/NIST/UD/UTK – refactor in 2020
- class sas.sascalc.invariant.invariant.Extrapolator(data, model=None)¶
Bases:
object
Extrapolate I(q) distribution using a given model
- __dict__ = mappingproxy({'__module__': 'sas.sascalc.invariant.invariant', '__doc__': '\n Extrapolate I(q) distribution using a given model\n ', '__init__': <function Extrapolator.__init__>, 'fit': <function Extrapolator.fit>, '__dict__': <attribute '__dict__' of 'Extrapolator' objects>, '__weakref__': <attribute '__weakref__' of 'Extrapolator' objects>, '__annotations__': {}})¶
- __doc__ = '\n Extrapolate I(q) distribution using a given model\n '¶
- __init__(data, model=None)¶
Determine a and b given a linear equation y = ax + b
If a model is given, it will be used to linearize the data before the extrapolation is performed. If None, a simple linear fit will be done.
- Parameters:
data – data containing x and y such as y = ax + b
model – optional Transform object
- __module__ = 'sas.sascalc.invariant.invariant'¶
- __weakref__¶
list of weak references to the object
- fit(power=None, qmin=None, qmax=None)¶
Fit data for \(y = ax + b\) return \(a\) and \(b\)
- Parameters:
power – a fixed, otherwise None
qmin – Minimum Q-value
qmax – Maximum Q-value
- class sas.sascalc.invariant.invariant.Guinier(scale=1, radius=60)¶
Bases:
Transform
class of type Transform that performs operations related to guinier function
- __doc__ = '\n class of type Transform that performs operations related to guinier\n function\n '¶
- __init__(scale=1, radius=60)¶
- __module__ = 'sas.sascalc.invariant.invariant'¶
- _guinier(x)¶
Retrieve the guinier function after apply an inverse guinier function to x Compute \(F(x) = s * \exp\left(-(r x)^{2/3}\right)\).
- Parameters:
x – a vector of q values
- Also uses:
self.scale: \(s\), the scale value
self.radius: \(r\), the guinier radius value
- Returns:
F(x)
- evaluate_model(x)¶
return calculated I(q) for the model
Calculates the Guinier expression \(F(x)= s * \exp\left(-(r x)^{2/3}\right)\)
- evaluate_model_errors(x)¶
Returns the error on I(q) for the given array of q-values
- Parameters:
x – array of q-values
- extract_model_parameters(constant, slope, dconstant=0, dslope=0)¶
assign new value to the scale and the radius
- linearize_q_value(value)¶
Transform the input q-value for linearization
- Parameters:
value – q-value
- Returns:
q*q
- class sas.sascalc.invariant.invariant.InvariantCalculator(data, background=0, scale=1)¶
Bases:
object
Compute invariant if data is given. Can provide volume fraction and surface area if the user provides Porod constant and contrast values.
- Precondition:
the user must send a data of type DataLoader.Data1D the user provide background and scale values.
- Note:
Some computations depends on each others.
- __dict__ = mappingproxy({'__module__': 'sas.sascalc.invariant.invariant', '__doc__': '\n Compute invariant if data is given.\n Can provide volume fraction and surface area if the user provides\n Porod constant and contrast values.\n\n :precondition: the user must send a data of type DataLoader.Data1D\n the user provide background and scale values.\n\n :note: Some computations depends on each others.\n ', '__init__': <function InvariantCalculator.__init__>, 'background': <property object>, 'scale': <property object>, 'set_data': <function InvariantCalculator.set_data>, '_get_data': <function InvariantCalculator._get_data>, '_fit': <function InvariantCalculator._fit>, '_get_qstar': <function InvariantCalculator._get_qstar>, '_get_qstar_uncertainty': <function InvariantCalculator._get_qstar_uncertainty>, '_get_extrapolated_data': <function InvariantCalculator._get_extrapolated_data>, 'get_data': <function InvariantCalculator.get_data>, 'get_extrapolation_power': <function InvariantCalculator.get_extrapolation_power>, 'get_qstar_low': <function InvariantCalculator.get_qstar_low>, 'get_qstar_high': <function InvariantCalculator.get_qstar_high>, 'get_extra_data_low': <function InvariantCalculator.get_extra_data_low>, 'get_extra_data_high': <function InvariantCalculator.get_extra_data_high>, 'set_extrapolation': <function InvariantCalculator.set_extrapolation>, 'get_qstar': <function InvariantCalculator.get_qstar>, 'get_surface': <function InvariantCalculator.get_surface>, 'get_volume_fraction': <function InvariantCalculator.get_volume_fraction>, 'get_qstar_with_error': <function InvariantCalculator.get_qstar_with_error>, 'get_volume_fraction_with_error': <function InvariantCalculator.get_volume_fraction_with_error>, 'get_surface_with_error': <function InvariantCalculator.get_surface_with_error>, '__dict__': <attribute '__dict__' of 'InvariantCalculator' objects>, '__weakref__': <attribute '__weakref__' of 'InvariantCalculator' objects>, '__annotations__': {}})¶
- __doc__ = '\n Compute invariant if data is given.\n Can provide volume fraction and surface area if the user provides\n Porod constant and contrast values.\n\n :precondition: the user must send a data of type DataLoader.Data1D\n the user provide background and scale values.\n\n :note: Some computations depends on each others.\n '¶
- __init__(data, background=0, scale=1)¶
Initialize variables.
- Parameters:
data – data must be of type DataLoader.Data1D
background – Background value. The data will be corrected before processing
scale – Scaling factor for I(q). The data will be corrected before processing
- __module__ = 'sas.sascalc.invariant.invariant'¶
- __weakref__¶
list of weak references to the object
- _fit(model, qmin=1e-05, qmax=10, power=None)¶
fit data with function using data = self._get_data() fx = Functor(data , function) y = data.y slope, constant = linalg.lstsq(y,fx)
- Parameters:
qmin – data first q value to consider during the fit
qmax – data last q value to consider during the fit
power – power value to consider for power-law
function – the function to use during the fit
- Return a:
the scale of the function
- Return b:
the other parameter of the function for guinier will be radius for power_law will be the power value
- _get_data(data)¶
- Note:
this function must be call before computing any type of invariant
- Returns:
new data = self._scale x data - self._background
- _get_extrapolated_data(model, npts=1000, q_start=1e-05, q_end=10)¶
- Returns:
extrapolate data create from data
- _get_qstar(data)¶
Compute invariant for pinhole data. This invariant is given by:
q_star = x0**2 *y0 *dx0 +x1**2 *y1 *dx1 + ..+ xn**2 *yn *dxn for non smeared data q_star = dxl0 *x0 *y0 *dx0 +dxl1 *x1 *y1 *dx1 + ..+ dlxn *xn *yn *dxn for smeared data where n >= len(data.x)-1 dxl = slit height dQl dxi = 1/2*(xi+1 - xi) + (xi - xi-1) dx0 = (x1 - x0)/2 dxn = (xn - xn-1)/2
- Parameters:
data – the data to use to compute invariant.
- Return q_star:
invariant value for pinhole data. q_star > 0
- _get_qstar_uncertainty(data)¶
Compute invariant uncertainty with with pinhole data. This uncertainty is given as follows:
dq_star = math.sqrt[(x0**2*(dy0)*dx0)**2 + (x1**2 *(dy1)*dx1)**2 + ..+ (xn**2 *(dyn)*dxn)**2 ]
where n >= len(data.x)-1 dxi = 1/2*(xi+1 - xi) + (xi - xi-1) dx0 = (x1 - x0)/2 dxn = (xn - xn-1)/2 dyn: error on dy
- Parameters:
data
- Note:
if data doesn’t contain dy return “None”
- property background¶
- get_data()¶
- Returns:
self._data
- get_extra_data_high(npts_in=None, q_end=10, npts=20)¶
Returns the extrapolated data used for the high-Q invariant calculation. By default, the distribution will cover the data points used for the extrapolation. The number of overlap points is a parameter (npts_in). By default, the maximum q-value of the distribution will be Q_MAXIMUM, the maximum q-value used when extrapolating for the purpose of the invariant calculation.
- Parameters:
npts_in – number of data points for which the extrapolated data overlap
q_end – is the maximum value to uses for extrapolated data
npts – the number of points in the extrapolated distribution
- get_extra_data_low(npts_in=None, q_start=None, npts=20)¶
Returns the extrapolated data used for the loew-Q invariant calculation. By default, the distribution will cover the data points used for the extrapolation. The number of overlap points is a parameter (npts_in). By default, the maximum q-value of the distribution will be the minimum q-value used when extrapolating for the purpose of the invariant calculation.
- Parameters:
npts_in – number of data points for which the extrapolated data overlap
q_start – is the minimum value to uses for extrapolated data
npts – the number of points in the extrapolated distribution
- get_extrapolation_power(range='high')¶
- Returns:
the fitted power for power law function for a given extrapolation range
- get_qstar(extrapolation=None)¶
Compute the invariant of the local copy of data.
- Parameters:
extrapolation – string to apply optional extrapolation
- Return q_star:
invariant of the data within data’s q range
- Warning:
When using setting data to Data1D , the user is responsible of checking that the scale and the background are properly apply to the data
- get_qstar_high(high_q_limit=None)¶
Compute the invariant for extrapolated data at high q range.
Implementation:
data = self._get_extra_data_high() return self._get_qstar()
- Return q_star:
the invariant for data extrapolated at high q.
- get_qstar_low(low_q_limit=None)¶
Compute the invariant for extrapolated data at low q range.
Implementation:
data = self._get_extra_data_low() return self._get_qstar()
- Return q_star:
the invariant for data extrapolated at low q.
- get_qstar_with_error(extrapolation=None)¶
Compute the invariant uncertainty. This uncertainty computation depends on whether or not the data is smeared.
- Parameters:
extrapolation – string to apply optional extrapolation
- Returns:
invariant, the invariant uncertainty
- get_surface(contrast, porod_const, extrapolation=None)¶
Compute the specific surface from the data.
Historically, Sv was computed with the invariant and the Porod constant so as not to have to know the contrast in order to get the Sv as:
surface = (pi * V * (1- V) * porod_const) / q_star
However, that turns out to be a pointless exercise since it also requires a knowledge of the volume fractions and from the volume fraction and the invariant the contrast can be calculated as:
contrast**2 = q_star / (2 * pi**2 * V * (1- V))
Thus either way, mathematically it is always identical to computing with only the contrast and the Porod Constant. up to and including SasView versions 4.2.2 and 5.0.1 the implementation used the traditional circular approach.
Implementation:
Given the above, as of SasView 4.3 and 5.0.2 we compute Sv simply from the Porod Constant and the contrast between the two phases as: surface = porod_const / (2 * pi contrast**2)
- Parameters:
contrast – contrast between the two phases
porod_const – Porod constant
extrapolation – string to apply optional extrapolation. This will only be needed if and when the contrast term is calculated from the invariant.
- Returns:
specific surface
- get_surface_with_error(contrast, porod_const, extrapolation=None)¶
As of SasView 4.3 and 5.0.3, the specific surface is computed directly from the contrast and porod_constant wich are currently user inputs with no option for any uncertainty so no uncertainty can be calculated. However we include the uncertainty computation for future use if and when these values get an uncertainty. This is given as:
ds = sqrt[(s'_cp)**2 * dcp**2 + (s'_contrast)**2 * dcontrast**2]
where s’_x is the partial derivative of S with respect to x
which gives (this should be checked before using in anger):
ds = sqrt((dporod_const**2 * contrast**2 + 4 * (porod_const * dcontrast)**2) / (4 * pi**2 * contrast**6))
We also assume some users will never enter a value for uncertainty so allow for None even when it is an option.
- Parameters:
contrast – contrast value eventually with the error
porod_const – porod constant value eventually with the error
extrapolation – string to apply optional extrapolation. This will only be needed if and when the contrast term is calculated from the invariant.
- Return s, ds:
the surface, with its uncertainty
- get_volume_fraction(contrast, extrapolation=None)¶
Compute volume fraction is deduced as follows:
q_star = 2*(pi*contrast)**2* volume( 1- volume) for k = 10^(-8)*q_star/(2*(pi*|contrast|)**2) we get 2 values of volume: with 1 - 4 * k >= 0 volume1 = (1- sqrt(1- 4*k))/2 volume2 = (1+ sqrt(1- 4*k))/2 q_star: the invariant value included extrapolation is applied unit 1/A^(3)*1/cm q_star = self.get_qstar() the result returned will be 0 <= volume <= 1
- Parameters:
contrast – contrast value provides by the user of type float. contrast unit is 1/A^(2)= 10^(16)cm^(2)
extrapolation – string to apply optional extrapolation
- Returns:
volume fraction
- Note:
volume fraction must have no unit
- get_volume_fraction_with_error(contrast, extrapolation=None)¶
Compute uncertainty on volume value as well as the volume fraction This uncertainty is given by the following equation:
sigV = dV/dq_star * sigq_star
so that:
sigV = (k * sigq_star) /(q_star * math.sqrt(1 - 4 * k)) for k = 10^(-8)*q_star/(2*(pi*|contrast|)**2)
Notes:
10^(-8) converts from cm^-1 to A^-1
q_star: the invariant, in cm^-1A^-3, including extrapolated values if they have been requested
dq_star: the invariant uncertainty
dV: the volume uncertainty
The uncertainty will be set to -1 if it can’t be computed.
- Parameters:
contrast – contrast value
extrapolation – string to apply optional extrapolation
- Returns:
V, dV = volume fraction, error on volume fraction
- property scale¶
- set_data(data)¶
- set_extrapolation(range, npts=4, function=None, power=None)¶
Set the extrapolation parameters for the high or low Q-range. Note that this does not turn extrapolation on or off.
- Parameters:
range – a keyword set the type of extrapolation . type string
npts – the numbers of q points of data to consider for extrapolation
function – a keyword to select the function to use for extrapolation. of type string.
power – an power to apply power_low function
- class sas.sascalc.invariant.invariant.PowerLaw(scale=1, power=4)¶
Bases:
Transform
class of type transform that perform operation related to power_law function
- __annotations__ = {}¶
- __doc__ = '\n class of type transform that perform operation related to power_law\n function\n '¶
- __init__(scale=1, power=4)¶
- __module__ = 'sas.sascalc.invariant.invariant'¶
- _power_law(x)¶
- F(x) = scale* (x)^(-power)
when power= 4. the model is porod else power_law
- The model has three parameters: ::
x: a vector of q values
power: power of the function
scale : scale factor value
- Parameters:
x – array
- Returns:
F(x)
- evaluate_model(x)¶
given a scale and a radius transform x, y using a power_law function
- evaluate_model_errors(x)¶
Returns the error on I(q) for the given array of q-values :param x: array of q-values
- extract_model_parameters(constant, slope, dconstant=0, dslope=0)¶
Assign new value to the scale and the power
- linearize_q_value(value)¶
Transform the input q-value for linearization
- Parameters:
value – q-value
- Returns:
\(\log(q)\)
- class sas.sascalc.invariant.invariant.Transform¶
Bases:
object
Define interface that need to compute a function or an inverse function given some x, y
- __annotations__ = {}¶
- __dict__ = mappingproxy({'__module__': 'sas.sascalc.invariant.invariant', '__doc__': '\n Define interface that need to compute a function or an inverse\n function given some x, y\n ', 'linearize_data': <function Transform.linearize_data>, 'get_allowed_bins': <function Transform.get_allowed_bins>, 'linearize_q_value': <function Transform.linearize_q_value>, 'extract_model_parameters': <function Transform.extract_model_parameters>, 'evaluate_model': <function Transform.evaluate_model>, 'evaluate_model_errors': <function Transform.evaluate_model_errors>, '__dict__': <attribute '__dict__' of 'Transform' objects>, '__weakref__': <attribute '__weakref__' of 'Transform' objects>, '__annotations__': {}})¶
- __doc__ = '\n Define interface that need to compute a function or an inverse\n function given some x, y\n '¶
- __module__ = 'sas.sascalc.invariant.invariant'¶
- __weakref__¶
list of weak references to the object
- evaluate_model(x)¶
Returns an array f(x) values where f is the Transform function.
- evaluate_model_errors(x)¶
Returns an array of I(q) errors
- extract_model_parameters(constant, slope, dconstant=0, dslope=0)¶
set private member
- get_allowed_bins(data)¶
Goes through the data points and returns a list of boolean values to indicate whether each points is allowed by the model or not.
- Parameters:
data – Data1D object
- linearize_data(data)¶
Linearize data so that a linear fit can be performed. Filter out the data that can’t be transformed.
- Parameters:
data – LoadData1D instance
- linearize_q_value(value)¶
Transform the input q-value for linearization
sas.sascalc.invariant.invariant_mapper module¶
This module is a wrapper to a map function. It allows to loop through different invariant objects to call the same function
- sas.sascalc.invariant.invariant_mapper.get_qstar(inv, extrapolation=None)¶
Get invariant value (Q*)
- sas.sascalc.invariant.invariant_mapper.get_qstar_with_error(inv, extrapolation=None)¶
Get invariant value with uncertainty
- sas.sascalc.invariant.invariant_mapper.get_surface(inv, contrast, porod_const, extrapolation=None)¶
Get surface with uncertainty
- sas.sascalc.invariant.invariant_mapper.get_surface_with_error(inv, contrast, porod_const, extrapolation=None)¶
Get surface with uncertainty
- sas.sascalc.invariant.invariant_mapper.get_volume_fraction(inv, contrast, extrapolation=None)¶
Get volume fraction
- sas.sascalc.invariant.invariant_mapper.get_volume_fraction_with_error(inv, contrast, extrapolation=None)¶
Get volume fraction with uncertainty