# algorithms.diagnostics.timediff

## Module: `algorithms.diagnostics.timediff`

Time series diagnostics

These started life as `tsdiffana.m` - see http://imaging.mrc-cbu.cam.ac.uk/imaging/DataDiagnostics

Oliver Josephs (FIL) gave me (MB) the idea of time-point to time-point subtraction as a diagnostic for motion and other sudden image changes.

## Functions

nipy.algorithms.diagnostics.timediff.time_slice_diffs(arr, time_axis=-1, slice_axis=None)

  Time-point to time-point differences over volumes and slices

  We think of the passed array as an image. The image has a “time” dimension given by time_axis and a “slice” dimension, given by slice_axis, and one or more other dimensions. In the case of imaging there will usually be two more dimensions (the dimensions defining the size of an image slice). A single slice in the time dimension we call a “volume”. A single entry in arr is a “voxel”. For example, if time_axis == 0, then `v = arr[0]` would be the first volume in the series. The volume `v` above has `v.size` voxels. If, in addition, slice_axis == 1, then for the volume `v` (above) `s = v[0]` would be a “slice”, with `s.size` voxels. These are obviously terms from neuroimaging.

  Parameters:
    arr array_like

      Array over which to calculate time and slice differences. We’ll call this array an ‘image’ in this doc.

    time_axis int, optional

      axis of arr that varies over time. Default is last

    slice_axis None or int, optional

      axis of arr that varies over image slice. None gives last non-time axis.

  Returns:
    results dict

      `T` is the number of time points (`arr.shape[time_axis]`)

      `S` is the number of slices (`arr.shape[slice_axis]`)

      `v` is the shape of a volume (`rollimg(arr, time_axis)[0].shape`)

      `d2[t]` is the volume of squared differences between voxels at time point `t` and time point `t+1`

      results has keys:

      - ‘volume_mean_diff2’(T-1,) array

          array containing the mean (over voxels in volume) of the squared difference from one time point to the next

      - ‘slice_mean_diff2’(T-1, S) array

          giving the mean (over voxels in slice) of the difference from one time point to the next, one value per slice, per timepoint

      - ‘volume_means’(T,) array

          mean over voxels for each volume `vol[t] for t in 0:T`

      - ‘slice_diff2_max_vol’v[:] array

          volume, of same shape as input time point volumes, where each slice is is the slice from `d2[t]` for t in 0:T-1, that has the largest variance across `t`. Thus each slice in the volume may well result from a different difference time point.

      - ‘diff2_mean_vol``v[:] array

          volume with the mean of `d2[t]` across t for t in 0:T-1.

  Raises:
    ValueError if time_axis refers to same axis as slice_axis

nipy.algorithms.diagnostics.timediff.time_slice_diffs_image(img, time_axis='t', slice_axis='slice')

  Time-point to time-point differences over volumes and slices of image

  Parameters:
    img Image

      The image on which to perform time-point differences

    time_axis str or int, optional

      Axis indexing time-points. Default is ‘t’. If time_axis is an integer, gives the index of the input (domain) axis of img. If time_axis is a str, can be an input (domain) name, or an output (range) name, that maps to an input (domain) name.

    slice_axis str or int, optional

      Axis indexing MRI slices. If slice_axis is an integer, gives the index of the input (domain) axis of img. If slice_axis is a str, can be an input (domain) name, or an output (range) name, that maps to an input (domain) name.

  Returns:
    results dict

      arr refers to the array as loaded from img

      `T` is the number of time points (`img.shape[time_axis]`)

      `S` is the number of slices (`img.shape[slice_axis]`)

      `v` is the shape of a volume (`rollimg(img, time_axis)[0].shape`)

      `d2[t]` is the volume of squared differences between voxels at time point `t` and time point `t+1`

      results has keys:

      - ‘volume_mean_diff2’(T-1,) array

          array containing the mean (over voxels in volume) of the squared difference from one time point to the next

      - ‘slice_mean_diff2’(T-1, S) array

          giving the mean (over voxels in slice) of the difference from one time point to the next, one value per slice, per timepoint

      - ‘volume_means’(T,) array

          mean over voxels for each volume `vol[t] for t in 0:T`

      - ‘slice_diff2_max_vol’v[:] image

          image volume, of same shape as input time point volumes, where each slice is is the slice from `d2[t]` for t in 0:T-1, that has the largest variance across `t`. Thus each slice in the volume may well result from a different difference time point.

      - ‘diff2_mean_vol``v[:] image

          image volume with the mean of `d2[t]` across t for t in 0:T-1.