Struct Schedule 

pub struct Schedule<Dim: Dimension>(/* private fields */);

Represents a sampling schedule. Schedules are represented as a list of booleans, where true means to take the sample at the position of the index and false means to not take the sample.

Implementations

impl<Dim: Dimension> Schedule<Dim>

pub const fn new(sched: Array<bool, Dim>) -> Schedule<Dim>

Create a new schedule from a list of booleans

pub fn into_inner(self) -> Array<bool, Dim>

Unwrap the inner list of bools

pub fn count(&self) -> usize

Count the number of samples in the schedule. Note that this is operation linear in the length of the schedule.

pub fn decode( encoded: &str, encoding_type: EncodingType, dims_rule: impl FnOnce(Dim) -> Result<Dim, String>, ) -> Result<Schedule<Dim>, ScheduleDecodingError>

Decodes a schedule from a string. The format is expected to be a list of line-break separated sample positions, where each sample position is a comma separated list of numbers for each index in each dimension.

len_rule is a function that takes the minimum possible length to contain all of the values and returns either a length for the schedule or an error message that will be propagated. This is necessary because it is not known how many false values there there should be after the last true value, and it allows rejecting input that could cause resource exhaustion of the software. It would make sense to configure this function to return an error above a maximum value because it is possible to make a “schedule bomb” that would consume the entire RAM when decoded:

0
100000000000000000000

Example

let sched = Schedule::new(Array::from_vec(vec![true, false, true, true, false, true, false, false]));

assert_eq!(
    Schedule::<Ix1>::decode(
        "0\n2\n3\n5",
        EncodingType::ZeroBased,
        |max| Ok(Ix1(max[0].next_power_of_two()))
    ).unwrap(),
    sched
);

assert!(
    Schedule::<Ix1>::decode(
        "1\n3\n4\n6",
        EncodingType::OneBased,
        |max| if max[0] > 4 { Err("Too big!".to_owned()) } else { Ok(max) },
    ).is_err(),
);

let sched = Schedule::new(Array::from_shape_vec(IxDyn(&[8, 2]).strides(IxDyn(&[1, 8])), vec![
    false, false, true,  false, false, false, false, false,
    true,  false, false, true,  false, true,  false, false,
]).unwrap());

assert_eq!(
    Schedule::<IxDyn>::decode(
        "1, 2\n3, 1\n4, 2\n6, 2",
        EncodingType::OneBased,
        |max| Ok(IxDyn(&max.as_array_view().iter().map(|v| v.next_power_of_two()).collect::<Vec<_>>())),
    ).unwrap(),
    sched,
);

let sched = Schedule::new(Array::from_vec(vec![true, false, true, true, false, true, false]));
assert_eq!(
    Schedule::<Ix1>::decode(
        "0\n2\n3\n5",
        EncodingType::ZeroBased,
        |_| Ok(Ix1(7)),
    ).unwrap(),
    sched,
);

pub fn encode(&self, encoding_type: EncodingType) -> String

Writes the schedule to a string using the same format as is understood by Schedule::decode.

Example

let sched = Schedule::new(Array::from_vec(vec![true, false, false, true, true]));
assert_eq!(sched.encode(EncodingType::ZeroBased), "0\n3\n4");
assert_eq!(sched.encode(EncodingType::OneBased), "1\n4\n5");

assert_eq!(
    Schedule::decode(
        "1, 2\n3, 4",
        EncodingType::OneBased,
        |v: Ix2| Ok(v),
    )
    .unwrap()
    .encode(EncodingType::OneBased),
    "1, 2\n3, 4",
);

impl Schedule<Ix1>

pub fn point_spread(&self) -> PointSpread

Calculates the Point Spread Function of the schedule.

The PSF is calculated as the discrete fourier transform of the schedule where true is replaced with 1. and false is replaced with 0..

If you take uniformly sampled data and set every sample not taken to zero, the Convolution Theorem states that your true signal will be convolved with the schedule’s PSF. Therefore, it is preferable to generate schedules where the PSF has minimal spikes because that minimizes sampling noise.

The PSF can also be thought of as a plot of global bias towards sampling a particular frequency. For example, a PSF spike at wavenumber 1/3 indicates a bias towards sampling at positions that are at multiples of three, or some offset of a multiple of three, thereby undersampling frequencies that are out of phase with this bias. Therefore, the PSF can be thought of as a plot of how much a schedule undersamples different phases of a particular frequency.

pub fn rlc(&self, seq: impl AsRef<[bool]>) -> Vec<u64>

Calculate the Repeat Length Curve of the schedule for a given pattern.

This metric can be used to determine the number of repeating patterns in the sampling schedule. Schedules with fewer patterns are more condusive to signal reconstruction because patterns represent a local bias against sampling particular frequencies.

The first argument is the pattern to be searched for. The function returns a list where the element at index i is number of places in the schedule where seq is repeated i + 1 times followed by the first element of seq.

Example

let sched = Schedule::new(Array::from_vec(vec![true, false, true, false, true, false, false, true, false, true]));

// The schedule has 3 instances of `T F T` and 1 instance of `T F T F T`
assert_eq!(sched.rlc([true, false]), vec![3, 1]);

L. E. Cullen, A. Marchiori, D. Rovnyak, Magn Reson Chem 2023, 61(6), 337. https://doi.org/10.1002/mrc.5340

Trait Implementations

impl<Dim: Clone + Dimension> Clone for Schedule<Dim>

fn clone(&self) -> Schedule<Dim>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<Dim: Dimension> Debug for Schedule<Dim>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<Dim: Dimension> Deref for Schedule<Dim>

type Target = ArrayBase<OwnedRepr<bool>, Dim>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<Dim: Dimension> DerefMut for Schedule<Dim>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<Dim: Dimension> Display for Schedule<Dim>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<Dim: PartialEq + Dimension> PartialEq for Schedule<Dim>

fn eq(&self, other: &Schedule<Dim>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<Dim: Eq + Dimension> Eq for Schedule<Dim>

impl<Dim: Dimension> StructuralPartialEq for Schedule<Dim>