API Reference

Core Classes

The package exposes three primary classes through neurodesign:

from neurodesign import Experiment, Design, Optimisation

Experiment

class neurodesign.Experiment(TR, P, C, rho, stim_duration, n_stimuli, stimuli_durations=None, conditional_ITI=None, ITImodel=None, ITImin=None, ITImax=None, ITImean=None, restnum=0, restdur=0, t_pre=0, t_post=0, n_trials=None, duration=None, resolution=0.1, FeMax=1, FdMax=1, FcMax=1, FfMax=1, maxrep=None, hardprob=False, confoundorder=3, order=None, order_probabilities=None, order_keys=None, order_length=None, order_fixed=False, trial_max=None)

Bases: object

This class represents an fMRI experiment.

Parameters:

• TR (float) – The repetition time.

• P (ndarray) – The probabilities of each trialtype.

• C (ndarray) – The contrast matrix. Example: np.array([[1,-1,0],[0,1,-1]])

• rho (float) – AR(1) correlation coefficient

• n_stimuli (integer) – The number of stimuli (or conditions) in the experiment.

• n_trials (integer) – The number of trials in the experiment. Either specify n_trials or duration.

• duration (float) – The total duration (seconds) of the experiment. Either specify n_trials or duration.

• resolution (float) – the maximum resolution of design matrix

• stim_duration (float) – duration (seconds) of stimulus

• t_pre (float) – duration (seconds) of trial part before stimulus presentation (eg. fixation cross)

• t_post (float) – duration (seconds) of trial part after stimulus presentation

• maxrep (integer or None) – maximum number of repetitions

• hardprob (boolean) – can the probabilities differ from the nominal value?

• confoundorder (integer) – The order to which confounding is controlled.

• restnum (integer) – Number of trials between restblocks

• restdur (float) – duration (seconds) of the rest blocks

• ITImodel (string) – Which model to sample from. Possibilities: “fixed”,”uniform”,”exponential”

• ITImin (float) – The minimum ITI (required with “uniform” or “exponential”)

• ITImean (float) – The mean ITI (required with “fixed” or “exponential”)

• ITImax (float) – The max ITI (required with “uniform” or “exponential”)

max_eff()

Compute maximum efficiency for Confounding and Frequency efficiency.

countstim()

Compute some arguments depending on other arguments.

Duration is always computed from EXPECTED values (trial_max + ITImean) so the whitening matrix is stable across all designs in a population. Individual designs may have shorter actual timing — the unused timepoints in the design matrix are simply zeros (equivalent to rest).

CreateTsComp()

Compute the number of scans and timepoints.

CreateLmComp()

Generate components for the linear model.

Components: hrf, whitening matrix, autocorrelation matrix, CX.

canonical()

Generate the canonical hrf.

Parameters:

resolution (float) – resolution to sample the canonical hrf

static drift(s, deg=3)

Compute a drift component.

static spm_Gpdf(s, h, l)

Generate gamma pdf.

static sample_stim_durations(order, stimuli_durations, t_pre, t_post)

Sample concrete stimulus durations for a specific trial order.

Called per-Design (not per-Experiment) so each design gets its own random draw, but they all share the same Experiment container.

Returns a list of durations (including t_pre + t_post per trial).

static generate_iti(order, conditional_iti)

static calculate_duration(ITI, dur)

Calculate total duration from ITI and trial durations.

static sample_from_probabilities(prob, key, length)

Design

class neurodesign.Design(order, ITI, experiment, onsets=None, all_stim_durations=None)

Bases: object

This class represents an experimental design for an fMRI experiment.

Parameters:

• order (list of integers) – The stimulus order.

• ITI (list of floats) – The ITI’s between all stimuli.

• experiment (experiment object) – The experimental setup.

• onsets (list of floats) – The onsets of all stimuli.

check_maxrep(maxrep)

Check whether design does not exceed maximum repeats within design.

Parameters:

maxrep (integer) – How many times should a stimulus maximally be repeated.

Returns repcheck:

Boolean indicating maximum repeats are respected

check_hardprob()

Check whether frequencies match the prespecified frequencies.

Returns probcheck:

Boolean indicating probabilities are respected

crossover(other, seed=1234)

Crossover design with other design and create offspring.

Parameters:

• other (design object) – The design with which the design will be mixed

• seed (integer or None) – The seed with which the change point will be sampled.

Returns offspring:

List of two offspring designs.

mutation(q, seed=1234)

Mutate q% of the stimuli with another stimulus.

Parameters:

• q (float) – The percentage of stimuli that should be mutated

• seed (integer or None) – The seed with which the mutation points are sampled.

Returns mutated:

Mutated design

designmatrix()

Expand from order of stimuli to a fMRI timeseries.

Returns self on success, or False if the design’s actual timing exceeds the experiment’s container (e.g. from extreme ITI draws).

FeCalc(Aoptimality=True)

Compute estimation efficiency.

Parameters:

Aoptimality (boolean) – Kind of optimality to optimize, A- or D-optimality

FdCalc(Aoptimality=True)

Compute detection power.

Parameters:

Aoptimality (boolean) – Kind of optimality to optimize: A- or D-optimality

FcCalc(confoundorder=3)

Compute confounding efficiency.

Parameters:

confoundorder (integer) – To what order should confounding be protected

FfCalc()

Compute efficiency of frequencies.

FCalc(weights, Aoptimality=True, confoundorder=3)

Compute weighted average of efficiencies.

Parameters:

weights (list of floats) – Weights given to each of the efficiency metrics in this order: Estimation, Detection, Frequencies, Confounders.

Optimisation

class neurodesign.Optimisation(experiment, weights, preruncycles, cycles, seed=None, I=4, G=20, R=None, q=0.01, Aoptimality=True, folder=None, outdes=3, convergence=1000, optimisation='GA')

Bases: object

Represent the population of experimental designs for fMRI.

Parameters:

• experiment (experiment) – The experimental setup of the fMRI experiment.

• G (integer) – The size of the generation

• R (list) – with which rate are the orders generated from [‘blocked’,’random’,’mseq’]

• q (float) – percentage of mutations

• weights (list) – weights attached to Fe, Fd, Ff, Fc

• I (integer) – number of immigrants

• preruncycles (integer) – number of prerun cycles (to find maximum Fe and Fd)

• cycles (integer) – number of cycles

• seed (integer) – seed

• Aoptimality (boolean) – optimises A-optimality if true, else D-optimality

• convergence (integer) – after how many stable iterations is there convergence

• folder (string) – folder to save output

• outdes (integer) – number of designs to be saved

• optimisation (string) – The type of optimisation - ‘GA’ or ‘simulation’

change_seed()

Change the seed.

check_develop(design, weights=None)

Check and develop a design to the population.

Function will check design against strict options and develop the design if valid.

Parameters:

• design (esign object) – Design to be added to population.

• weights (list of floats, summing to 1) – weights for efficiency calculation.

add_new_designs(weights=None, R=None)

Generate the population.

Parameters:

• experiment (experiment) – The experimental setup of the fMRI experiment.

• weights (list of floats, summing to 1) – weights for efficiency calculation.

• seed (integer or None) – The seed for random processes.

to_next_generation(weights=None, seed=1234, optimisation=None)

Go from one generation to the next.

Parameters:

• weights (list of floats, summing to 1) – weights for efficiency calculation.

• seed (integer or None) – The seed for random processes.

• optimisation (string) – The type of optimisation - ‘GA’ or ‘simulation’

clear()

Clear results between optimisations (maximum Fe, Fd or opt).

optimise()

Run design optimization.

evaluate()

download()

static pearsonr(signals, nstim)

Utility Modules

generate

neurodesign.generate.order(nstim, ntrials, probabilities, ordertype, seed=1234)

Generate an order of stimuli.

Parameters:

• nstim (integer) – The number of different stimuli (or conditions)

• ntrials (integer) – The total number of trials

• probabilities (list) – The probabilities of each stimulus

• ordertype (string) – Which model to sample from. Possibilities: “blocked”, “random” or “msequence”

• seed (integer or None) – The seed with which the change point will be sampled.

Returns order:

A list with the created order of stimuli

neurodesign.generate.iti(ntrials, model, min=None, mean=None, max=None, lam=None, resolution=0.1, seed=1234)

Generate an order of stimuli.

Parameters:

• ntrials (integer) – The total number of trials

• model (string) – Which model to sample from. Possibilities: “fixed”,”uniform”,”exponential”

• min (float) – The minimum ITI (required with “uniform” or “exponential”)

• mean (float) – The mean ITI (required with “fixed” or “exponential”)

• max (float) – The max ITI (required with “uniform” or “exponential”)

• lam – lambda

• resolution (float) – The resolution of the design: for rounding the ITI’s

• seed (integer or None) – The seed with which the change point will be sampled.

Returns iti:

A list with the created ITI’s

msequence

Generate m sequences.

Loosely translated from http://fmriserver.ucsd.edu/ttliu

class neurodesign.msequence.Msequence

Bases: object

Create instance for an order of experimental trials.

GenMseq(mLen, stimtypeno, seed)

Generate a random msequence given the length of the desired sequence and the number of different values.

Parameters:

• stimtypeno (int) – Number of different stimulus types

• mLen (int) – The length of the requested msequence (will be shorter than full msequence)

• seed (int) – Seed with which msequence is sampled.

Mseq(baseVal, powerVal, shift=None, whichSeq=None, userTaps=None)

Generate a specific msequence given the base and power values.

Parameters:

• baseVal (int) – The base value of the msequence (equivalent to number of stimuli)

• powerVal (int) – The power of the msequence

• shift (int | None) – Shift of the msequence

• whichSeq (int | None) – Index of the sequence desired in the taps file.

• userTaps (list) – if user wants to specify own polynomial taps

tapsfnc()

Generate taps leading to msequences.

static qadd(a, b, base)

static qmult(a, b, base)

report

neurodesign.report.make_report(population, outfile='NeuroDesign.pdf')

Create a report of a finished design optimisation.

class neurodesign.report.PdfImage(img_data, width=200, height=200)

Bases: Flowable

wrap()

This will be called by the enclosing frame before objects are asked their size, drawn or whatever. It returns the size actually used.

drawOn(canv, x, y, _sW=0)

Tell it to draw itself on the canvas. Do not override