modalities.fmri.utils¶
Module: modalities.fmri.utils
¶
This module defines some convenience functions of time.
interp : an expresion for a interpolated function of time
- linear_interp : an expression for a linearly interpolated function of
- time
step_function : an expression for a step function of time
events : a convenience function to generate sums of events
blocks : a convenience function to generate sums of blocks
convolve_functions : numerically convolve two functions of time
fourier_basis : a convenience function to generate a Fourier basis
Functions¶
-
nipy.modalities.fmri.utils.
blocks
(intervals, amplitudes=None, name=None)¶ Step function based on a sequence of intervals.
Parameters: intervals : (S,) sequence of (2,) sequences
Sequence (S0, S1, ... S(N-1)) of sequences, where S0 (etc) are sequences of length 2, giving ‘on’ and ‘off’ times of block
amplitudes : (S,) sequence of float, optional
Optional amplitudes for each block. Defaults to 1.
name : None or str, optional
Name of the convolved function in the resulting expression. Defaults to one created by
utils.interp
.Returns: b_of_t : sympy expr
Sympy expression b(t) where b is a sympy anonymous function of time that implements the block step function
Examples
>>> on_off = [[1,2],[3,4]] >>> tval = np.array([0.4,1.4,2.4,3.4]) >>> b = blocks(on_off) >>> lam = lambdify_t(b) >>> lam(tval) array([ 0., 1., 0., 1.]) >>> b = blocks(on_off, amplitudes=[3,5]) >>> lam = lambdify_t(b) >>> lam(tval) array([ 0., 3., 0., 5.])
-
nipy.modalities.fmri.utils.
convolve_functions
(f, g, f_interval, g_interval, dt, fill=0, name=None, **kwargs)¶ Expression containing numerical convolution of fn1 with fn2
Parameters: f : sympy expr
An expression that is a function of t only.
g : sympy expr
An expression that is a function of t only.
f_interval : (2,) sequence of float
The start and end of the interval of t over which to convolve values of f
g_interval : (2,) sequence of floats
Start and end of the interval of t over to convolve g
dt : float
Time step for discretization. We use this for creating the interpolator to form the numerical implementation
fill : None or float
Value to return from sampling output fg function outside range.
name : None or str, optional
Name of the convolved function in the resulting expression. Defaults to one created by
utils.interp
.**kwargs : keyword args, optional
Any other arguments to pass to the
interp1d
function in creating the numerical funtion for fg.Returns: fg : sympy expr
An symbolic expression that is a function of t only, and that can be lambdified to produce a function returning the convolved series from an input array.
Examples
>>> from nipy.algorithms.statistics.formula.formulae import Term >>> t = Term('t')
This is a square wave on [0,1]
>>> f1 = (t > 0) * (t < 1)
The convolution of
f1
with itself is a triangular wave on [0, 2], peaking at 1 with height 1>>> tri = convolve_functions(f1, f1, [0, 2], [0, 2], 1.0e-3, name='conv')
The result is a symbolic function
>>> print tri conv(t)
Get the numerical values for a time vector
>>> ftri = lambdify(t, tri) >>> x = np.arange(0, 2, 0.2) >>> y = ftri(x)
The peak is at 1 >>> x[np.argmax(y)] 1.0
-
nipy.modalities.fmri.utils.
define
(name, expr)¶ Create function of t expression from arbitrary expression expr
Take an arbitrarily complicated expression expr of ‘t’ and make it an expression that is a simple function of t, of form
'%s(t)' % name
such that when it evaluates (vialambdify
) it has the right values.Parameters: expr : sympy expression
with only ‘t’ as a Symbol
name : str
Returns: nexpr: sympy expression :
Examples
>>> t = Term('t') >>> expr = t**2 + 3*t >>> print expr 3*t + t**2 >>> newexpr = define('f', expr) >>> print newexpr f(t) >>> f = lambdify_t(newexpr) >>> f(4) 28 >>> 3*4+4**2 28
-
nipy.modalities.fmri.utils.
events
(times, amplitudes=None, f=DiracDelta, g=a)¶ Return a sum of functions based on a sequence of times.
Parameters: times : sequence
vector of onsets length $N$
amplitudes : None or sequence length $N$, optional
Optional sequence of amplitudes. None (default) results in sequence length $N$ of 1s
f : sympy.Function, optional
Optional function. Defaults to DiracDelta, can be replaced with another function, f, in which case the result is the convolution with f.
g : sympy.Basic, optional
Optional sympy expression function of amplitudes. The amplitudes, should be represented by the symbol ‘a’, which will be substituted, by the corresponding value in amplitudes.
Returns: sum_expression : Sympy.Add
Sympy expression of time $t$, where onsets, as a function of $t$, have been symbolically convolved with function f, and any function g of corresponding amplitudes.
Examples
We import some sympy stuff so we can test if we’ve got what we expected
>>> from sympy import DiracDelta, Symbol, Function >>> from nipy.modalities.fmri.utils import T >>> evs = events([3,6,9]) >>> evs == DiracDelta(-9 + T) + DiracDelta(-6 + T) + DiracDelta(-3 + T) True >>> hrf = Function('hrf') >>> evs = events([3,6,9], f=hrf) >>> evs == hrf(-9 + T) + hrf(-6 + T) + hrf(-3 + T) True >>> evs = events([3,6,9], amplitudes=[2,1,-1]) >>> evs == -DiracDelta(-9 + T) + 2*DiracDelta(-3 + T) + DiracDelta(-6 + T) True
-
nipy.modalities.fmri.utils.
fourier_basis
(freq)¶ sin and cos Formula for Fourier drift
The Fourier basis consists of sine and cosine waves of given frequencies.
Parameters: freq : sequence of float
Frequencies for the terms in the Fourier basis.
Returns: f : Formula
Examples
>>> f=fourier_basis([1,2,3]) >>> f.terms array([cos(2*pi*t), sin(2*pi*t), cos(4*pi*t), sin(4*pi*t), cos(6*pi*t), sin(6*pi*t)], dtype=object) >>> f.mean _b0*cos(2*pi*t) + _b1*sin(2*pi*t) + _b2*cos(4*pi*t) + _b3*sin(4*pi*t) + _b4*cos(6*pi*t) + _b5*sin(6*pi*t)
-
nipy.modalities.fmri.utils.
interp
(times, values, fill=0, name=None, **kw)¶ Generic interpolation function of t given times and values
Imterpolator such that:
f(times[i]) = values[i]
- if t < times[0] or t > times[-1]:
- f(t) = fill
See
scipy.interpolate.interp1d
for details of interpolation types and other keyword arguments. Default is ‘kind’ is linear, making this function, by default, have the same behavior aslinear_interp
.Parameters: times : array-like
Increasing sequence of times
values : array-like
Values at the specified times
fill : None or float, optional
Value on the interval (-np.inf, times[0]). Default 0. If None, raises error outside bounds
name : None or str, optional
Name of symbolic expression to use. If None, a default is used.
**kw : keyword args, optional
passed to
interp1d
Returns: f : sympy expression
A Function of t.
Examples
>>> s = interp([0,4,5.],[2.,4,6]) >>> tval = np.array([-0.1,0.1,3.9,4.1,5.1]) >>> res = lambdify_t(s)(tval)
0 outside bounds by default
>>> np.allclose(res, [0, 2.05, 3.95, 4.2, 0]) True
-
nipy.modalities.fmri.utils.
lambdify_t
(expr)¶ Return sympy function of t expr lambdified as function of t
Parameters: expr : sympy expr
Returns: func : callable
Numerical implementation of function
-
nipy.modalities.fmri.utils.
linear_interp
(times, values, fill=0, name=None, **kw)¶ Linear interpolation function of t given times and values
Imterpolator such that:
f(times[i]) = values[i]
- if t < times[0] or t > times[-1]:
- f(t) = fill
This version of the function enforces the ‘linear’ kind of interpolation (argument to
scipy.interpolate.interp1d
).Parameters: times : array-like
Increasing sequence of times
values : array-like
Values at the specified times
fill : None or float, optional
Value on the interval (-np.inf, times[0]). Default 0. If None, raises error outside bounds
name : None or str, optional
Name of symbolic expression to use. If None, a default is used.
**kw : keyword args, optional
passed to
interp1d
Returns: f : sympy expression
A Function of t.
Examples
>>> s = linear_interp([0,4,5.],[2.,4,6]) >>> tval = np.array([-0.1,0.1,3.9,4.1,5.1]) >>> res = lambdify_t(s)(tval)
0 outside bounds by default
>>> np.allclose(res, [0, 2.05, 3.95, 4.2, 0]) True
-
nipy.modalities.fmri.utils.
step_function
(times, values, name=None, fill=0)¶ Right-continuous step function of time t
Function of t such that
f(times[i]) = values[i]
- if t < times[0]:
- f(t) = fill
Parameters: times : (N,) sequence
Increasing sequence of times
values : (N,) sequence
Values at the specified times
fill : float
Value on the interval (-np.inf, times[0])
name : str
Name of symbolic expression to use. If None, a default is used.
Returns: f_t : sympy expr
Sympy expression f(t) where f is a sympy implemented anonymous function of time that implements the step function. To get the numerical version of the function, use
lambdify_t(f_t)
Examples
>>> s = step_function([0,4,5],[2,4,6]) >>> tval = np.array([-0.1,3.9,4.1,5.1]) >>> lam = lambdify_t(s) >>> lam(tval) array([ 0., 2., 4., 6.])