mspt.motion package¶
Submodules¶
mspt.motion.motionBreathCough module¶
- class mspt.motion.motionBreathCough.MotionBreathCough(argsDict, typeFloat)[source]¶
Bases: mspt.motion.motionNoisyCos.MotionNoisyCos
The class MotionBreathCough, inherit from MotionNoisyCos. In addition to noise added to the motion, this class add a cough to the motion. The cough is modeled as a single event happening at a random date. The amplitude of a cough is the initial amplitude (wihtout cough) minus a random value defined by a normal distribution (mean = ‘magnitude’/2 and stdev = ‘variationsMag’/2). The reason why we are using a “minus” instead of a “plus” is that usually when someone coughs his rib cage is compressed.
Parameters: - argsDict –
Dictionary configuring the motion. Keys that must be in this dictionary are:
- ‘breathingPeriod’: numpy array of 3 elements: [ x_period, y_period, z_period]
- ‘magnitude’: numpy array of 3 elements: [ x_magnitude, y_magnitude, z_magnitude]
- ‘initialPhase’: numpy array of 3 elements: [ x_phase, y_phase, z_phase]
- ‘variationsMag’: numpy array of 3 elements representing the standard deviation of the normal distribution applied to the motion amplitude of each coordinate. We consider that the mean of the distribution is the value defined in ‘magnitude’. This represents the noise applied to the motion magnitudes.
- ‘variationsPeriod’: numpy array of 3 elements representing the standard deviation of the normal distribution applied to the length of the period for each coordinate. We consider that the mean of the distribution is the value defined in ‘breathingPeriod’. This represents the noise applied to the length of the periods.
- typeFloat – type of numpy float to use: ‘float32’ or ‘float64’.
- getDisplacementVectorAtTime(timer)[source]¶
Computes the displacement vector. It uses the getDisplacementVectorAtTime() function of MotionNoisyCos.
We add a “Cough” when the random date has just occured. The random amplitude is then subtracted from the initial motion amplitude. The amplitude of the cough is random using a Gaussian pdf whose mean amplitude is half the amplitude used for the noise and the stdev is half the stdev used for noise in the motion for each coordinate.
Parameters: timer – Time in sec. Returns: Displacement vector : numpy array with 3 elements.
- argsDict –
- mspt.motion.motionBreathCough.updateVecDispl(CoughFunc, vec)[source]¶
Update a displacement vector, by subtraction the cough amplitude to each coordinate. We consider the cough as reducing the amplitude.
Parameters: - CoughFunc – list of normal distribution functions
- vec – Initial displacement vector
Returns: Displacement vector : numpy array with 3 elements.
mspt.motion.motionBreathHiccup module¶
- class mspt.motion.motionBreathHiccup.MotionBreathHiccup(argsDict, typeFloat)[source]¶
Bases: mspt.motion.motionNoisyCos.MotionNoisyCos
The class MotionBreathHiccup, inherit from MotionNoisyCos. In addition to noise added to the motion, this class adds some hiccups to the motion.
The hiccup is modeled as a periodical event starting at a random date, having a random period, a random number of period (for ease we set this number between 1 and 10: the value can be changed in motion.motionBreathHiccup with the global variable nbMaxHiccup) which determines the ending date of the hiccup. The amplitude of a hiccup is the sum of the initial amplitude (wihtout hiccup) plus a random value defined by a normal distribution (mean = ‘magnitude’/2 and stdev = ‘variationsMag’/2).
Parameters: - argsDict –
Dictionary configuring the motion. Keys that must be in this dictionary are:
- ‘breathingPeriod’: numpy array of 3 elements: [ x_period, y_period, z_period]
- ‘magnitude’: numpy array of 3 elements: [ x_magnitude, y_magnitude, z_magnitude]
- ‘initialPhase’: numpy array of 3 elements: [ x_phase, y_phase, z_phase]
- ‘variationsMag’: numpy array of 3 elements representing the standard deviation of the normal distribution applied to the motion amplitude of each coordinate. We consider that the mean of the distribution is the value defined in ‘magnitude’. This represents the noise applied to the motion magnitudes.
- ‘variationsPeriod’: numpy array of 3 elements representing the standard deviation of the normal distribution applied to the length of the period for each coordinate. We consider that the mean of the distribution is the value defined in ‘breathingPeriod’. This represents the noise applied to the length of the periods.
- typeFloat – type of numpy float to use: ‘float32’ or ‘float64’.
- getDisplacementVectorAtTime(timer)[source]¶
Computes the displacement vector. It uses the getDisplacementVectorAtTime() function of MotionNoisyCos. We add a “Hiccup” when using a random starting date, a random hiccup period duration and a random number of periods. The amplitude of the hiccup is random using a Gaussian pdf whose mean amplitude is half the amplitude used for the noise and the stdev is half the stdev used for noise in the motion for each coordinate.
Parameters: timer – Time in sec. Returns: Displacement vector : numpy array with 3 elements.
- argsDict –
- mspt.motion.motionBreathHiccup.updateVecDispl(HiccupFunc, vec)[source]¶
Update a displacement vector, by adding the hiccup amplitude to each coordinate.
Parameters: - HiccupFunc – list of normal distribution functions
- vec – Initial displacement vector
Returns: Displacement vector : numpy array with 3 elements.
mspt.motion.motionCos module¶
- class mspt.motion.motionCos.MotionCos(argsDict, typeFloat)[source]¶
Bases: object
Class modeling breathing motions as a cosine function. The model is based on models used by:
- Lujan et al. 1999: “A method for incorporating organ motion due to breathing into 3D dose calculations”
- George et al. 2005: “The application of the sinusoidal model to lung cancer patient respiratory motion”
- Seco et al. 2009: “Breathing interplay effects during proton beam scanning: simulation and statistical analysis.”
The model of the breathing motion based on a cosine function was introduced by Lujan et al. and slightly modified later by George et al. We use this last version that can be expressed as:
f(t) = z0 + b cos( (2*Pi*t / tau) - phi) where z0 is the average position (it is set to 0),t the time, b the amplitude, and tau the motion period. Lujan and Seco also added a phase phi that can be added in the cosine.Parameters: argsDict – Dictionary configuring the motion. Keys that must be in this dictionary are:
- ‘breathingPeriod’: numpy array of 3 elements: [ x_period, y_period, z_period]
- ‘magnitude’: numpy array of 3 elements: [ x_magnitude, y_magnitude, z_magnitude]
- ‘initialPhase’: numpy array of 3 elements: [ x_phase, y_phase, z_phase]
If no motion is one direction, set the 3 parameters for this direction (x,y or z) to 0.
Parameters: typeFloat – type of numpy float to use: ‘float32’ or ‘float64’.
mspt.motion.motionManager module¶
- class mspt.motion.motionManager.Motion(argsDict, typeFloat)[source]¶
Bases: object
Class Motion: used to define motions. They can be of different types:
- ‘motionCos’: Motion defined as a cosine wave along X,Y,Z axis.
- ‘motionNoisyCos’: Similar to ‘motionCos’ with random noise.
- ‘motionBreathHiccup’: ‘NoisyCos’ plus hiccup. Hiccup is defined by a starting and ending date and a periodical motion of random amplitude is added to the initial noisy cosine.
- ‘motionBreathCough’: ‘NoisyCos’ plus cough. Cough is defined by a single random motion occuring at a random time.
Note
The user could create new motions. To do so, in motionManager.py add the name of the created class (the first letter must be in lower case) in the global variable ‘motionTypes’. The new class must implement ‘getDisplacementVectorAtTime(timer)’ to define the displacement vector at time = timer. On could decide to return a 3D matrix containing local displacement vectors (In such case patient.patient.py and scanning.deliverySimulation_Static_Dynamic.py should be adapted for deformable transformations. The ‘history’ attribute of MotionManager should also be adapted). It must also implement ‘__str__’ to provide information about the motion.
Parameters: - argsDict – dictionary of arguments used to initialize the types of motion. The key ‘typeMotion’ must be present. It it equal to one of theses types: ‘motionNoisyCos’,’motionCos’,’motionBreathHiccup’,’motionBreathCough’
- typeFloat –
type of numpy float to use: ‘float32’ or ‘float64’.
The units for the stdandard deviations and the averages must be in cm and the time in sec.
mspt.motion.motionMonitor module¶
- class mspt.motion.motionMonitor.MotionMonitor(motion, measureStdErr, measureAvgErr)[source]¶
Bases: object
The class MotionMonitor aims to simulate a motion monitoring system. A motion (motionManager) is assigned to this monitor. This motion provides the true measurement to the monitor. Some noise is added to this measurement in order to make it more realistic. The noise is modeled by a normal distribution.
Parameters: - motion – The motion being used. It should be a motion manager so that it can be used for any type of motion.
- measureStdErr – Numpy array with 3 values corresponding to the standard deviation of the normal distribution for each coordinate.
- measureAvgErr – Numpy array with 3 values corresponding to the mean of the normal distribution for each coordinate.
- getHistory()[source]¶
Returns: Dictionary: keys: - ‘time’ : list of time values.
- ‘x’ (dictionary): keys:
- ‘PatientMotion’: list of true patient position along the X axis
- ‘MeasuredMotion’: list of patient position measurement along the X axis
- ‘y’ (dictionary): keys:
- ‘PatientMotion’: list of true patient position along the Y axis
- ‘MeasuredMotion’: list of patient position measurement along the Y axis
- ‘z’ (dictionary): keys:
- ‘PatientMotion’: list of true patient position along the Z axis
- ‘MeasuredMotion’: list of patient position measurement along the Z axis
mspt.motion.motionNoisyCos module¶
- class mspt.motion.motionNoisyCos.MotionNoisyCos(argsDict, typeFloat)[source]¶
Bases: object
Class modeling breathing motions as a cosine function. The model is based on models used by:
- Lujan et al. 1999: “A method for incorporating organ motion due to breathing into 3D dose calculations”
- George et al. 2005: “The application of the sinusoidal model to lung cancer patient respiratory motion”
- Seco et al. 2009: “Breathing interplay effects during proton beam scanning: simulation and statistical analysis.”
The model of the breathing motion based on a cosine function was introduced by Lujan et al. and slightly modified later by George et al. We use this last version that can be expressed as:
f(t) = z0 + b cos( (2*Pi*t / tau) - phi)where z0 is the average position (it is set to 0),t the time, b the amplitude, and tau the motion period.
Lujan and Seco also added a phase phi that can be added in the cosine. We add a Gaussian noise on each coordinate to introduce uncertainties.
We represent the noisy cosine function as: f(t) = z0 + b(t) cos( (2*Pi*t / tau(Cylcle)) + phi) where b(t) is a value of a normal distribution whose mean is ‘magnitude’ and whose standard deviation is ‘distributionMag’. tau(Cylcle) is the period which depends on the number of cylce, i.e. every new cycle (Cycle = round(timer/(2*Pi)) ) the period tau is changed following the normal distribution. The mean is ‘breathingPeriod’ and the standard deviation is ‘distributionPeriod’.
Parameters: - argsDict –
Dictionary configuring the motion. Keys that must be in this dictionary are:
- ‘breathingPeriod’: numpy array of 3 elements: [ x_period, y_period, z_period]
- ‘magnitude’: numpy array of 3 elements: [ x_magnitude, y_magnitude, z_magnitude]
- ‘initialPhase’: numpy array of 3 elements: [ x_phase, y_phase, z_phase]
- ‘variationsMag’: numpy array of 3 elements representing the standard deviation of the normal distribution applied to the motion amplitude of each coordinate. We consider that the mean of the distribution is the value defined in ‘magnitude’. This represents the noise applied to the motion magnitudes.
- ‘variationsPeriod’: numpy array of 3 elements representing the standard deviation of the normal distribution applied to the length of the period for each coordinate. We consider that the mean of the distribution is the value defined in ‘breathingPeriod’. This represents the noise applied to the length of the periods.
- typeFloat – type of numpy float to use: ‘float32’ or ‘float64’.