Neurodesign documentation¶

Neurodesign: design optimisation¶

class `src.neurodesign.``design`(order, ITI, experiment, onsets=None)[source]

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.
`FCalc`(weights, Aoptimality=True, confoundorder=3)[source]

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.
`FcCalc`(confoundorder=3)[source]

Compute confounding efficiency.

Parameters: confoundorder (integer) – To what order should confounding be protected
`FdCalc`(Aoptimality=True)[source]

Compute detection power.

Parameters: Aoptimality (boolean) – Kind of optimality to optimize: A- or D-optimality
`FeCalc`(Aoptimality=True)[source]

Compute estimation efficiency.

Parameters: Aoptimality (boolean) – Kind of optimality to optimize, A- or D-optimality
`FfCalc`()[source]

Compute efficiency of frequencies.

`check_hardprob`()[source]

Function to check whether frequencies of stimuli are exactly the prespecified frequencies.

Returns probcheck:
Boolean indicating probabilities are respected
`check_maxrep`(maxrep)[source]

Function to check whether design does not exceed maximum repeats within design.

Parameters: Returns repcheck: maxrep (integer) – How many times should a stimulus maximally be repeated. Boolean indicating maximum repeats are respected
`crossover`(other, seed=1234)[source]

Function to crossover design with other design and create offspring.

Parameters: Returns offspring: 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. List of two offspring designs.
`designmatrix`()[source]

Expand from order of stimuli to a fMRI timeseries.

`mutation`(q, seed=1234)[source]

Function to mutate q% of the stimuli with another stimulus.

Parameters: Returns mutated: q (float) – The percentage of stimuli that should be mutated seed (integer or None) – The seed with which the mutation points are sampled. Mutated design
class `src.neurodesign.``experiment`(TR, P, C, rho, stim_duration, n_stimuli, 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)[source]

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”)
`CreateLmComp`()[source]

This function generates components for the linear model: hrf, whitening matrix, autocorrelation matrix and CX

`CreateTsComp`()[source]

This function computes the number of scans and timpoints (in seconds and resolution units)

`canonical`()[source]

This function generates the canonical hrf

Parameters: resolution (float) – resolution to sample the canonical hrf
`countstim`()[source]

Function to compute some arguments depending on other arguments.

static `drift`(s, deg=3)[source]

Function to compute a drift component

`max_eff`()[source]

Function to compute maximum efficiency for Confounding and Frequency efficiency.

static `spm_Gpdf`(s, h, l)[source]

Function to generate gamma pdf

class `src.neurodesign.``optimisation`(experiment, weights, preruncycles, cycles, seed=None, I=4, G=20, R=[0.4, 0.4, 0.2], q=0.01, Aoptimality=True, folder=None, outdes=3, convergence=1000, optimisation='GA')[source]

This class represents 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 ‘random’
`add_new_designs`(weights=None, R=None)[source]

This function generates 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 ramdom processes.
`change_seed`()[source]

Function to change the seed.

`check_develop`(design, weights=None)[source]

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

Parameters: design (design object) – Design to be added to population. weights (list of floats, summing to 1) – weights for efficiency calculation.
`clear`()[source]

Function to clear results between optimalisations (maximum Fe, Fd or opt)

`optimise`(optimisation='GA')[source]

Function to run design optimization

`to_next_generation`(weights=None, seed=1234, optimisation=None)[source]

This function goes 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’

Generate: generating stimulus order and ITI’s¶

`src.generate.``iti`(ntrials, model, min=None, mean=None, max=None, lam=None, resolution=0.1, seed=1234)[source]

Function will 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”) 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. A list with the created ITI’s
`src.generate.``order`(nstim, ntrials, probabilities, ordertype, seed=1234)[source]

Function will 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. A list with the created order of stimuli

Msequence: generating msequences¶

class `src.msequence.``Msequence`[source]

A class for an order of experimental trials.

`GenMseq`(mLen, stimtypeno, seed)[source]

Function to generate a random msequence given the length of the desired sequence and the number of different values.

Parameters: stimtypeno (integer) – Number of different stimulus types mLen – The length of the requested msequence (will be shorter than full msequence) seed (integer) – Seed with which msequence is sampled.
`Mseq`(baseVal, powerVal, shift=None, whichSeq=None, userTaps=None)[source]

Function to generate a specific msequence given the base and power values.

Parameters: powerVal (integer) – The power of the msequence baseVal (integer) – The base value of the msequence (equivalent to number of stimuli) shift (integer) – Shift of the msequence whichSeq (integer) – Index of the sequence desired in the taps file. userTaps (list) – if user wants to specify own polynomial taps
`tapsfnc`()[source]

Function to generate taps leading to msequences.

Report: summarise results from optimisation¶

`src.report.``make_report`(POP, outfile='NeuroDesign.pdf')[source]

Function to create a report of a finished design optimisation.