Pulse sequence database documentation
From NMR Wiki
This document aims to fully describe technical details of the pulse sequence database.
For a simpler description, please take a look at the following:
Please use table of contents below to navigate this manual.
Contents |
Structure of the pulse sequence database
The Brief overview of the Pulse Sequence Database outlines the overall structure of the database.
Two components that were not covered in the "brief overview" are a collection of templates that help build the database and registry pages.
Sections below describe the individual components in more detail.
Laboratory/company-specific parts of the database
It is important to state that pulse sequence record and repository are specific to the laboratory/company that produced the pulse sequence.
Each laboratory/company has it's own pulse sequence template, independent directory in the repository and a special "registry page".
NMR experiment records
NMR experiment records are wiki pages that describe essence of the experiment regardless of implementation details on any specific hardware.
All of those documents fall into category "NMR experiment" and have automatically generated links to the relevant pulse sequence record pages.
What turns the regular page into the "NMR experiment page" is a clause {{NMR-experiment}}. This is a statement inserting template named NMR-experiment
That template inserts a statement that generates listing of pulse sequence pages linking into this experiment page. Also the template adds a category link [[Category:NMR experiment]], so that the page becomes automatically discoverable here.
Besides basic description, NMR experiment page should contain literature references.
Registry pages
TODO: describe purpose of registry pages and how to edit them
Pulse sequence records
These are also regular pages - but in this case - one for each hardware-specific pulse sequence implementation.
Pulse sequence entry consists of two parts:
- a structured template record containing some basic information
- freehand text description - should include listing of parameters, processing instructions and literature references
- category links/tags - these enable the search interface to filter the records.
Example
{{gtm-pulse-sequence
|name=hetzyT1_ch3
|synopsis={{15N}}-HSQC with T1 measurement
|author=cbr, gtm
|console=Unity
|field=500
|observe=H
|nuclei=HN
|dim=2
}}
freehand text
[[Category:HSQC]]
[[Category:T1]]
In the example above anything within double braces {{ ... }} is the template record.
Freehand text goes after.
In the end there are category links (these actually can go in any order, but it is best to keep them together in one place).
Pulse sequence template record
There is a general template called Template:pulse-sequence-record. It is not used directly, but through some other inheriting template.
The actual template that should be used on the pulse sequence pages is one of available templates from this list that has name in the forum XYZ-pulse-sequence, where XYZ is name or initials of the lab PI, or name of the company .
If no matching template is found in the list - then a new one must be created.
Those derived templates inherit the "pulse-sequence-record" and have some fields of the template pre-filled, the most important pre-filled fields are:
- local_library
- registry_page
local_library field is name of the directory in the file repository that stores the corresponding pulse sequences.
registry_page is name of one of the pages that belongs to this list. Those pages contain information that maps peoples initials with their full names. A comma-separated list of initials is used as a value of authors template parameter.
Other fields that are pre-filled in the derived templates are for convenience:
- copyright
- + any other parameters that repeat from record to record.
It is very likely that a given laboratory creates only liquids pulse sequences and only for Varian - so fields medium and platform might as well be pre-filled to save typing.
Freehand description of pulse sequence
- listing of parameters - only independent parameters that are not calculated/hardcoded must be described
- any instructions to process an analyze data
- literature references - this document describes how to insert citations
Adding/removing tags
Tags also known as category links allow retreiving records via the search interface, so they are very important.
Some tags are created by the template - to adjust those you will need to change fields in the template record.
Others will be added explicitly by the user. For example for pulse sequences containing HSQC element tag [[Category:HSQC]] will be appropriate. Just type it in in the end of the page (this is a convention for placing category links).
If some category does not exist just type in the tag the way you want to see it. Category will be automatically created.
Also as you see pulse sequence database tags are regular wiki category links.
TODO: Which category links to use here? Where to find them?
Pulse sequence file repository
The active file repository is actually a simple directory on the server it is not easily searchable by itself, but holds all the necessary files. In addition, this directory is revision-controlled using git system with a mirror at the public github service.
You can contribute source code files either via github or by email at inbox@nmrwiki.org.
Structure of the pulse sequence repository
TODO: describe this
What is git and github?
Git is a version control system developed to maintain code of the Linux Kernel. Git system is now increasinly used by the software developers.
Github provides a popular free public repository hosting service.
How to use PSDB git repository?
1. Get started
This needs to be done only once.
- register an account at github
- add personal keys to your account
- install git on your computer
- fork the psdb repository
This will give you your own copy of the psdb repository.
2. Get some work done
clone your repository onto your local system
git clone git@github.com:youraccount/psdb.git
Above, "youraccount" part will be your actual github user name.
By now you will have created a directory called 'psdb' containing a full copy of the repository.
Add/change some files using conventions described in the psdb README file.
Sample git session
For example, if you have added a file mylibrary/bruker/lists/pp/cosy to the psdb directory, add it to the repository "commit buffer" (called "index" in git terminology).
git add mylibrary/bruker/lists/pp/cosy
Add more files in the similar fashion (even if you edit some file, you'll need to run git add command).
Once all changed files are "added", commit the whole set of changes to your local repository.
git commit -m 'added cosy pulse sequence in bruker format'Now you have the fresh change entered into your local computer copy of the repository, but it is not yet available to anyone else.
Push your local changes to github:
git push origin master
This means that you want to push your master branch onto origin (which is your github repository).
Adding files is not the only function you will need to perform under git. You will also need to delete files, rename them, create a new branch, merge branches, etc.
Please peruse online git crash course to learn more about git.
Templates
TODO: describe function of each template in the PSDB system.
