[clug] Writing Training Materials

Fri Mar 24 11:07:32 UTC 2017

Hi Jeff,

On 24 March 2017 at 20:15, jm via linux <linux at lists.samba.org> wrote:
> I was hoping to find something that would give an overview of how other
> people approach the problem. What I have in mind is a lab manual for a set
> of yet t be decided exercises. I have an example from a Redhat course, but
> thought there might be something more suitable out there that gave a look
> behind the scenes of how it formed. The first iteration would be rough for
> sure that I understand. It's getting something to the point that it is
> usable so that it would be adopted that's the objective.

My recommendation is to dive in and write the part you know (the
exercises), from there I find the formal structure generally just
falls out. It's different for each audience so don't spend too much
time agonising over it. The best part about online training materials
is that it's easy to link out to other things for those who are having
trouble.

I've used wikibooks for this in the past:

   https://en.wikibooks.org/wiki/MINC/Tutorials/Programming04

It has mechanisms by which you can export as a PDF, there's also
pandoc (http://pandoc.org/) and many other conversion/pub tools.

More recently I've used readthedocs in combination with sphinx to
write API documentation and tutorials, it's backed by github and has
great dashboard tools that allow you to check that your code examples
work with a dashboard against the current API. Here's an example:
http://pillow.readthedocs.io/en/3.1.x/handbook/tutorial.html

http://apidocjs.com/ is another example on this. Depends on if you are
writing code tutorials though.

I've also used plain text files (see below for an example). In this
case the workshop was run as a 30min introductory lecture on the
science and motivation of why to do this followed by a 1 hour
tutorial. So you have to adapt the material to suit each time you
teach it. You already acknowledge that it's going to change over time
and this is a good thing. I find the best courses are those that are
continually updated.

Others have suggested exhaustive reviews and needs analysis, this
might work for those with 6 months of free time on their hands and an
army of helpers to agonise over the design of the course and
everything in it. I was forced to go through a needs-analysis,
macro-design, micro-design, etc ... for a MOOC course I wrote sections
of. It was the most frustrating waste of time I can remember in a long
time. My view is that there's no point pontificating and asking your
audience about how they'd like to be taught what they don't know. Take
a crack at it and respond to feedback instead, I find it much more
efficient.

Good luck, and just start writing, starting is the hardest part!

a

---

** Data management, anonymization, provenance and curation

#1 - introduction to neurodebian (linux is the standard for neuroimaging)
   - Why use VM's? - reproducibility of analysis (versions of software)
   - How do you go back after upgrading software?
   - Platform independent
   - allow "cloud" analysis - more on this Tuesday
   - 90% of the software you need is pre-packaged (and thus repeatable)

#2 - FSL, freesurfer  neuro.debian.net
   - How to install data
http://neuro.debian.net/pkglists/toc_pkgs_for_release_data.html

#3 - How to install packages

Neurodebian is based upon the Debian operating system, if you've used
Ubuntu before it too is based upon Debian so the apt-get based install
system may be familiar. There are a number of pre-installed packages
in the menus, when these are selected for the first time they will be
installed. In order to install MRview you can do this as such in the
Neurodebian VM:

   Applications -> Neurodebian -> Medical Imaging -> MRview

The MRview package will then be installed.  You can also install
packages from the command line by running apt-get on the command line
(launch a terminal using the black icon from the panel launcher at the
bottom). To install the itksnap package you could do this:

   $ sudo apt-get install itksnap

It is a good habit to get into using the command line to install
packages as it will allow you to keep a record of which packages you
need for an analysis, for example to install both minc-tools and
itksnap you can do this:

   $ sudo apt-get install minc-tools itksnap

apt-get will install any needed package dependencies as part of the
install process. You can also get an idea of which packages (and
versions) are currently installed using the dpkg command:

   $ dpkg --list

This will allow you to rapidly build a list of installed software and
versions that you have used in an analysis.

#4 - example DICOM file - structure of DICOM

The DICOM medical imaging format has been used for many years in
medical imaging. It is supported by most if not all medical imaging
systems but is not the most widely used analysis format in research,
especially in the field of brain imaging.

A DICOM file is nearly always a single slice of a medical imaging
dataset and a number with matching metadata (same series) are used to
reconstruct a single 3D image. Each of the DICOM files will contain
most of the the metadata for the entire study.

There is a typical DICOM structure from a scanning session in the
DICOM-examples folder on the desktop, it consists of multiple 3D and
multi-slice acquisitions. First launch a Terminal window (black icon
at the bottom) and then unzip the compressed BRAINIX.zip archive:

   $ cd ~/Desktop/DICOM-examples/
   $ unzip BRAINIX.zip

While viewers such as OSIRIX (OSX), Imagemagick, ImageJ and
SanteDicomViewer (Windows) can view this data, we'll use the more
powerfull DICOM tools in the dcmtk package to have a look at the
headers.

If you haven't installed the dcmtk package in neurodebian, you can do
this as such:

   $ sudo apt-get install dcmtk

We can now dump all the headers of the first file as such:

   $ dcmdump BRAINIX/BRAINIX/IRM\ cérébrale\,\
neuro-crâne/T1-3D-FFE-C\ -\ 801/IM-0001-0001.dcm

# Dicom-File-Format

...

# Dicom-Data-Set
# Used TransferSyntax: Little Endian Explicit
(0008,0005) CS [ISO_IR 100]                             #  10, 1
SpecificCharacterSet
(0008,0008) CS [ORIGINAL\PRIMARY\M_FFE\M\FFE]           #  28, 5 ImageType
(0008,0012) DA [20061201]                               #   8, 1
InstanceCreationDate
(0008,0013) TM [145346.000000]                          #  14, 1
InstanceCreationTime
(0008,0014) UI [1.3.46.670589.11.8743.5]                #  24, 1
InstanceCreatorUID
(0008,0016) UI =MRImageStorage                          #  26, 1 SOPClassUID
(0008,0018) UI [1.3.46.670589.11.0.0.11.4.2.0.8743.5.5396.2006120114483570701]
#  62, 1 SOPInstanceUID
(0008,0020) DA [20061201]