Vespa – Simulation User Manual and Reference - VeSPA
Contents
1. sigmal pg Sxpuls sys sigma0 H IH offhz pd90 ang90 sigma0 pg Sypuls sys sigmal H IH offhz pd180 ang180 sigmal pg Sxpuls sys sigma0 H IH offhz pd90 ang90 Udelay pg prop H tauR sigma0 pg evolve sigmal Udelay sigmal pg Sxpuls sys sigma0 H IH offhz pd90 ang90 sigma0 pg Sypuls sys sigmal H IH offhz pd180 ang180 sigmal pg Sxpuls sys sigma0 H IH offhz pd90 ang90 Udelay pg prop H tauR 2 0 sigma0 pg evolve sigmal Udelay sigmal sigma0 if k 4 3 Udelay pg prop H tauR 2 0 sigma0 pg evolve sigmal Udelay sigmal pg Sxpuls sys sigma0 H IH offhz pd90 ang90 sigma0 pg Sypuls sys sigmal H IH offhz pd180 ang180 sigmal pg Sxpuls sys sigma0 H IH offhz pd90 ang90 Udelay pg prop H tauR sigma0 pg evolve sigmal Udelay sigmal pg Sxpuls sys sigma0 H IH offhz pd90 ang90 sigma0 pg Sypuls sys sigmal H IH offhz pd180 ang180 sigmal pg Sxpuls sys sigma0 H IH offhz pd90 ang90 Udelay pg prop H tauR sigma0 pg evolve sigmal Udelay sigmal pg Sxpuls sys sigma0 H IH offhz pd90 ang90 sigma0 pg Sypuls sys sigmal H IH offhz pd180 ang180 sigmal pg Sxpuls sys sigma0 H IH offhz pd90 ang90 Udelay pg prop H tauR sigma0 pg evolve sigmal Udelay sigmal pg Sxpuls sys sigma0 H IH offhz pd90 ang90 sigma02. pg Sypuls sys sigmal H IH offhz pd180 ang180 sigmal pg Sxpuls sys sigma0 H IH offhz pd90 ang90 Udelay pg prop H tauR 2 0 sigma0 pg evolve sigmal Udelay sigmal sigma0 pg prop H te2 0 5 pg evolve sigmal Udelay pg Iypuls sys sigma0 IH 180 0 pg prop H te2 0 5 pg evolve sigmal Udelay table sigma0 35 The pulse sequence accesses the sys spin_system variable The first seven lines of code are good examples of how to access the control_dict dictionary for all three loop parameters and some user defined static parameters Note that the dictionary key for user defined parameters is and that they are ordered into a list in the order they are arranged in the GUI Thus the alpha 2 pulse duration is set by the line pd90 sim dict user static parameters 2 line since this variable was the third one listed in the GUI Similarly to the examples above a transition table variable called mx is set up in the last line of code Also of note in this example is the fact that typical Python control structures can be used in these sequence_code strings for loops if statements etc However extreme care should be taken to have consistent spacing and lack of tabs in the code that is pasted into the new pulse sequence dialog tab A 4 Creating a Pulse Sequence with an RF Pulse WaveForm A 4 1 A PRESS sequence that uses a real RF pulse read in from a file A typical use m
3. B3 TEEN 39 B 3 1 Sequence Le EE 39 B 3 2 Loop Variable 1 2 3 Descriptions aaa ceeded ed EE 39 B 3 3 User Defined Static Parameters vccscisenusend tertile aaa GAAN 39 B 3 4 General DESGrIPLON maan EEN EEEEENEEREEEEE EENS resene reene 39 Big STEAM deai EE 40 B41 Sequence Diagram EE 40 B 4 2 Loop Variable 1 2 3 Descriptions e ERRSCRE EEKEEEENESEEERdEEN EES EENEENEdeEEEEECKNEN nes 40 B 4 3 User Defined Static Parameters EEN 40 GR ENT EE A0 EE E EE 41 B 5 1 Ee E EE 41 B 5 2 Loop Variable 1 2 3 Descriptions EE 41 B 5 3 User Defined Static Parameters kA 41 B 5 4 General Description ua MAAGA aa 41 Overview of the Vespa Package The Vespa package enhances and extends three previously developed magnetic resonance spectroscopy MRS software tools by migrating them into an integrated open source open development platform Vespa stands for Versatile Simulation Pulses and Analysis The original tools that have been migrated into this package include GAVA Gamma software for spectral simulation MatPulse software for RF pulse design and IDL Vespa a package for spectral data processing and analysis The new Vespa project addresses current software limitations including non standard data access closed source multiple language software that complicates algorithm extension and comparison lack of integration between programs for sharing prior information and incomplete or missing documentation and educational content Introduction to Vespa Sim
4. x axis value in PPM or Hz white lines on black background or reversed select Real Imaginary or Magnitude spectral data to display select Gaussian or Lorentzian lineshapes for the basis functions plotted toggles either x or y or both axes on off toggles both axes on off writes the plot currently in the 1D or StackPlot canvas to file as either PNG SVG EPS or PDF format writes the plot currently in the Integral plot canvas to file as either PNG SVG EPS or PDF format writes the plot currently in the Contour plot canvas to file as either PNG SVG EPS or PDF format opens the operating systems standard text editor and inserts a textual rendering of the Experimental parameters and results Typically this is a summary of the general descriptive information the specific pulse sequence and metabolite parameters included and a listing of all metabolite lines for every loop instance in the Experiment 4 1 Loading an existing Experiment The Experiment Browser dialog is launched from the Experiment Open menu and is shown below A list of Experiment names is shown on the left When an Experiment listed in the browser is clicked on once its comment and metabolites are displayed on the right Experiments can be sorted by the isotopes contained within the simulated metabolites They al ra a AG A x strength given in MHz Experiments Comment Simulation for baseline GAYA When the Open button is clicked cortou Examp
5. 0 aspartate 0 0 0 0 0 0 5 2 78347 0 5175 0 0 aspartate 0 0 0 0 0 0 6 2 97959 0 04772 0 0 aspartate 0 0 0 0 0 0 7 3 05519 0 01597 0 0 aspartate 0 0 0 0 0 0 8 3 58274 0 00563 0 0 aspartate 0 0 0 0 0 0 9 3 79689 0 29328 0 0 aspartate 0 0 0 0 0 0 10 3 87249 0 25374 0 0 aspartate 0 0 0 0 0 0 11 3 92001 0 23456 0 0 aspartate 0 0 0 0 0 0 12 3 99561 0 21054 0 0 aspartate 0 0 0 0 0 0 13 4 20976 0 00225 0 0 choline truncated 0 30 0 0 0 0 0 3 185 3 0 0 0 creatine 0 0 0 0 0 0 0 3 027 3 0 0 0 creatine 0 0 0 0 0 0 1 35913 2 0 0 0 creatine 0 0 0 0 0 0 2 6 649 1 0 0 0 6 2 Plot results to image file formats Results in the 1D StackPlot Integral Plot and Contour Plot windows can all be saved to file in PNG portable network graphic PDF portable document file or EPS encapsulated postscript formats to save the results as an image The Vespa Simulation View menu lists commands that 26 only apply to the active Experiment Tab Select the View Output option and further select either the 1D StackPlot IntegralPlot or ContourPlot menu item Finally select either Plot to PNG Plot to PDF or Plot to EPS item The user will be prompted to pick an output filename to which will be appended the appropriate suffix 6 3 Plot results to vector graphics formats Results in the 1D StackPlot Integral Plot and Contour Plot windows can all be saved to file in SVG scalable vector graphics or EPS encapsulated postscript formats to save the results as a vector graph
6. displayed EB Simulation f loj x Experiment Management View Help j Welcome Info X Welcome to Vespa Simulation Currently there are no experiments loaded You can use the Experiment menu to load an existing experiment or create a new experiment Use the Experiment menu to open existing Experiments into tabs or to create a tab for designing a new spectral simulation Experiment If there is a bug in this release of Vespa Simulation and the program crashes it should display information in the shell or command window Please refer to this information if you are reporting bugs Shown below is a screen shot of a Vespa Simulation session with two Experiment tabs opened side by side for comparison The functionality of all tools will be described further in the following sections EB Simulation Example SpinEcho multi TE Experiment Management View Help Experiment2 X 1 Main Plat Controls Main Plot Controls Display Mode stack Plot Index Display Mode iDP zl eae aee i xs PPM S yH wel en fm an H i 1 Cursor Values PPM ee ee i Ma 2661 iwel 225 H f Indext 1 TE ms 5 0 F Index2 t Mms 5 0 T Sum Plots V 20 40 60 80 100 120 tneegralPlotControb Ta i Integral Plot Controls E show i d T show Contour Plat Controls Contour Plot Controb IZ Show E Grayscale Levels 8 4 g 4 T
7. displayed in the 1D window X Axis Max Min click fields Controls the PPM limits of the spectrum displayed in the 1D and 2D plots Alternatively the left mouse button can be used interactively in the 1D Display window to set these axes Click on the left mouse button and drag to set the min max settings using an interactive rubber band display method X axis cursors are displayed in gray red Cursor Max Min click fields Controls the PPM limits of the cursors displayed in the 1D and Stack Plots These also act as the PPM integral regions calculated in the Integral and Contour plots The cursors are displayed in purple and may not be displayed on the screen if set to values outside the X Axis min max values Alternatively the right mouse button can be used in an interactive rubber band display method in the 1D Display window to set these axes Click on the left mouse button and drag to set the left right values Cursors are displayed in gray yellow Index 1 2 3 click fields These fields allow the user to step thru the Loop1 Loop2 and Loop3 dimensions for the various plot modes As each Index widget is incremented the sequence timing s actual value is shown in the adjoining field If a given Experiment did not use a Loop dimension that index is not displayed e g you will often not see Index 3 15 Metabolites to Plot Sum Plots Integral Plot Show Contour Plot Show Grayscale Levels Contour Dimensions Line
8. gt lt Expe riment using a pulse Name example CP PRESS version Parameters sequence with additional UUID 43cbc7e9 2239 4a74 b262 d4e667adb8c2 kaaa ae Ha TEA parameters Investigators ian Ther S SSS E CT a Created 30 October 2010 High 10 0 Deg ban When a sequence with comments additional eee is ve 1 c selected from the Pulse z pisu 2and3 i E z Rgroups int TE2 ms Sequences drop list We Start value Simulate tab will be modified to In Experiment Available Step Count i display input fields where the Step se ES user can set the values for ae toc a NO these additional parameters a Paa a These additional parameters gt aerem are displayed in a list below the TauR sec been double loop fields Each line contains Aa Run Experiment Visualize Simulate Hz 4 74343810077 value 1 50017237663 choline truncated only one parameter description and a field to set a value When appropriate a default value is provided Note Data types are limited to String Long or Float data types for data entry The user is restricted to entering this type of data in any given field 4 4 Visualizing Experiment Results Experiments displayed in the Visualize widget can be considered to contain 2 3 4 or 5 dimensions that correspond to the Spectral dimension the number of metabolites in the experiment and the number of steps in Loops 1 2 and 3 respectively Pul
9. int number of spins in the metabolite for convenience As alluded to above inside the execution function there are a number of code bits that are automatically provided One is the import pygamma as pg statement Another takes the field isotopes chemical shifts and j coupling values from the control dictionary and creates a PyGamma spin_system variable called sys However this sys variable could be over written by user code as needed it is only provided as a convenience 30 The One Pulse Example Here is the PyGamma code that is in the sequence code string for the One Pulse sequence H pg Hcs sys pg HJ sys D pg Fm sys 1H ac pg acquirelD pg gen_op D H 0 000001 ACQ ac sigma pg sigma_eq sys sigma0 pg Iypuls sys sigma IH 90 0 mx ACQ table sigma0 The first thing to note is that other than the sys spin_system variable this pulse sequence does not make use of any of the variables in the control_dict dictionary There are no loops in this simulation and no user defined static parameters For examples of how to use these variables see the following examples In this example the first line defines the Hamiltonian in this case consisting simply of chemical shift and J coupling terms The second through fourth lines define the detection and acquisition operators The fifth line defines an equilibrium density matrix The sixth line applies an ideal 90 degree pulse to the den
10. is controlled by the settings of loop variable 1 41
11. sigmal pg Sxpuls sys sigma0 H IH offhz pd90 ang90 sigma0 pg Sypuls sys sigmal H IH offhz pdi80 ang180 sigmal pg Sxpuls sys sigma0 H IH offhz pd90 ang90 Udelay pg prop H tauR sigma0 pg evolve sigmal Udelay sigmal pg Sxpuls sys sigma0 H IH offhz pd90 ang90 sigma0 pg Sypuls sys sigmal H IH offhz pd180 ang180 sigmal pg Sxpuls sys sigma0 H IH offhz pd90 ang90 Udelay pg prop H tauR sigma0 pg evolve sigmal Udelay sigmal pg Sxpuls sys sigma0 H IH offhz pd90 ang90 sigma0 pg Sypuls sys sigmal H IH offhz pd180 ang180 sigmal pg Sxpuls sys sigma0 H IH offhz pd90 ang90 Udelay pg prop H tauR 2 0 sigma0 pg evolve sigmal Udelay sigmal sigma0 if k 3 4 2 Udelay pg prop H tauR 2 0 sigma0 pg evolve sigmal Udelay sigmal pg Sxpuls sys sigma0 H IH offhz pd90 ang90 sigma0 pg Sypuls sys sigmal H IH offhz pdi80 ang180 sigmal pg Sxpuls sys sigma0 H IH offhz pd90 ang90 Udelay pg prop H tauR sigma0 pg evolve sigmal Udelay 34 Udelay sigma0 sigmal Udelay sigma0 mx ACQ sigmal pg Sxpuls sys sigma0 H IH offhz pd90 ang90 sigma0 pg Sypuls sys sigmal H IH offhz pd180 ang180 sigmal pg Sxpuls sys sigma0 H IH offhz pd90 ang90 Udelay pg prop H tauR sigma0 pg evolve sigmal Udelay
12. tab gt Simulate sub tab Creator The name of the person creating the pulse sequence Loop Labels When the pulse sequence is called it can make use of up to three looping variables to create a variety of conditions for investigating metabolite behavior In the Loop Loop2 and Loop3 rows the user gives information that allows Simulation to parse these loop variables The Label field is a string used in creating the Experiment tab Simulate sub tab that describe these loops An example would be TE ms for a spin echo experiment N B If you indicate that a user should provide a timing in ms don t forget to divide by 1000 in your program to get a timing value in sec that PyGamma requires The examples demonstrate how to define and use these parameters in PyGamma code Your Static Parameter Definitions Each pulse sequence GUI has a section where users can set values for additional static parameters that are passed into the simulation The GUI for these parameters needs to be described in the Pulse Sequence Editor so that the main program can display them properly By hitting the Add button a row of widgets will appear that contain three fields used to describe the GUI for one static parameter A data type selected from a drop list a Name string and a Default Value string The Name string will be used by the Experiment Tab gt Simulate sub tab as a label to describe this field when the pulse sequence is selected for an Experim
13. 26 6 3 Plot results to vector graphics formats cceceecececcee tree ee eeeeeeeeeeeeeeeeeenenseeees 27 Appendix A Pulse Sequence Design cccceceeeeeeeteneeeeeteees 28 A 1 What is under the hood ama Nana Nanana i itu NA NAA it ih Sun 28 Vespa Simulation Basic CoOnCepts ccccseccceeeeeecceeeeeeeceeeeeeseeeeeesnsaaeeeessenaneeseeneaaees 28 Eeer Eege ee 28 A 2 Creating a Pulse Sequence without Extra Parameters 7772masasusann 30 A 2 1 How to create a One Pulse pulse seouence EE 30 A 2 2 The Ideal PRESS pulse sequence typical use of standard parameters 32 A 3 Creating a Pulse Sequence with Extra Parameters ssssssssssesssseeeeees 33 A 3 1 The PRESS CP with Variable R groups Pulse Sequence nnesssseeeeesseeeenne 33 AA Creating a Pulse Sequence with an RF Pulse WaveForm 10 mnaaannaaaaaa 36 A 4 1 A PRESS sequence that uses a real RF pulse read in from aile 36 Appendix B Pulse Sequence Diagrams s s esennnreeeeeeeneenre nnn 37 GK One EE 37 B 1 1 SEQUENCES Diagram aa R E a seared 37 B 1 2 Loop Variable 1 2 3 Descriptions enee ee ee ANNA NAA 37 B 1 3 User Defined Static Parameters 2 X a 37 GREEN e EE 37 Be DIME CMO NEE 38 Re ER Le E EE 38 B 2 2 Loop Variable 1 2 3 Descriptions aaa Aa AG EE ad 38 B 2 3 User Defined Static Parameters nk 38 B 2 4 General Description Seege naaa enge Seege e Eed deg 38
14. Show E Grayscale Levels 4 H E Dimensions Contour Index 142 Dimensions Contour Index 1 2 zl F Basis Function Parameters 5 Basis Function Parameters Line Width fl 3 0 Ek 2048 Line Width Hz 3 0 4 points 2048 4 3 Sweep Width Hz 2000 0 i Sweep Width Hz 2000 0 i ASCII Display ZS 30 25 20 15g i ASCII Display Visualize Simulate Visualize Simulate PPM 4 11013015426 i Value 15000243187 choline truncated 2 The Simulation Main Window This is a view of the main Vespa Simulation user interface window It is the first window that appears when you run the program It contains the Experiment Notebook a menu bar and status bar The Experiment Notebook can be eseme populated with one or more Experiment Tabs Experiment management View Help each of which contains input data and results 4 welomemfo x from one Experiment As described above an Welcome to Vespa Simulation Experiment is a group of spectral simulations Each simulation contains the result for one metabolite that has been run through a simulated pulse sequence for a given set of sequence parameters Thus an Experiment may consist of one metabolite for multiple sets of pulse sequence parameters or multiple metabolites for one set of pulse sequence parameters or multiple metabolites for multiple collections of pulse sequence parameters Cur
15. Vespa Simulation User Manual and Reference Version 0 1 0 Release date November 157 2010 Developed by Brian J Soher Ph D Philip Semanchuk Duke University Medical Center Department of Radiology Durham NC Karl Young Ph D David Todd Ph D University of California San Francisco Department of Radiology San Francisco CA Developed with support from NIH grant EB008387 01A1 Table of Contents Overview of the Vespa Package ssssssesssesesrsreerrerererererererrene 4 Introduction to Vespa Simulation cscssssseseecssseteeeeeesentenees 5 Using Simulation A User Manual 7 1 Overview How to launch Vespa Gimulatton aaa anannnanaan 7 2 The Simulation Main Window a 9 3 The Experiment Notebook apapap kaabang 10 4 Fe Experiment Taba NANANA ABA ANNA NAA 10 4 1 Loading an existing Experiment 1 1 1111111 terres eeeeeeeeeeeeeee senna 11 4 2 Running a new Experiment u EEN 12 4 3 New Experiments with additional user defined poarameiers AA 13 4 4 Visualizing Experiment Results 11111111 eee eeeeseeseneeeeeeeeeeeneee 14 5 Management Dialogs ama ma ANA MANANGNANANANANAKANANAUANGL 17 5 1 Manage Experiments dialog aaa kan NAA DAANAN AA 17 5 2 Manage Metabolites dialog aasa Aa GA ahy 17 5 3 Manage Pulse Sequences dialog ENEE 19 B Res lts TI 26 6 1 Results output into standard text edtor 26 6 2 Plot results to image file formats a aa ANN Lana
16. Width Sweep Width Points ASCII Display list A list of metabolites in the experiment that can be included in the display Sums all metabolite plots selected highlighted in the list For 1D display this sums different metabolite spectra together For Stack Plots the different sequence timings for one metabolite are summed check Toggles Integral Plot display check Toggles Contour Plot display check Toggles whether a grayscale image overlay is applied as a background to the contour plot click field Select the number of levels to display in the Contour Plot Note that setting too many levels may limit the ability of level values from being displayed drop list Selects index pairs among index 1 2 and 3 for display in plot click field Set the full width half max linewidth in Hz of the peaks displayed in the plots click field Set the sweep width in Hz used to reconstruct the spectra The number of spectral points used to reconstruct the spectra Displays the current Experiment results in text form The information at the top is a summary of the Experiment parameters which is followed by a line by line report of metabolite results Each line is tab delineated and shows a Metabolite Name Loop1 Loop2 Index Loop3 Index Group Number Index Line Number Index Frequency PPM Amplitude and Phase deg for each line extracted from the transition table for a given simulation 16 5 Management Dialogs The Manag
17. ab Dimensions Contour index 1 2 A New Experiment is typically created set _tewerts _30__ jponts 205 up and run Results from running an eS ar n n Experiment are only saved to the database See when specifically requested by the user The Visualize tab is updated to display results after each time the Run button is pushed on the Simulate tab i e after each run Experiments can be run multiple times until it has been saved to the database At that point it is considered frozen and it can only be run again to add additional metabolites The same parameters will be used for additional add metabolite runs PPM 0 56214900488 Hz 35 9775363125 Value 1 4999549388 choline truncated 10 The View menu on the main menu bar can be used to modify the display of the plots in the Visualize tab The resulting modifications only affect the settings in the currently activated Experiment Tab The following lists the functions on the View menu item On the Menu Bar View this menu affects the plots in the currently active Experiment tab Show ZeroLine Xaxis Show Xaxis PPM Hz Plot Color Data Type Lineshape integral Axes Show x y Show Contour Axes Output 1D Stackplot Output Integral Plot Output Contour Plot Output Text Results toggle zero line off on in 1D and stack display white lines on black background or reversed
18. alization pulses of the PRESS sequence are modeled by ideal GAMMA pulses The TE1 period is controlled by the settings of loop variable 1 the TE2 period is controlled by the settings of loop variable 2 thus either a symmetric or asymmetric PRESS experiment can be simulated 39 BA STEAM Ideal B 4 1 Sequence Diagram SCH SCH Acquisition B 4 2 Loop Variable 1 2 3 Descriptions Loop1 Describes the number of TE values to loop over in ms Loop2 Describes the number of TM values to loop over in ms Loop3 not used B 4 3 User Defined Static Parameters none B 4 4 General Description This is a simulation of a STimulated Excitation Acquisition Mode STEAM pulse sequence The typical 90 90 90 pulses of the STEAM sequence are modeled by ideal GAMMA pulses The total TE period is controlled by the settings of loop variable 1 the TM mixing time period is controlled by the settings of loop variable 2 40 B 5 JPRESS Ideal B 5 1 Sequence Diagram lt j kb a eg I lt l JE JTE1 TE Tet Acquisition T d 2 ai ee Lon l 80y Lon soy B 5 2 Loop Variable 1 2 3 Descriptions Loop Describes the number of TE1 values to loop over in ms Loop2 not used Loop3 not used B 5 3 User Defined Static Parameters none B 5 4 General Description This is a simulation of a J PRESS pulse sequence The typical 90 180 90 180 pulses of the JPRESS sequence are modeled by ideal GAMMA pulses The total TE period
19. alues Right clicking in place will turn off the Span Zoom region Edit The first highlighted sequence is opened in a form similar to the New Sequence dialog Note Only the metabolite Name and Comment are editable if the pulse sequence is public or referred to by one or more Experiments The name is editable because Experiments save Pulse Sequence references by UUID which are not editable Use the Clone option to create a copy of a Pulse Sequence that is editable If the sequence is editable the existing values of the pulse sequence object are populated into the Design and Test tabs on startup The name of the pulse sequence from the main dialog is shown in the dialog title The pulse sequence setting can be edited and tested just like a New pulse sequence would be Hitting OK saves any changes into the database Cancel quits the dialog without saving changes 25 6 Results Output 6 1 Results output into standard text editor The Vespa Simulation View menu lists commands that only apply to the active Experiment Tab Select the View Output Text Results option and a tab delineated text description of the Experiment is created and loaded into the local computer s standard text editor On Windows this is typically Notepad From here the user can save it wherever they please N B This command can also be launched from the Experiment Tab gt Visualize sub tab using the ASCII Results button The first section of the text file desc
20. alues of the location of the mouse as it moves across the canvas Text Results Button Creates a text representation of the metabolite test results and displays them in a native text editor on your computer Plot gt PNG Button Creates a PNG format image of the plot display and shows it in a native image viewer on your computer Run Test Button Runs a test Experiment on the pulse sequence The Start and End times should be reported in the Console window Any additional exceptions that are raised should be reported between these messages Console The place where text messages about each Test Run are printed Visualize Notebook Tab Note This tab is in an AUI Notebook and can be moved and positioned within the Notebook in a variety of ways Left click and drag the tab of the pane that you want to re locate to the position that you want it The test metabolite results are reconstituted as a frequency domain spectrum as described in the Results Plot Options and plotted to this display tab The Left mouse button can be used to draw a zoom box in both x and y directions Multiple zooms can be performed Left clicking once in place will zoom you all the way out to the maximum x axis extent and fit the y axis to approximately the min max data range Clicking and dragging on the Right mouse will draw a Span Cursor two vertical cursors on the screen filled in with light gray These will stay in place between test runs as you vary loop and parameter v
21. e deleted from the database if needed The exported file can be imported into another Vespa Simulation installation using the Import function Note An interesting case for which one might want to create a new metabolite would be if one discovered during for example a long TE experiment that literature values for a particular metabolite were not adequately precise in terms of modeling the result of the experiment One could obtain improved values via some combination of experimental and optimization methods then clone the existing metabolite and enter the improved values These improved values could later be submitted to the public VeSPA database perhaps after publication of the results 5 3 Manage Pulse Sequences dialog Access this dialog by clicking on the Management Manage Pulse Sequences menu item Actions that can be taken on the Pulse Sequences dialog include New Edit View Clone Delete Import and Export An example of the window used to display and edit pulse sequence information is shown The New Edit View Import and Export buttons all launch secondary New dialogs as part of their gat eegen functionality Clone and Delete yen Example SpinEcho x only affect the list in the main JPRESS_Ideal x pulse sequence management Gone oneruse e d PRESS Ideal x 3 la 0g STEAM Ideal x The Public column indicates if a E SC i sequence has ever been exported press_fullpulse_indiv x or imported from som
22. e being plotted or not Both the Integral and Contour plot windows can be undocked repositioned and re docked using the grab bars on the left hand side of each window 14 Under the 1D StackPlot window a 1D spectrum for one or more metabolites or a 2D spectral stack plot along any two Loop dimensions for a single metabolite can be selected If more than one metabolite is selected for a stack plot only the first metabolite in the list is displayed The mouse can be use to set the X axis and Cursor values in the 1D plots The left mouse button sets the X axis Min Max PPM values Click and hold the left mouse button in the window and a vertical cursor will appear Drag the mouse either left or right and a second vertical cursor will appear PPM value changes will be reflected in the Plot Control widget Release the mouse and the plot will be redisplayed for the Min Max PPM axis values This Zoom Span will display its range in a pale yellow that disappears when the left mouse is released In a similar fashion two vertical cursors can be set inside the plot window Click and drag then release to set the two cursors anywhere in the window This Cursor Span will display as a light gray span Click in place with the right mouse button and the Cursor span will be turned off The cursor values are used to determine the area under the peak values that are plotted in the Integral and Contour windows Changes to the cursor settings either by mou
23. econstruct any given Experiment that object must refer to the original sequence used to create it The Use Count column indicates if a sequence is in use by an Experiment If not in use by an Experiment the highlighted sequence s in the list can be deleted from the database Import Pops up a secondary dialog that allows the user to select an XML file that contains a Vespa Simulation pulse sequence If the UUID in the file is unique it is added to the Simulation database If it is not unique then the sequence is already in the main dialog list and the import is aborted without comment Export Select a Pulse Sequence from the list A second dialog pops up that allows the user to browse for the output filename select if output should be compressed and allows an additional export comment to be typed in Note that the action of exporting an object causes it to be marked as frozen in the database and public in the pulse sequence management dialog This means that it can not be changed This is for the sake of consistency as results are shared However a frozen pulse sequence can still be deleted from the database if needed This file can be imported into another Vespa Simulation installation using the Import function New A Pulse Sequence Editor dialog pops up that allows the user to design and test a Vespa Simulation compliant pulse sequence using PyGamma code The user must provide 20 general descriptive information about t
24. ed to display canvas E in test Experiment parameters setup in Test tab Loop Values These loops were defined in the Design tab Any loops without a label are not included in the pulse sequence The user must fill in a value for use in the test run for each loop User Static Parameters User parameters were defined in the Design tab They are initially populated with their default values but may be altered for the test run as necessary Experiment Parameters When the Run Test button is hit a mini Experiment will be run to test the user s pulse sequence In order to properly run and display results the experiment 24 needs values for Main Field MHz the isotope one metabolite to be run select from the list as sorted by isotope and the binning parameters for Peak Search Range and Blend Tolerance see Appendix A for more information on the standard blending algorithm Results Plot Options These values only affect how the metabolite result is plotted to the Display Canvas tab in the notebook Spectral Points are the number of points in the metabolite FID Sweep Width defines the FID dwell time Line Width Hz defines the broadening applied to the FID Checking the Gaussian box applies a Gaussian lineshape when it is not checked a Lorentzian lineshape is applied Checking Magnitude plots magnitude data on the canvas otherwise real data is plotted Checking x y Values will show in the lower left corner of the plot the x and y axis v
25. elay pg prop H tauR 2 0 sigma0 pg evolve sigmal Udelay sigmal pg Sxpuls sys sigma0 H IH offhz pd90 ang90 sigma0 pg Sypuls sys sigmal H IH offhz pd180 ang180 sigmal pg Sxpuls sys sigma0 H IH offhz pd90 ang90 Udelay pg prop H tauR sigma0 pg evolve sigmal Udelay 33 sigmal pg Sxpuls sys sigma0 H IH offhz pd90 ang90 sigma0 pg Sypuls sys sigmal H IH offhz pd180 ang180 sigmal pg Sxpuls sys sigma0 H IH offhz pd90 ang90 Udelay pg prop H tauR sigma0 pg evolve sigmal Udelay sigmal pg Sxpuls sys sigma0 H IH offhz pd90 ang90 sigma0 pg Sypuls sys sigmal H IH offhz pdi80 ang180 sigmal pg Sxpuls sys sigma0 H IH offhz pd90 ang90 Udelay pg prop H tauR sigma0 pg evolve sigmal Udelay sigmal pg Sxpuls sys sigma0 H IH offhz pd90 ang90 sigma0 pg Sypuls sys sigmal H IH offhz pd180 ang180 sigmal pg Sxpuls sys sigma0 H IH offhz pd90 ang90 Udelay pg prop H tauR 2 0 sigma0 pg evolve sigmal Udelay sigmal sigma0 if k 4 1 Udelay pg prop H tauR 2 0 sigma0 pg evolve sigmal Udelay sigmal pg Sxpuls sys sigma0 H IH offhz pd90 ang90 sigma0 pg Sypuls sys sigmal H IH offhz pdi80 ang180 sigmal pg Sxpuls sys sigma0 H IH offhz pd90 ang90 Udelay pg prop H tauR sigma0 pg evolve sigmal Udelay
26. ement dialogs allows the user to Create Delete Edit Import Export or View Metabolites Experiments and Pulse Sequences These dialogs therefore allow the user to manage the data in the Simulation database and to add new metabolite and pulse sequence information that can be used as prior information for simulation and processing It also provides the means for users to share information between themselves via XML files created using the Import Export functions 5 1 Manage Experiments dialog Access this dialog by clicking on the Management Manage Experiments menu item The dialog opens and blocks other activity until it is closed An example of this dialog is shown in the figure Experiment names are listed in the window on the right This list may be REISE E sorted by isotope or main BO field strength Isotope any zl B0 fany zl from the drop list widgets above the list gen Users may View Delete Import or Export e ee See Experiments These functions are paete BG DE cee ale x summarized below View Creates a brief textual description of the Experiment that is displayed in a native text editor for the platform being used Use View Output Text Results menu item on the main menu bar with the Experiment loaded into a tab in the Notebook for a more detailed textual description of the Experiment and it s Import Export cose results Delete Removes the Experiment from the database Import Allows
27. ent The data type shows up as a label in the far right hand side as a reminder The default value is inserted as the initial value that is displayed in that field The Remove Selected button can be used to remove unwanted static parameters while designing a pulse sequence Select the check box on the left side of each row of parameters you want to remove and then hit the Remove Selected button 22 As described in more detail Appendix A the values of these user specified parameters are passed to each Simulation that is run as part of an Experiment The results of setting up your pulse sequence loops and additional parameters can be viewed in the Test tab The examples demonstrate how to define and use these parameters in PyGamma code Note By selecting a data type for a user specified parameter in the drop down menu the user will be reminded to enter a variable of that type but the actual field value will be passed as a string that must be appropriately converted before being used in PyGamma simulation code Please select your default types and values accordingly Comments A field where you can enter a lot of text to remind yourself why you make this pulse sequence when you check back on it 3 months from now This is also a good place to put information for users on how to use this sequence Sequence Code Notebook Tab Note This tab is in an AUI Notebook and can be moved and positioned within the Notebook in a variety of ways Left c
28. eone else press_fullpulse_summed x Pulse Sequences with the Public column marked x can not be edited except in the Name and Comment fields The Use Count column indicates how many local 19 Experiments use this sequence While in use by any Experiments the sequence can not be deleted View Select a sequence from the main list If more than one is selected the first on in the list is viewed This button pops up a secondary dialog with three tabs that contain the sequence creation information widget descriptors and pulse sequence and binning code These tabs are not editable See figure below for example of View Comments UUID e4cc37d6 c3ee 40a9 baae 22a4260da87b Creator Brian Sohe Created 30 April 2010 Labels for Loops 1 2 and 3 Parameter Definitions Lag cr Name PulseType 0 Ideal 1 Sand Default Value Default Value Default Value Default Value Default Value Clone This option allows a user to make a copy of an existing pulse sequence This is most useful when an existing sequence is public or otherwise not editable because it is referenced by an existing Experiment Select a sequence in the list hit clone and a copy of that sequence is made that is now fully editable The new sequence has the name of the original sequence followed by the date and the word clone Delete Only sequences that are not referenced by an experiment may be deleted To r
29. eriments use this metabolite While in use by any Experiments the metabolite can not be deleted Manage Metabolites xj Isotope fal e IV Show deactivated NAAG truncated siemens acetate alanine aspartate atp adenosine atp ribose choline methylene choline methylene siemens choline methylene 2010 06 25 done not active choline trimethyl choline truncated x KM KN NM KM NM KN KM NM KM w Es x x New A dialog will pop up that gives the user a blank metabolite form to fill out Select the number of spins in the metabolite and the form will enable the appropriate chemical shift and j coupling fields Edit the fields appropriately and hit ACCEPT or Cancel See the sample in the figure below New Metabolite xj Ka GG Comments UUID Creator Aa ma Created 25 June 2010 Spins zi Pk EE ES 1 mr r a a a a a a mg 2 foo fo fo Kr AGA P E om 3 Ha a a SE a E z gt TT l E a SS SSS SS EE ESS LSS ES SE 719 en a rl nl a e E Leg aaa EE Ed xr fg Edit The highlighted metabolite is opened in a metabolite form Only the metabolite Name and Comment are editable The name is editable because Experiments save Metabolite references by UUID which are not editable Use the Clone option to create a copy of a Metabolite that is fully editable View Similar to Edit but no fields are editable 18 Clone Select a metabolite in the list hit clone and a copy of that metabolite
30. es Launches the Manage Pulse Sequences dialog Allows user to create edit view clone delete import and export Pulse Sequence information View lt various gt Changes plot options in the Visualize sub tab of the active Experiment tab including display a zero line turn x axis on off or choose units changing plot color selecting data type or line shape turning axes on off for the Integral or Contour plot windows and various output options for all plot windows Help User Manual Launches the user manual from vespa docs into a PDF file reader Help Simulation Vespa Online Help Online wiki for the Simulation application and Vespa project Help About Giving credit where credit is due 3 The Experiment Notebook The Experiment Notebook is an advanced user interface widget AUINotebook What that means to you and me is a lot of flexibility Multiple tabs can be opened up inside the window They can be moved around arranged and docked as the user desires by left click and dragging the desired tab to a new location inside the notebook boundaries In this manner the tabs can be positioned side by side top to bottom or stacked as show in Sections 1 and 4 They can also be arranged in any mixture of these positions The Experiment Notebook can be populated with one or more Experiment Tabs each of which contains the results of one Experiment Tabs can be closed using the X box on the tab or with a middle click on the tab it
31. es calculated by the GAMMA density matrix simulations frequently contain a large number of transitions caused by degenerate splittings and other processes At the conclusion of each simulation run a routine is called to extract lines from the transition table These lines are then normalized using a closed form calculation based on the number of spins To reduce the number of lines required for display multiple lines are blended by binning them together based on their PPM locations and phases The following parameters are used to customize these procedures Peak Search Range Low High PPM the range in PPM that is searched for lines from the metabolite simulation Peak Blending Tolerance PPM and Degrees the width of the bins in PPM and in PhaseDegrees that are used to blend the lines in the simulation Lines that are included in the same bin are summed using complex addition based on Amplitude and Phase 4 3 New Experiments with additional user defined parameters A full explanation of how to create additional pulse sequences with any additional parameters that may be required is given in Appendix A The Vespa Simulation Manage Pulse Sequences dialog provides an interface for a user to define the additional parameters needed for a given pulse sequence These are then saved to the Vespa Simulation database This section describes the 2215 x interface used to run an a vew Hep Experiment1 Experiment2 Experiment3
32. etabolite can t be removed from a saved experiment e An experiment s bO value is always stored in megahertz The take home lesson from this section is that the Vespa Simulation application provides 4 dynamic looping variables and 12 standard static variables to each spectral simulation that is run In the example below we will specify what these are and how they can typically be used In 29 the second example below we will specify how user defined static variables can also be passed into spectral simulations A 2 Creating a Pulse Sequence without Extra Parameters A 2 1 How to create a One Pulse pulse sequence The most important thing to remember in pulse sequence design is that no matter the size of your looping variables each distinct set of pulse sequence parameters are sent to their spectral simulation independent of all others To achieve this a list of control dictionaries is created to store each distinct set of parameters Then each dictionary is sent to a function that executes the PyGamma spectral simulation that it describes On completion of each dictionary execution lists of area ppm and phase values and start finish time stamps are returned and stored in the database The standard variables that are stored as key value pairs in the control dictionary include field float main BO field strength in MHz sequence code string PyGamma code string executed using exec to perform the simulatio
33. f N Wiedermann D Meyerhoff DJ Weiner MW Maudsley AA Short TE in vivo 1 H MR spectroscopic imaging at 1 5 T acquisition and automated spectral analysis Magn Reson Imaging 18 9 1159 65 2000 Using Simulation A User Manual This section assumes Vespa Simulation has been downloaded and installed See the Vespa Installation guide on the Vespa main project wiki for details on how to install the software and package dependencies http scion duhs duke edu vespa In the following screenshots are based on running Simulation on the Windows OS but aside from starting the program the basic commands are the same on all platforms 1 Overview How to launch Vespa Simulation On all operating systems but particularly on OS X and Linux one can open up a command window go the directory vespa simulation src and type the following command python main py The easiest way to start Simulation under Windows is to create a shortcut that executes the program e Right click on the desktop and select New gt Shortcut e Type the following Target change directory names and paths as needed C Python26 python exe C vespa simulation src main py e Click Next e Name your new shortcut Simulation or whatever click OK or Finish This shortcut will create a python shell and run Vespa Simulation Shown below is how the Vespa Simulation main window appears on first opening No actual Experiment windows are open only the Welcome banner is
34. he sequence They must describe how to lay out the pulse sequence in the Experiment tab gt Simulate sub tab both for the standard loop variables as well as any user defined parameters The user must also provide PyGamma code i e a Python script that uses calls to the PyGamma library for the main pulse sequence In addition if the default PyGamma code for binning the results is not adequate there is a place to add your own code As mentioned already the input parameters and PyGamma code for user sequence development are very specific and are described with examples in more detail in Appendix A It should be noted that the PyGamma code looks like typical Python code but with some minor differences that may be confusing at first For example specific PyGamma calls are prefaced with pg to indicate that they are defined in the PyGamma namespace This is facilitated in the underlying code with a typical python import statement but is not required in the Pulse Sequence Editor version of the code that the user sees There are a few other minor differences but examination of the examples provided should help to clarify these differences and ultimately they make the environment much easier for the user This section describes the Editor window that you can use to facilitate your design and testing The New Pulse Sequence Editor widget is shown below Please note that there are 2 main windows 1 the Design Test notebook left and 2 the Code Display notebo
35. ics file that can be decomposed into various parts This is particularly desirable when creating graphics in PowerPoint or other drawing programs At the time of writing this only the EPS files were readable into PowerPoint The Vespa Simulation View menu lists commands that only apply to the active Experiment Tab Select the View Output option and further select either the 1D StackPlot IntegralPlot or ContourPlot menu item Finally select either Plot to SVG or Plot to EPS item The user will be prompted to pick an output filename to which will be appended the appropriate suffix 27 Appendix A Pulse Sequence Design A 1 What is under the hood Vespa Simulation Basic Concepts This is a combination of logical concepts and limitations that determine how Simulation works These rules are enforced through the application and to some extent the database The main objects in the system are experiments simulations spectra pulse sequences and metabolites Experiments are the primary objects everything else is secondary Here s how they re related e Each experiment has zero to many simulations Simulations are the whole point of an experiment and there s not much to an experiment besides the metatdata that defines the simulations Since entering the experiment metadata is pretty trivial we don t let users save experiments that define zero simulations Experiments with zero simulations can exist but only in memory They are never
36. ict dictionary for the Loop and Loop2 values in the tel sim_dict dims 1 and tel sim_dict dims 2 lines There are no user defined static parameters Similarly to the example above a transition table variable called mx is set up in the last line of code Not shown The default binning code string is used to return the values from the transition table to the main Simulation program 32 A 3 Creating a Pulse Sequence with Extra Parameters A 3 1 The PRESS CP with Variable R groups Pulse Sequence Here is the PyGamma code that is in the sequence code string for the PRESS CP with Variable R groups sequence pd180 pd90 2 0 ang180 ang90 2 0 H pg Hcs sys pg HJ sys D pg Fm sys IH ac pg acquirelD pg gen_op D H 0 000001 ACQ ac sigma0 pg sigma_eq sys sigmal pg Iypuls sys sigma0 IH 90 0 Udelay pg prop H tel 0 5 sigma0 pg evolve sigmal Udelay sigmal pg Iypuls sys sigma0 IH 180 0 Udelay pg prop H tel 0 5 sigma0 pg evolve sigmal Udelay sigmal sigma0 if type using Ideal 180 pulses for k in range rgroups Udelay pg prop H tauR 2 0 sigma0 pg evolve sigmal Udelay sigmal pg Iypuls sys sigma0 180 Udelay pg prop H tauR 2 0 sigma0 pg evolve sigmal Udelay sigmal sigma0 else for k in range rgroups using 90 180 90 square Sandwich pulses with MLEV16 phase cycling if k 4 Ud
37. ight be to use one or more user defined pulses in a pulse sequence Though various ways of accessing pulses in the VeSPA database for use in pulse sequences is described elsewhere a simple method that PyGamma provides is to read the complex values for a given pulse from file The following code closely resembling the above PRESS sequence code but using real pulses for the 180 pulses illustrates how to accomplish this In particular a user_static_parameter is used to specify the name and path of the file containing the pulse values tel te2 float sim_dict dims 1 1000 0 evolution after 90 before first 180 in msec float sim_dict dims 2 1000 0 TE in msec pulsestep float sim_dict user_static_parameters 0 H pg Hcs sys pg HJ sys D pg Fm sys Udelayl pg prop H tel 0 5 Udelay2 pg prop H tel te2 0 5 Udelay3 pg prop H te2 0 5 ac pg acquirelD pg gen_op D H 0 001 ACQ ac sigma0 pg sigma_eq sys sigmal pg Iypuls sys sigma0 90 0 pg evolve sigmal Udelayl sigma0 pg evolve sigmal Udelay2 sigma0 pg evolve sigmal Udelay3 mx ACQ table sigma0 Appendix B Pulse Sequence Diagrams This section provides some basic information about the standard simulated pulse sequences that are provided as part of the Vespa distribution The full PyGamma code for each pulse sequence can be accessed through the Pulse Sequence Management Dialog widget using the View or Edit f
38. is made that is now fully editable The new metabolite has the name of the original metabolite followed by the date and the word clone Delete Only metabolites that have not been used by an experiment may be deleted This is because to reconstruct any given Experiment that object must refer to the original list of metabolites used to create it The Use Count column indicates if a metabolite is in use by an Experiment If not in use by an Experiment the highlighted metabolite in the list can be deleted from the database De activate When a metabolite is no longer being used it can be set to a deactivated state where it no longer shows up in the Experiment Tab Simulate metabolite list for use in new Experiments This state is indicated in the Metabolite dialog by the word not active appended to the metabolite name in the list Import Allows the user to select an XML file that contains a Metabolite If the UUID in the file is unique it is added to the Simulation database Export The user selects a Metabolite from the list A second dialog allows the user to browse for the output filename select if the output should be compressed and allows an additional export comment to be typed in Note that the action of exporting an object causes it to be marked as frozen in the database This means that no further changes can be made This is for the sake of consistency when results are shared However a frozen Metabolite can still b
39. itching to the Test tab Note A similar validation takes place when the user hits the OK button Only a validated pulse sequence can be saved into the database However the validation only checks to see if all necessary data is available in a reasonable format NOT if it is functional PyGamma code An example is shown below of how settings in the Design tab are represented on the Test tab Note that the test values for each loop have been entered and that the default value for the my string user parameter has been altered as well 23 New Pulse Sequence tel sim dict dims 1 1000 0 te2 sim dict dims 2 1000 0 my_str sim dict my string print my_str H pg Hes sys pg HJ sys D pg Frn sys 1H ac pg acquire1D pg gen op D H 0 000001 ACQ ac sigma pg sigma_eq sys sigmal pg lypuls sys sigma 1H 90 0 Udelay pg prop H te1 0 5 sigma pg evolve sigrnal Udelay sigmal pg lypuls sys sigma 1H 180 0 Udelay pg prop H te1 te2 0 5 sigmaD pg evolve sigmat Udelay sigma pg lypuls sys sigmaQ 1H 180 0 Udelay pg prop H te20 5 sigma pg evolve sigmat Udelay a simple comment to remind me that this is a test sequence mx ACQ table sigmaQ New Pulse Sequence Test simulation Finished with errors at 2010 10 05 11 30 14 itarting test simulation at 2010 10 05 11 30 25 Test simulation finished successfully at 2010 10 05 11 30 25 Results plott
40. k and the default view is for the Simulate sub tab This panel enables the user to select define and run a new Experiment from the list of defined pulse sequences provided with the Simulation program Additional pulse sequences can be created by the user and accessed using the methods covered in the next section A list of available pulse sequences is kept in the Vespa Simulation database and can be selected from the Pulse Sequence Name dropdown menu The Simulation widget will reconfigure itself based on the parameters needed to run that sequence Users must fill in the Name Investigator Main Field Peak Search Ranges Blend Tolerances and all loop Start Value Step Count and Step Size fields At least one metabolite must be selected and moved into the In Experiment list Some default values are already included EB Simulation New Experiment F lol x Experiment Management View Help Experiment1 Experiment2 Experiment3 gt X Name Jexample Ideal PRESS version Parameters E UUID 43cbc7e9 2239 4a74 b262 d4e667adb8c2 Main Field MHz 128 0 Peak Search Range PPM m Blend Tolerance Investigator Brian J Soher Low o o PPM 0 0015 Created 30 October 2010 High 10 0 Deg 50 0 Comments some inane comment Pulse Sequence Name PRESS Ideal Loops 1 2 and 3 TE1 ms TE2 ms m Metabolites ms ms Ee NO 8 2 Isotope zl Start Yalue In Experiment Availab
41. le pRess2010 06 21713 23 56 database Example OnePulse Data or an Experiments name is Eeer double clicked on the program ener loads the information for that Experiment from the database into an Experiment object in memory This object then creates a set of basis functions for all metabolites for use in the Visualization tab plots N B In the case of a large Experiment this may take a significant isotope fany zl amount of time to calculate but sofield fany is indicated on the lower left of the status bar while calculating Contour Example PRESS 2D stuff2010 06 21113 18 16 Metabolites aspartate choline truncated creatine gaba glutamate glutamine lactate myo inositol n acetylaspartate taurine Open Cancel 11 4 2 Running a new Experiment As noted previously an Experiment object consists of one or more spectral Simulation objects Each Experiment object uses only one pulse sequence but can contain one or more metabolites and one or more sets of timings for the pulse sequence Each Simulation object contains results for a single metabolite for one set of sequence timings Each call to the PyGamma library produces results for a single Simulation object Vespa Simulation loops through spectral simulations for all timings and metabolites to completely fill an Experiment object When a user selects the Experiment New menu option a new Experiment Tab is created in the Experiment Noteboo
42. le Step Count fe fiz acetate GPC gp fo bai see a GPC pcholinet Step Size 20 18 2 GPC pcholine2 J 7 R NAAG truncated ete NAAG truncated sieme alanine Run Experiment Visualize Simulate Hz 4 74343810077 Value 1 500172375663 choline truncated Simulation provides the user with four loop variables for use in their pulses sequences This is covered in detail in Appendix A however in brief The first loop is the list of selected 12 metabolites The remaining three loops are defined as evenly spaced floating point number series Each series is defined by a starting value a number of steps and a step size So for these values start 10 2 steps 4 size 2 0 that dimension would contain the following values 10 2 12 2 14 2 16 2 These values are passed directly to the user s PyYGamma code and can be used in any fashion One might use these values directly as sequence timing values where they represent ms timings between RF pulses Another use might be as an integer series e g 1 2 3 4 5 6 indexing a series of RF pulses stored in a file This way an Experiment could loop through the effects of different RF pulses in an experiment Either way the user can set up three of these loops in the Loops 1 2 and 3 section of the Simulation sub tab Shown in the figure is an example of a new Experiment tab configured for a PRESS simulation Note Metabolite Peak Normalization and Blending The transition tabl
43. le The actual binning code is written in C and accessed through a Swig mapping This code creates three equal length lists called area ppm and phase that are subsequently returned from the execution function to the main Simulation application for storage in the database If the user wants to write their own binning code then they must follow these requirements If the user is careful about what is provided executed in the sequence_code and subsequently used in the binning_code there may be no need for the mx variable But the user must always return the three equal length lists named area ppm and phase A 2 2 The Ideal PRESS pulse sequence typical use of standard parameters Here is the PyGamma code that is in the sequence code string for the PRESS Ideal sequence H pg Hcs sys pg HJ sys D pg Fm sys 1H ac pg acquirelD pg gen_op D H 0 000001 ACQ ac sigma0 pg sigma_eq sys sigmal pg Iypuls sys sigma0 IH 90 0 Udelay pg prop H tel 0 5 sigma0 pg evolve sigmal Udelay sigmal pg Iypuls sys sigma0 1H 180 0 Udelay pg prop H teltte2 40 5 sigma0 pg evolve sigmal Udelay Sigmal pg Iypuls sys sigma0 IH 180 0 Udelay pg prop H te2 0 5 sigma0 pg evolve sigmal Udelay mx ACQ table sigma0 The first thing to note is that this pulse sequence accesses the sys spin_system variable and also the control d
44. lick and drag the tab of the pane that you want to re locate to the position that you want it The Sequence Code tab is a text window in which PyGamma code can be pasted and or edited As defined in more detail in Appendix A this code is executed using the Python exec command and so should be constructed as if it were going to be run in place with appropriate space tab layout See figure below for an example of PyGamma code Binning Code Tab Note This tab is in an AUI Notebook and can be moved and positioned within the Notebook in a variety of ways Left click and drag the tab of the pane that you want to re locate to the position that you want it This is a text window like the Sequence Code tab in which PyGamma code can be pasted and or edited The default binning code as defined in Appendix A is already in place when the New Sequence dialog is created but can be deleted edited as the user wishes As defined again in more detail in Appendix A this code is executed using the Python exec command immediately following the Sequence Code and so should be constructed as if it were going to be run in place with appropriate space tab layout Test Tab When the user clicks on the Test tab the settings in the Design tab are validated and if passed then the Test tab widgets are updated to reflect the pulse sequence design If there are any missing fields or other errors in the Design tab the user is prompted to fix these prior to sw
45. n binning_code string PyYGamma code string executed using exec immediately after the sequence_code to extract the areas ppms and phases from the transition table peak_search_ppm_low float lower end of range in ppm to be searched in binning code see below peak_search_ppm_high float upper end of range in ppm to be searched in binning code see below blend_tolerance_ppm float width of bins in ppm into which similar lines can be combined see below blend tolerance phase float width of bins in phase specified in degrees into which similar lines can be combined see below user static parameters list static parameters defined by the user in the GUI that are stored in this list as strings in the order that they are presented in the GUI see below Note In this One Pulse experiment there are no user defined parameters so the list would be empty dims list this list contains the values of the 4 loops as set for this particular simulation Specifically dims 0 is a string containing the metabolite name dims 1 dims 2 and dims 3 contain the float values of the three counting loops met iso list string value for the isotope of each spin in the current metabolite met cs list float ppm value for chemical shift of each spin in the current metabolite met_js list float ppm value for J couplings of each spin pair in the current metabolite nspins
46. ok right To create a pulse sequence fill in the Design tab the Sequence Code tab and Binning Code tab At this point if you have filled them in correctly you have created a pulse sequence and if desired could quit the dialog Alternatively you can hit the Update Testing Control button and proceed to test and modify your pulse sequence as desired The Test tab and Visualize tab allow you to test your pulse sequence before running it in an Experiment Effectively it allows you to run a mini Experiment where only one metabolite and one value for any loops you defined are allowed More information on these is provided below When you hit the OK button lower right the pulse sequence is saved to the database the New Pulse Sequence dialog goes away and you should see your new sequence listed in the main Manage Pulse Sequence dialog list If you do not wish to save your pulse sequence hit Cancel 21 New Pulse Sequence E x Design Test M Identifying Information Loop Labels Name Loop 1 UUID ae066462 8f5d 4e12 9df1 9e38aeb3f455 Loop zj Creator Loop al Created 05 October 2010 Your Static Parameters Add Remove Selected E Name Default value Comments a A Sequence Code Binning Code Visualize OK Cancel Design Tab Data input fields Name This is how the pulse sequence is displayed in the dropdown list in the Experiment
47. rently there are no experiments loaded You can use the Experiment menu to load an existing experiment or create a new experiment Ready The Experiment Notebook is initially populated with a welcome text window but no Experiment results From the Experiment menu bar you can 1 load a previously run Experiment from the Simulation database into a tab or 2 create a new Experiment and set it up and run it In either case a tab will appear for each Experiment that is loaded or created The Management menu allows users to run pop up dialogs to create edit view delete and import export Experiment Metabolites and Pulse Sequences from the Simulation database The status bar provides information about where the cursor is in various plots and images in the interface throughout the program It also reports short messages that reflect current processing while events are running On the Menu Bar Experiment New Opens a new Experiment Tab in the Experiment Notebook Experiment Open Runs the Experiment Browser dialog from which you can choose an Experiment from the database to open Management Manage Experiments Launches the Manage Experiments dialog Allows user to view clone delete import and export Experiments Management Manage Metabolites Launches the Manage Metabolites dialog Allows user to create edit view clone de activate delete import and export Metabolite prior information Management Manage Pulse Sequenc
48. ribes the settings of the Experiment Metabolite simulations are saved as a collection of lines with amplitude PPM and phase that can be used to recreate a time domain spectrum Each line contains metabolite name loop1 value loop2_value loop3_value line_number PPM area and phase deg The index_loop variables may be set to other than O if the Experiment contains multiple steps in pulse sequence timings E g an Experiment could run NAA Cr and Cho for 10 TE values with TE1 being held fixed and TE2 having 10 values In the output file loop1 index would be fixed and loop2 index would increment 10 times The metabolite name s would repeat 10 times as well as loop2 value is incremented In this way a 2D Experiment is flattened into a 1D output file Experiment 9al4bac7 c47d 4ae2 b7b2 961e942d7d18 Name Example OnePulse Data Public True Created 2010 03 24T16 20 18 Comment abbr Simulation for baseline GAVA database PI bsoher Parameters b0 64 000000 Peak Search PPM low high 0 000000 10 000000 Blend tol PPM phase 0 001500 50 000000 Pulse seq bf0b302c ce1f 46c9 b852 0e7c6b77f95c One Pulse 3 Metabolites aspartate choline truncated creatine 1 Simulations not shown Simulation Results aspartate 0 0 0 0 0 0 0 2 3706 0 03836 0 0 aspartate 0 0 0 0 0 0 1 2 49372 0 02196 0 0 aspartate 0 0 0 0 0 0 2 2 64232 0 409 0 0 aspartate 0 0 0 0 0 0 3 2 70787 0 422190 0 aspartate 0 0 0 0 0 0 4 2 76544 0 52731 0
49. s can also design and test their own Python pulse sequence scripts using the PyGamma library The database also contains prior information current literature values for the NMR parameters of available compounds J coupling and chemical shift values necessary to run the simulations NMR parameters are available in this database for approximately 30 compounds commonly observed for in vivo H MRS The following chapters run through the operation of the Vespa Simulation program both in general and widget by widget In this manual command line instructions will appear in a fixed width font on individual lines for example Vespa Simulation 3 Is Specific file and directory names will appear in a fixed width font within the main text References Examples of spectral simulation for pulse optimization and spectral fitting Young K Govindaraju V Soher BJ and Maudsley AA Automated Spectral Analysis Formation of a Priori Information by Spectral Simulation Magnetic Resonance in Medicine 40 812 815 1998 Young K Soher BJ and Maudsley AA Automated Spectral Analysis Il Application of Wavelet Shrinkage for Characterization of Non Parameterized Signals Magnetic Resonance in Medicine 40 816 821 1998 Soher BJ Young K Govindaraju V and Maudsley AA Automated Spectral Analysis III Application to in Vivo Proton MR Spectroscopy and Spectroscopic Imaging Magnetic Resonance in Medicine 40 822 831 1998 Soher BJ Vermathen P Schuf
50. saved to the database or an export file e Each experiment makes use of and refers to exactly one pulse sequence but the experiment may define one or more timing sets for the pulse sequence e Each simulation creates one spectrum e Each spectrum has zero or more lines Zero is an unusual case but possible e Each spectrum line has one PPM area and phase value in it We expect users to share data via Simulation s export and import functions For this reason several of Simulation s objects experiments pulse sequences and_ metabolites have universally unique ids UUIDs rather than just ordinary integer ids Experiments Experiments are the main focus of the Simulation application An Experiment s raison d etre is to run a set of simulations This set of simulations is the experiment s results space Currently that space is defined by one to four nested loops The first loop covers the list of metabolites the user has involved in the experiment The other one two or three loops are user defined lists of numbers The figure below is a visual representation of a 3D results space one set of metabs and two lists of user defined numbers For clarity we do not show the 4 dimension a k a the last user defined loop as stacks of cubes are hard to visualize 28 Example of simulations for 10 iterations of loop1 along the Z axis starting at 0 0 with a step size of 0 1 8 iterations of loop2 along the X axis starting at 0 4 with a
51. se or in the respective widgets will be updated in the Integral and Contour plots described below after these values are changed by the user Click and release the left mouse button in place and the plot will zoom out to its max setting Click and release the right mouse button in place and the cursor span will be turned off An Integral plot can be created from a 2D Spectral stack plot experiment for a single metabolite Metabolite areas are measured between the Left and Right Cursor settings in each spectrum and for the real imaginary or magnitude data shown The plot will show the integral along the Stack Plot axis displayed in the 1D StackPlot Once the Integral plot is displayed changes to the Left and Right Cursor values or to the Loop index widgets are reflected in the plot The Contour plot works best for Experiments that contain at least two Loop dimensions but will create a pseudo 2D contour plot from an Experiment with only one Loop dimension by repeating the first dimension Contours are integrated over all steps in the two loop dimensions selected in the Contour Dimensions drop box for the Left and Right Cursor settings shown in the Plot control widget and for the real imaginary or magnitude data shown Plotted contours change as the cursor settings change but are only refreshed when the right mouse button is released On the Visualize Widget Display Mode drop list Selects 1D or Stack Plots along index 1 2 or 3 to be
52. se sequences such as One Pulse or Spin Echo only allow 0 or 1 Loop dimensions and are thus the types of available display are appropriately restricted However other pulse sequences can typically use most of the plot modes The three plot modes for displaying results 1D StackPlot Integral Plot and Contour Plot are shown below EB Simulation Example STEAM with TE TM steps 0 sl Experiment Management View Help Experiment1 gt lt Experiment2 Experiment3 Main Plot Controls Display Mode Stack Plot Index1 r X Axis PPM il Max oe iwel am H M Cursor Values PPM il Max 1596 mnf 2409 H Indexi 1 TE ms 5 0 Index2 1 TM ms ka Metabolites to a J Sum Plots lutamate myo inositol M Integral Plot Controls V Show E r Contour Plot Controls JV Show JV Grayscale Levels E Dimensions Contour Index 1 2 D r Basis Function Parameters Line Width Hz Ka Sweep Width Hz 2000 0 e ASCII Display 1 0 1 5 2 0 2 5 3 Points 2048 Visualize Simulate PPM 2 464583690063 Hz 157 74956164 Walue 1 89693439007 lactate The 1D StackPlot window is always open and centered in the screen The Integral Plot and the Contour Plot can be toggled on off using the check box next to their names though their windows remain open whether they ar
53. self When a Tab is closed the Experiment is removed from memory but can be reloaded from the database at a future time assuming it was previously saved 4 The Experiment Tab An Experiment Tab is a tabbed window that is added to the Experiment Notebook Each tab contains one entire Experiment An Experiment Tab can be used to run a new Experiment and view the results of that run It can also be used to load an existing Experiment from the database to view results or to add more metabolites to the Experiment Each Experiment Tab has two sub tabs la x called Visualize and Simulate The Simulate Droit Management View Heb tab is where a new experiment is set up and pene Main Plot Controls run It is also where the parameters and ospeymode fore gt settings for an existing Experiment can be stm ___ S reviewed when the Experiment is reloaded rp iua n The Visualize tab is where the results of an wl ca Hmp 119 4 Experiment can be visualized as 1D plots mea 1 24 etms foo stack plots peak integral maps and or Mmetaboitestort I sum Pits contour maps Gen When a new Experiment is set up there are no results to be displayed so the program defaults to the Simulate tab for New Experiments When an existing Experiment messroecomo o o is loaded it typically contains results from pie simulations that have been run so the P show gasa Jee H program defaults to the Visualize t
54. sity matrix and returns the resulting density matrix The final line applies the acquisition operator to the final density matrix and returns a transition table For more details in PyGamma and GAMMA objects consult the PyGamma documentation Note that the final line of code demonstrates the one output code requirement if the user plans on using the standard binning_code provided by Simulation by default In that case the user must set up a transition table variable called mx Here is the PyGamma code that is the default binning_code string which is automatically inserted into the Binning Code tab for each new pulse sequence definition and subsequently is used in the One Pulse sequence area pg DoubleVector 0 ppm pg DoubleVector 0 phase pg DoubleVector 0 field sys Omega nspins sys spins tolppm float sim_dict blend_tolerance_ppm tolpha float sim_dict blend_tolerance_phase ppmlow float sim_dict peak_search_ppm_low pemhi float sim dict peak search ppm high bins mx calc spectra ppm area phase field nspins tolppm tolpha ppmlow ppmhi if bins gt 0 E area i for i in area ppm i for i in ppm phase i for i in phase else area ppm 31 phase This code expects that there already exists already in the namespace a variable named mx that is a PyGamma transition tab
55. step size of 0 2 and 4 metabolites aspartate creatine glycine and lactate along the Y axis There are 320 10 x 8 x 4 individual simulations 711207 i 12 1 0 M lactate e et Wa 2514 i M lactate L1 0 0 2 04 M aspartate L1 0 9 2 1 8 _ L1 0 9 M lactate L1 0 1 a 2 18 2 04 Ta GE A L1 0 9 M glycine M aspartate wer 2 1 8 Po dL D M creatine L1 0 2 a 2 18 L2 0 4 M aspartate M aspartate L1 0 7 2 ee a ae 2 04 NU 09 4 09 TU Us D M creatine 12 04 2 0 6 2 0 8 M aspartate M aspartate M aspartate Simulations themselves know nothing about one another and are agnostic to the order in which they re run Thus while the existing code is geared towards generating a very regular results space that we iterate over in a very straightforward order more complex result spaces and iteration orders are possible The sky s the limit really provided you can dream up a GUI that allows users to describe the results space A few other rules of note e Once an experiment has been saved the following attributes become read only pulse sequence investigator user parameters bO isotope peak search ppm low peak_search_ppm_high blend_tolerance_ppm blend_tolerance_phase e One can associate additional metabolites with an experiment but once it is associated and the experiment is saved the metabolite remains with the experiment forever In other words a m
56. the user to select an XML file that contains an Experiment If the UUID in the file is unique it is added to the Simulation database Export The user selects an Experiment from the list The program asks if both parameters and results should be included in the export or just parameters A second dialog allows the user to browse for the output filename select if output should be compressed and allows an additional export comment to be typed in Note that the action of exporting an Experiment or other objects caused it to be marked as frozen in the database This means that no changes can be made This is for the sake of consistency as results are shared However a frozen Experiment can still be deleted from the database if needed This file can be imported into another Vespa Simulation installation using the Import function If additional changes are desired a new Experiment using the same Pulse Sequence object can be created and edited 5 2 Manage Metabolites dialog Access this dialog by clicking on the Management Manage Metabolites menu item Actions that can be taken on the Metabolite dialog include New Edit View Clone De activate Delete Import and Export An example of the Manage Metabolites window is shown below The Public column indicates if a metabolite has ever been exported or imported from someone else If the public flag is set then it can not be edited The Use Count column indicates how 17 many local Exp
57. ulation Vespa Simulation is a graphical control and visualization program written in the Python programming language that provides a user friendly front end to the Gamma PyGamma NMR simulation libraries The Vespa Simulation interface allows users to 1 Create and run a simulated Experiment consisting of one or more spectral simulations from lists of metabolites and pulse sequences 2 Store simulated Experiment results in a database 3 Display the results in a flexible plotting graphing tool 4 Compare side by side results from one or more simulated Experiments 5 Output results in text or graphical format 6 Export Import experiments metabolites or pulse sequences from other users 7 Design and test their own PyGamma pulse sequences for addition to the list of pulse sequences available for use in Experiments What is an Experiment An Experiment consists of one or more spectral Simulations Each Experiment uses only one pulse sequence but can contain one or more metabolites and one or more sets of timings for the pulse sequence Each Simulation contains results for a single metabolite for one set of sequence timings Each call to the PyGamma library produces results for a single Simulation Vespa Simulation loops through the spectral simulations for all timings and metabolites to completely fill out the Experiment s results There are a number of predefined pulse sequences in the Vespa Simulation environment and user
58. unctions B 1 One Pulse B 1 1 Sequence Diagram logy Acquisition B 1 2 Loop Variable 1 2 3 Descriptions Loop1 not used Loop2 not used Loop3 not used B 1 3 User Defined Static Parameters none B 1 4 General Description This is a simulation of a pulse and observe or one pulse pulse sequence The typical 90y degree hard pulse is modeled by an ideal GAMMA pulse Despite the slight spacing in the sequence diagram there is no evolution period after the excitation pulse prior to transition table acquisition 37 B 2 Spin Echo B 2 1 Sequence Diagram TE Acquisition Rn a TE TE Ha WER loy en B 2 2 Loop Variable 1 2 3 Descriptions Loop1 Describes the number of TE values to loop over in ms Loop2 not used Loop3 not used B 2 3 User Defined Static Parameters none B 2 4 General Description This is a simulation of a spin echo sequence using ideal GAMMA pulses for the 90y and 180y localization pulses 38 B 3 PRESS Ideal B 3 1 Sequence Diagram TE1 TE2 Acquisition ligoy B 3 2 Loop Variable 1 2 3 Descriptions Loop Describes the number of TE1 values to loop over in ms Loop2 Describes the number of TE2 values to loop over in ms Loop3 not used Notes Pulse sequence TE TE1 TE2 B 3 3 User Defined Static Parameters none B 3 4 General Description This is a simulation of a Point Resolved Spectroscopy PRESS The typical 90 1 80 180 loc
Download Pdf Manuals
Related Search