confusius.timing¶

Convert timings from one volume acquisition reference to another.

Parameters:

• time ¶

  (array_like) –

  Input timings in any physical time unit.

• volume_duration ¶

  (float or array_like) –

  Duration of one volume in the same units as time. May be a scalar or one duration per input timing.

• from_reference ¶

  ((start, center, end), default: "start" ) –

  Reference point used by the input timings.

• to_reference ¶

  ((start, center, end), default: "start" ) –

  Reference point to convert the timings to.

Returns:

• ndarray –

  Converted timings in the same units as time.

Convert time values between units.

Parameters:

• values ¶

  (array_like) –

  Time values to convert.

• from_unit ¶

  (str or None) –

  Current unit of the values.

• to_unit ¶

  (str or None, default: "s" ) –

  Target unit of the values.

• raise_on_missing ¶

  (bool, default: False ) –

  Whether to raise when either unit is missing.

• raise_on_unknown ¶

  (bool, default: False ) –

  Whether to raise when either unit is not recognized.

Returns:

• ndarray –

  Time values converted to to_unit.

Return a representative time step for the time coordinate.

Parameters:

• data ¶

  (DataArray) –

  DataArray containing the time coordinate.

• unit ¶

  (str or None, default: None ) –

  Unit in which to evaluate the representative step. If None, use the native units of the time coordinate.

• uniformity_tolerance ¶

  (float, default: 1e-2 ) –

  Maximum allowed per-interval relative deviation from the median consecutive difference for the time coordinate to be considered uniform.

Returns:

• step ( float or None ) –

  Representative time step in unit when provided, otherwise in the native units of the time coordinate. Returns None if fewer than two time points are available.

• approximate ( bool ) –

  Whether the returned step is a median approximation derived from non-uniform sampling.

Return the factor that converts a time coordinate to seconds.

Parameters:

• data ¶

  (DataArray) –

  DataArray containing a time coordinate.

Returns:

• float –

  Multiplicative factor that converts values expressed in the time coordinate's units to seconds. Returns 1.0 when units are missing or unknown.

Raises:

• ValueError –

  If data does not have a time coordinate.

Warns:

• UserWarning –

  If the time coordinate has missing or unknown units. In that case, seconds are assumed.

Resample data to new time coordinates.

Parameters:

• data ¶

  (DataArray) –

  DataArray with a time coordinate.

• new_time ¶

  (array_like) –

  New time coordinates to resample to.

• method ¶

  ((linear, nearest, nearest - up, zero, slinear, quadratic, cubic, previous, next), default: "linear" ) –

  Interpolation method passed to scipy.interpolate.interp1d:

  • "linear": linear interpolation.
  • "nearest": nearest-neighbour interpolation; rounds down at half-integers.
  • "nearest-up": nearest-neighbour interpolation; rounds up at half-integers.
  • "zero": zeroth-order spline (step function).
  • "slinear": first-order spline.
  • "quadratic": second-order spline.
  • "cubic": third-order spline.
  • "previous": use previous point's value.
  • "next": use next point's value.

• fill_value ¶

  (float or tuple[float, float] or {extrapolate, nan}, default: "extrapolate" ) –

  How to handle target times that fall outside the range of the input time coordinates. "extrapolate" allows linear extrapolation. Use a float for a constant fill value, or a tuple (left, right) for different values on each side.

Returns:

• DataArray –

  DataArray resampled to new_time coordinates.

Raises:

• ValueError –

  If data does not have a time dimension or has only 1 timepoint.

Resample data to a uniform time grid.

Parameters:

• data ¶

  (DataArray) –

  DataArray with a time coordinate.

• start ¶

  (float or None, default: None ) –

  Start of the new time grid. If not provided, use the first time point.

• stop ¶

  (float or None, default: None ) –

  Stop of the new time grid. If not provided, use the last time point.

• step ¶

  (float or None, default: None ) –

  Time step for the uniform grid. If not provided, derive it from the input coordinate by estimating a representative interval from consecutive time differences. For non-uniform input, the median interval is used and a warning is emitted. The generated grid always starts at start and includes stop only when it falls on the start + n * step lattice.

• method ¶

  ((linear, nearest, nearest - up, zero, slinear, quadratic, cubic, previous, next), default: "linear" ) –

  Interpolation method passed to scipy.interpolate.interp1d:

  • "linear": linear interpolation.
  • "nearest": nearest-neighbour interpolation; rounds down at half-integers.
  • "nearest-up": nearest-neighbour interpolation; rounds up at half-integers.
  • "zero": zeroth-order spline (step function).
  • "slinear": first-order spline.
  • "quadratic": second-order spline.
  • "cubic": third-order spline.
  • "previous": use previous point's value.
  • "next": use next point's value.

• fill_value ¶

  (float or tuple[float, float] or {extrapolate, nan}, default: "extrapolate" ) –

  How to handle target times that fall outside the range of the input time coordinates. "extrapolate" allows linear extrapolation. Use a float for a constant fill value, or a tuple (left, right) for different values on each side.

Returns:

• DataArray –

  DataArray resampled to a uniform time grid.

Raises:

• ValueError –

  If data does not have a time dimension or has only 1 timepoint.

• ValueError –

  If start is greater than or equal to stop, if step is not positive, or if no valid representative step can be derived.

Warns:

• UserWarning –

  If the original time coordinate is not uniform and step is not provided. In that case the median step is used.