seder_tutorial

SEDER Tutorial

Intro
Setup
Navigation
Add a new study
Create a new subject to the system
Add that subject to a study
Collect MEG and or MRI
Attach meg_raw
Attach mri_raw
Add clinical info
Add freesurfer analysis
Add dipole analysis
Add report parts
Add dspm
Add clinical reports
Review

INTRO
In this tutorial, you will go through from start to finish, setting up a subject in the seder software.
Hopefully, it will familiarize you with the different tools you need.

SETUP
Log in to an SSH terminal.
At the command prompt, enter:

seder_setup

NAVIGATION
To see the subject meta tree, you enter this:

    cd $SEDER_SUBJECT_META
    ls

You should see all the listed subjects so far.

To see the study meta tree, you can enter this:

    cd $SEDER_STUDY_META
    ls

Now you see all the listed studies.

ADD A NEW STUDY
In this section, you will add a new study. The software will not let you add a study if one
exists with the same name already.

Try this:

    seder_new_study

You should get a small message from the program explaining how to use it.
The reason you get that is because you did not specify the name of the study.

Now try again:

    seder_new_study epilepsy

If this study exists, the software will complain a bit.
I also want to have a study called language.

    seder_new_study language

One more time, let's make a new study. This time call it foobar.

    seder_new_study foobar

If the study does not exist, then it will get created. To verify this, check here:

    ls $SEDER_STUDY_META

You should see your study listed.

When you originally make a new study, there is nothing but one folder generated. Therefore,
if the study was made in error, it is very simple to remove the study. Here is how:

    cd $SEDER_STUDY_META
    rmdir foobar

(The will not work if the study has stuff in it already)

CREATE A NEW SUBJECT TO THE SYSTEM

Ok. Now you are ready to start. You have a study called epilepsy and another study called language.
Let's add in a new subject to the system now.

You must enter this command:

    seder_new_subject

Note, that if you enter that command exactly like that, it will give you instructions about exactly how to
use the command.

Now lets try this out.
Use a real name of a patient this time.

    seder_new_subject epilepsy <lastname> <firstname>

For example, lets say the name was "Jon Doe" so I would write...

    seder_new_subject epilepsy Doe Jon

If the subject name is new to the system, everything is ok. You should notice the NMR ID of the subject.
On the other hand, if the subject is known already to the system, it will ask if you want to generate a new ID.
I do NOT recommend generating more than one ID for the same person!

Just to make sure you see that this happens, try to run the same command you did a moment ago,
a second time. You should get prompted for generating a new ID or not. Say "n" for no.

Remember the NMR ID that you got for your subject! It is important.

You can see that your subject was added to the subject meta tree. Type this:

    ls $SEDER_SUBJECT_META

You can also see that the subject was added to the epilepsy folder in the study meta. Type this:

    ls $SEDER_STUDY_META/epilepsy

ADD THAT SUBJECT TO A STUDY

Now I want you to add that same subject to the language study. When you created the subject,
you associated them with epilepsy. Now lets connect them also to language.

Type this:

    seder_add_subject_to_study

You should get instructions for how to use this,

All we need is that NMR ID and a study name.
So lets do it

    seder_add_subject_to_study <NMR ID> language

If you did this right, you should see no errors.

You can verify that everything worked by checking the study meta tree under language.

    ls $SEDER_STUDY_META/language

COLLECT MEG AND/OR MRI

At this point you would collect MEG and/or MRI data. You can use old data as well for this.
The idea is that you would normally collect data at this stage.

ATTACH MEG_RAW

Now, assuming you have some raw MEG data somewhere, you can attach that data to the seder system pretty easily.
The command to use is:

    seder_new_meg_raw

When you type it, it gives you instructions about how to use it.

To do this right. we need to know the exact location of the real MEG data.
Lets say (hypothetically) that it was stored here:
    /space/megraid/38/MEG/epilepsy/clin_123456/020829

In that case, the following info is known:
    MEG ID = clin_123456
    YEAR = 2002
    MONTH = 08
    DAY = 29
    STUDY = epilepsy
    MEGRAID = 38

Using the info gathered from the pathname of the data, you can now connect that data to
seder.

    seder_new_meg_raw <NMR id> <meg_id> <yyyy> <mm> <dd> <study name> <megraid>

If everything works ok, then you should get prompted for some initial notes. You may have some
and you may have none. Add what makes sense here. DO NOT waste your time writing things that
are obvious or redundant, such as "subject for epilepsy".

When you are done, you can verify the connection by entering the subject's meta directory:

    cd $SEDER_SUBJECT_META/<nmr ID>
    ls

You should find a new dataform called meg_raw there. You can open it if you like.

ATTACH MRI_RAW

If you have some raw MRI data to attach, you can do that now.
The command to enter is:

    seder_new_mri_raw

This command will give you further instructions if you type it as is.
To get the data correctly attached, you must know the ID used in the raw MRI data
directory (for example, clin_38463612), as well as the exact date that the data was collected.

When you have this information, connect the data to your subject with this command:

    seder_new_mri_raw <NMR id> <mri_id> <yyyy> <mm> <dd> <study name>

When you are done, you can verify the connection by entering the subject's meta directory:

    cd $SEDER_SUBJECT_META/<nmr ID>
    ls

You should find a new dataform called mri_raw there. You can open it if you like.

ADD CLINICAL INFO

Now perhaps you would like to add some clinical information about this patient. Here is what you do:
Enter this command:

    seder_new_dataform

Command instructions will come up.

The type of dataform you are interested in is called "clinical_info".
Suppose you forgot that? You can always ask seder for a list of possible dataforms using:

    seder_name_dataforms

So now you can add the clinical info like this:

    seder_new_dataform <NMR id> epilepsy clinical_info

You will be asked about any inital notes. Obviously you should NOT write anything here that would go elsewhere
in the clinical info database files.

When you are done, you can verify the connection by entering the subject's meta directory:

    cd $SEDER_SUBJECT_META/<nmr ID>
    ls

You should find a new dataform called clinical_info there. Open it with this command:

    cd clinical_info

You will find a project/date directory. Open that too.

Inside, you will notice a special file called "clinical_info.txt", and another one called "contact.txt"
You can examine the contents of these files with any text editor that you like.
I generally used GEDIT or EMACS or PINE. But use whatever one you favor.

VERY VERY IMPORTANT!!! You need to be very consistent when you edit these database files.
One and ONLY one tab allowed after the name of the field. Don't use TAB in what you write.
Any date that has has no day or month, use 00
Any field that has multiple choices, you must use EXACTLY one of those choices (don't change the capitalization
or spelling etc).

ADD FREESURFER ANALYSIS

To add a freesurfer analysis, you will use the same command as previously:

    seder_new_dataform

Only now, we will use the dataform called "freesurfer".

    seder_new_dataform <NMR id> epilepsy freesurfer

This command will require some dependancy info. Your freesurfer analysis will be
dependant on the mri_raw data. It may also have other dependancies. It is important
to list dependancies correctly as they show up in the seder lists. Here is an example
of some dependancies:

    mri_raw/epilepsy_2004_03_23
    dti/epilepsy_2005_01_30

Also initial notes here must relate to anything useful and non-redundant. Don't bother
with a comment if you don't need one. But definitely put one if there is something
important about this data.

When you are done, you can verify the connection by entering the subject's meta directory:

    cd $SEDER_SUBJECT_META/<nmr ID>
    ls

You should find a new dataform called freesurfer there. Open it with this command:

    cd freesurfer

You will find a project/date directory. Open that too.
You can now see a new directory which is mostly empty except for the SEDER files.

In the case of freesurfer, where they generate lots of files for you, you will probably
have data sitting somewhere. Most likely this data is sitting in the wrong location.

So to move your real freesurfer stuff into our newly generated freesurfer system...
1. get the full path of your real freesurfer dir. (example "/space/doodles/3/users/subject4")
2. cd into the new freesurfer directory (inside the project/date dir)
3. enter this command:

    cp -r <real freesurfer dir>/* ./

(for example, cp -r /space/doodles/3/users/subject4/* ./ )

If you are not copying, but rather MOVING the files, you can instead use the move command:

    mv <real freesurfer dir>/* ./

Now you should have all the freesurfer stuff in the right place.

ADD DIPOLE ANALYSIS

To add a dipole analysis, you will use the same command as previously:

    seder_new_dataform

Only this time, we will specify one of the two allowed dipole dataform types:
dip_sandbox
or
dip_clin

What is the difference?
dip_sandbox is a place to try lots of different dipole fitting.
dip_clin is where ONLY final important clinical result dipoles are saved.

You may never need a dip_sandbox, and you may never need a dip_clin.
But it is important to use the correct kind when needed.

Ok. So make a dipole directory for your subject. Let's use dip_sandbox.

    seder_new_dataform <NMR id> epilepsy dip_sandbox

When you enter this command, you will notice that seder wants to know the
dependancies of the dip_sandbox. There should be two things relevant here.
First, the meg_raw data. Second, the T1 MRI image. This image might be in the
freesurfer directory, or you might have it somewhere else. Knowing where it is
will help! Whenever possihle, list the dependancies using the seder links, so that
the physical location of the file is not important anymore. For instance, listing
the name of a megraid is NOT helpful, because if the data moves from one megraid
to another then you are in BIG trouble! But if you list the project/date and the type
of data, then there is a better chance of finding the data.

As usual, initial notes are only useful if they will be non-redundant.

When you are done, you can verify the connection by entering the subject's meta directory:

    cd $SEDER_SUBJECT_META/<nmr ID>
    ls

You should find a new dataform called dip_sandbox there. Open it with this command:

    cd dip_sandbox

You will find a project/date directory. Open that too.

Inside this directory, along with the usual files, you will find a file called "sphere.txt".
It contains 4 numbers, the x,y,z and r coordinates. These are listed with one digit past the
decimal place, and each number has a TAB after the text field, like this:
x   10.3
y   20.3
z   39.3
r   59.2

It is NOT recommended to put ANYTHING else in this file. Any comments can be added
to the SEDER_FINAL_README.txt file.

You should note that if you create a dip_clin directory, the same exact sphere.txt file will
show up as well. It is important to edit this file, so others can use your data.

If you have already completed a dipole analysis, copy all the files into this newly created
directory.

You can make a collection of all dipole files into a file called "all_runs.bdip" using this
command:

    seder_collect_all_dipoles

If you run it more than one time, it will simply re-compute the all_runs.bdip file again based
on whatever .bdip files exist in the current directory.

ADD REPORT PARTS

Another possible dataform is report parts. This is used for image files generated by the dipole analysis.
To create a report parts directory, do this:

    seder_new_dataform <NMR id> epilepsy report_parts

As usual, you need to list dependancies. Of key importance is the dipole analysis that was
used to generate these files. So you must know for instance that the dip_sandbox or dip_clin from
such and such a date was used, otherwise no one will be able to figure out where the pictures
came from! Here is an example list of dependancies:
    meg_raw/epilepsy_2003_01_03
    freesurfer/epilepsy_2004_02_29
    dip_clin/epilepsy_2004_04_17

Make any inital notes that will help someone focus their attention on specific features of the pictures.

When you are done, you can verify the connection by entering the subject's meta directory:

    cd $SEDER_SUBJECT_META/<nmr ID>
    ls

You should find a new dataform called report_parts there. Open it now. Open the project/date directory.

You should copy into here any image files which exist for this subject based on dipoles.

ADD DSPM

Now we want to add DSPM data.
Again, you use this command:

    seder_new_dataform

Only now, you use the dataform called "dspm". The command will be:

    seder_new_dataform <NMR id> epilepsy dspm

As before, the correct dependancies will be very valuable. So make sure that
you connect this dspm data to the correct freesurfer data and meg data.

The inital notes should reflect the reason for this dspm (such as "suspect propagation")

When you are done, you can verify the connection by entering the subject's meta directory:

    cd $SEDER_SUBJECT_META/<nmr ID>
    ls

You should find a new dataform called dspm there. Open it, and the project/date directory.
Inside here, you should put any dspm analysis that has been completed. Use the cp command to
copy files.

ADD CLINICAL REPORTS

Now you can add any clinical reports to this subject.

You will use our old friend, seder_new_dataform again. The dataform is called clinical_reports.

    seder_new_dataform <NMR id> epilepsy clinical_reports

The dependancies here should list anything that was used to make this final report, such as the
meg_raw, the dip_clin, the clinical_info, the dspm, etc.

The initial notes are only useful if they will say something not listed in the clinical reports themselves.

When you are done, you can verify the connection by entering the subject's meta directory:

    cd $SEDER_SUBJECT_META/<nmr ID>
    ls

You should find a new dataform called dip_sandbox there. Open it with this command:

    cd clinical_reports

You will find a project/date directory. Open that too.

Inside this directory, along with the usual files, you will find a file called "NMR_findings.txt".
This file has a database of some usual important findings. The usual comments apply here,
you must be very consistent when using this file. ONE tab per line, that is between the field
and your remarks. If choices are listed, use one of the possible choices exactly as written.

Any other final report data should also get copied into this location.

REVIEW

In this tutorial, you have learned how to use the following commands:
seder_setup
seder_new_study
seder_new_subject
seder_add_subject_to_study
seder_new_meg_raw
seder_new_mri_raw
seder_name_dataforms
seder_new_dataform
seder_collect_all_dipoles

You should now have the ability to retrospectively add old data into the seder system, as well as
prospectively add new data into the seder system as it is being made.

You can use the FIND command in your browser to look up any of these commands.
Also, each command should have a short manual page in the SEDER TOOLS presentation.