Spinal Cord Research Centre

SCRC Data Capture and Analysis Software Tutorials

Guide to writing tutorials for the Analysis program

[ General Guidelines | Data Files/Scripts | Keystrokes | Figures (Screen shotsPlots) | Final Publication | Author ]

We would like to encourage all users of the SCRC analysis software to share with others the techniques they've developed for performing specific analyses. The best way to do this is to write a tutorial, in the format we've developed here, so that even a novice can pick up on the techniques you use and go from there to apply these to their own data analysis. This guide should help you in this task, by explaining the approach we used here to write our tutorials, and giving you some recommendations to follow for making your tutorial consistent with the others on this site.

You may even want to keep this guide open in your web browser as you write your tutorial, so you can refer to it often and make use of the links provided below.

1. General Guidelines

The first few decisions you'll face will be what to write about, and what software you'll use to write it. You'll also have to decide at what level you should be writing, or what your target audience is. Below are several general pointers to help you with these choices.

Write about what you know... or need to know. The best tutorials are the ones that solve concrete problems. If you've just solved a problem, just worked out a technique for analyzing something that wasn't immediately obvious, it may be worth sharing your newfound knowledge with others. Even for problems you're still in the process of solving, it would be useful in any case to document your steps as you go along, so you may want to consider taking the extra step of writing it up for others to use as well.

Don't reinvent the wheel. Take a little while to familiarize yourself with the tutorials already on our site so you don't end up writing something that's already covered in another tutorial. Also please let us know before you begin writing one, so we can assign a tutorial number to your work, and so we know which tutorials are in the works.

Assume some prior knowledge, but not much. The tutorials can build on techniques and terminology covered in earlier tutorials, but don't assume the reader is very comfortable with the analysis program and some of the techniques you may routinely use. These tutorials should be written at a beginner level. Ideally, a complete novice should be able to go through the tutorials in sequence without getting bogged down in a level of detail not explained previously. When you refer to a technique covered in an earlier tutorial, include references in your work. E.g. "Set the cycles as described in sections 3.1 and 3.2 of Tutorial 3" or "Delete the frames using the frmsel program as described in Tutorial 9, section 9.5." Also introduce and explain any scientific jargon you use in your tutorial, as the reader may be unfamiliar not only with the software, but also with techniques or terms you commonly use.

Use the tools you're comfortable with. Here at the SCRC, we use WordPerfect quite extensively because it it readily available, easy to use, and attractively priced for the academic version. It also has built-in PDF export capability, so we don't need additional software to make the PDFs for publishing our tutorials to the web. This is the tool we recommend using. However, if you'd rather use Word, or some other word processor, that's entirely up to you. We don't want to discourage you from writing a tutorial by imposing unfamiliar software on you. We do ask, however, that you make your document available as either a Word or WordPerfect document, as well as a PDF, so that others can easily edit or add to the document later without requiring the installation of some special software.

You don't need to be a web expert to write one of these. If you're familiar with web editing tools, and would rather write up your work as an HTML document, we can deal with that too. Most likely, though, you'll want to use some sort of word processing software and leave the rest to us. That's fine too. We will make the HTML cover page that we have for each tutorial, linking to the document and data you contribute. If you're not able to make your own PDF version of your document, we'll do that too provided your document is in a standard format we can read.

2. Data Files and Scripts

Rather than just documenting a general technique, your tutorial should walk the readers through an example they can try themselves, and compare their results to yours. For this reason, you should make the data files available with the tutorial. Ideally, you should build your tutorial around our standard sample run data files, especially the c08-01 run. Please browse through these files and try your analysis on them to see if they will do the trick. However, if none of these are suitable for the technique you wish to demonstrate, please provide a reasonably sized sample data set to add to our archives for this purpose.

Similarly, if your technique involves the use of shell scripts, please submit these to us as well so we can add them to our shell script archive for others to use. Even if you can't find the time to write a tutorial right away, or ever, if you have a shell script that you feel may be useful to others, please send us a copy. Make sure you include some comments in your script that describe what it does and how it is used.

In either case, include with your submission a list of the data files and shell scripts used by your tutorial, so that we can add links to these on the cover page we'll make for the tutorial.

3. Keystroke Illustrations

You should walk the reader through the analysis, step by step, explaining each step as you go along. Each step should include the actual commands and/or keystrokes used to accomplish that particular task, so that the reader can follow and try it out without a lot of searching around trying to figure out how to set a particular parameter. As much as possible, you should refer to parameters and analysis methods by the same names as they are given in the analysis program, to avoid confusion and ambiguities. Follow these two links to get at the lists of names for each. You can also use these lists to check your keystroke sequences.

Make the keystroke sequences stand out. You should show the keystrokes and commands in a bold font, so they stand out from the rest of the text. It would also help to use colour to highlight them, but use a dark colour so the text will print legibly on a black and white printer. For analysis menu selections, you should show the keystrokes as capital letters, or as capitalized words separated by slashes. E.g. <Esc>SCID or Set/Cycles/In-phase/Delay. Show single keystrokes that must be represented by a multi-letter word or code within angle brackets, e.g. <Esc> for the Esc or Escape key, and <CR> for Return or Enter key (CR is carriage return). Italicizing these also makes them stand out from the rest of the keystrokes. Use the same approach for so-called "modifier" keys (Shift, Ctrl, Alt), e.g. "Use <Ctrl>C to cancel." Try to be consistent in this to avoid confusion.

Explain the reasons for each step. While it's important to walk through all the steps, the goal should be for the reader to understands the purpose of these steps. When you recommend setting a parameter a certain way, explain why such a value should be used, and how that parameter will affect the final results. It may be helpful to demonstrate the effect of different values for a given parameter.

4. Screen shots and Figures

It's one thing to explain what an analysis will do, but a few well chosen figures will likely communicate the message much more quickly and effectively. Fortunately, making these figures can be very easy. A few screen-shots may be all that's needed, or perhaps a final plot file from the analysis, rendered as an image in your document.

End off with a final figure, which shows the intended end result of the tutorial. This will serve as the figure on the cover page, as well as the thumbnail on the tutorial index page, so that you can tell at a glance from the tutorial index which one will yield the graph you want, or something close to it. As well, you should include any screen shots of intermediate results which you feel are relevant, as well as samples of any visual parameter setting steps you describe.

Screen shots

There are a number of different screen grabbing techniques you can use to get screen shots to illustrate your tutorial. Your choice may well depend on which system you use to display the analysis while running it. If you're familiar with Windows-based tools, and run an X Window display program on Windows, you may want to use Windows-specific solutions to getting and manipulating your screen shots. Otherwise, there are some UNIX-based tools you can use.

If you're running a remote X11 session under Microsoft Windows, you can use Windows-based screen grabbing tools: Corel Capture (part of Corel Draw) lets you select a portion of the screen that you want to capture, or you can use the <PrtScr> (print screen) key to copy the whole screen image to the Windows clipboard, for pasting into a window in Adobe Photoshop or Corel PhotoPaint. You can also use <Alt><PrtScr> to copy only the active window, including its border.

If using the PrtScr key, pay close attention to what gets pasted into your photo editing application. I noticed some wierdness with the PrtScr key after doing more than two of them, and pasting into Adobe Photoshop LE. I found the paste operation was giving me the 2nd screen shot over and over, rather than the 3rd, 4th, etc. If I quit the application and started over, it worked again for 2 more shots. It seems to be a bug in Photoshop LE, as Corel PhotoPaint doesn't seem to have that problem.

If you're not using Windows for the analysis, but are working right on a Linux or other UNIX system, there are tools you can use on any platform that supports the X Window system. The sdump program that's included with the analysis software does provide limited capabilities for getting screen shots saved as files, but these images are black and white only, so you may find them lacking for illustrations. However, you can use this if black & white images are acceptable. First, you need to set sdump's options to save files, e.g. "sdumpopt -save sd0001", and then you can use <Ctrl>B or Plot/Video from analysis, frmsel, etc., to get your screen-dump files as sd0001, sd0002, and so on. You can then convert these to GIF as "ras2xbm sd0001 | xbmtopbm | ppmtogif > sd0001.gif".

Alternatively, for colour screen dumps you can use the improved sdump script from our shell script archive to get a screen dump saved directly to a colour GIF file. This improved sdump script is included in release 20070626 or later releases of the software. Using it on older releases will require installing this script in place of the existing sdump program, if you want to run it directly from analysis as above. Then all you need to do is run the sdumpopt command as above, but include the .gif file name extension on the filename you give with the -save option, and this will cause the screen dump to be directly saved as a colour GIF image.

Both of these techniques just grab the inside of the window running the program, without the borders or title bar. If you want a screen shot that includes the whole window, frame and all, or even the whole screen, you can do that too, with a variation of the command in the sdumpgif script above. Running a command like the following, either in a shell script or directly from the command line, will grab the whole screen after a 5 second delay to give you time to bring forward the window you want:

sleep 5; xwd -root | xwdtopnm | ppmquant 256 | ppmtogif > sdump.gif

If all that is getting too technical, there are some simpler techniques you can use to get screen shots. On Linux systems running the GNOME desktop, you can use the <PrtScr> (print screen) key to copy the whole screen image to a PNG file, for which you are prompted to enter a file name and location. GNOME also lets you use <Alt><PrtScr> to copy only the active window, including its border. Under KDE, you can use the KSnapshot utility to capture a region of the screen to the clipboard, then paste into another application.

If your system has the GIMP image editor, you can use File->Acquire->Screen Shot... If your system has the xv program installed, you can run it in the background, and use the Grab button on the xv controls window to get a screen shot. Similarly with xpaint you can get a screen shot from the XPaint tool window using File->Take Snapshot... Either way, you have the option of selecting a region of the screen to grab using your mouse.

If you're working on a Mac, there are numerous techniques for getting screenshots covered in this article: Screenshot Hacks for Mac OS X. However, the quickest and easiest way to grab a whole window onto the clipboard, so you can paste it into a document, is to use <Command><Ctrl><Shift>4 then hit the space bar to select the window you're working on, and click on that window. (The Command key is the one with the Apple logo and/or clover symbol on it.) You can then go to your Word document and paste the graphic into it.

Whatever technique you use to grab the screen shots, you may decide to do some cropping or other editing using whatever image editor you're comfortable with. You may not need to do any editing at all, but if you're grabbing shots of the whole screen, it may be preferable to crop these so they include only the relevant window in the image you end up embedding into your document. You may also want to do some resizing of images in an image editor if the word processor you're using doesn't to a good job of resizing them.

Plot Files

For final output from analysis, a screen shot may still do the trick for your tutorials. However, if you prefer a more uncluttered rendering of a plot file produced by the program, here's a simple way to convert it into an image of the size you want. There's a new program in the 20020426 release of the analysis software, called hpgl2gif, that gives more optimal results for analysis plot files than what some other conversion tools might produce. (It's what's used by the rawwfplt program that makes "movies" of run data, as a series of GIF frames.) Here's an example of its usage:

hpgl2gif -w 600 cbc0201.plt > cbc0201.gif

Use "hpgl2gif --help" to get a description of its options. The -w option specifies the width in pixels, and the height will change proportionally. 600 is an ideal width for the cover page images. We also recommend setting the Data pen to 2 and Markers pen to 3, in the Plot menu, before plotting to a file, so you get a bit of colour in the final graph.

It shouldn't be necessary to get fancier than that with the final plots, unless what you're trying to show in the tutorial is how to pretty up your graphs. For instance, a tutorial on how to prepare graphs for publication, using Corel Draw, could include the original plot file rendered as above, followed by screen shots showing what it looks like when first imported into Draw, then at various stages afterward. This is a hint, by the way, of a tutorial that would be worth writing, if you're looking for ideas.

5. Final Publication/Updates

So you've written up your tutorial, complete with data files, step by step explanations, and all the figures you need to get the point across. What's next?

Proofread it. Check it over carefully for spelling errors and for anything that might be unclear. Walk through the examples to make sure they work as promised, without needing any additional, undocumented steps.

Make a PDF. In WordPerfect 11, use File->Publish To->PDF..., and use ZIP compression in the Objects tab for simple graphics (line art), or JPEG compression with a quality factor of 106 for photos. JPEG compression is really designed for photo compression, whereas ZIP (a.k.a. LZ or LZH compression) and LZW are designed for lossless data compression and tend to do better with line art with limited numbers of colours and large areas of the same color, especially large horizontal runs of one colour. JPEG compression on line art tends to put a "haze" around the lines or the text. The procedure is similar in WordPerfect 9, except that you use File->Publish to PDF..., and select the compression type from the Details tab. There's also a quirk in the compression in WordPerfect 9: unless you always click on the Details tab before making a PDF, it will default to using no compression, not to the last compression type used.

If you're not using WordPerfect, then you should install the full Adobe Acrobat package, and print from your word processing software to the Acrobat Distiller pseudo-printer to generate the PDF. Under Mac OS X, PDF is a native format, so any application has the ability to produce PDF files. There are other PDF generating tools available as well. Use whatever works for you.

Upload the .wpd (or .doc) and the PDF versions of the document. At the SCRC, we currently store these tutorials in the directory dave2:/home/exp/dave/tutorial/cd/, as well as in cliff:/data/tutorial/cd/, as tutorial_number.wpd and tutorial_number.pdf, where number is the assigned tutorial number. If you have access to these systems, please upload the files there yourself. Putting them on cliff will directly update the web server's copy. If you don't have access to these systems, please make them available to us in some other way, either by placing them on another web server or ftp server, or by e-mail.

In any case, let us know that you've copied the new files or updates, and where you put them, so we can do any follow up work that may be needed: moving them into place, updating or making new cover pages, and updating the tutorial index page.

Upload the image for the cover page, if you have one, as tutorial_number.gif. For new GIF images for the cover pages, put them in the same directory on dave2. You can also put them on cliff, if they're the same size as the ones they're replacing (in pixels, rather than in bytes which is less important), or if these are images for a new tutorial. We recommend images of about 600 pixels wide for the cover pages, but anywhere from 400 to 700 pixels will do. Use what's needed for a clear image. If you want to make a thumbnail image too, please do. We put these in the same directory, as tutorial_numberthumb.gif. These are to be exactly 120 pixels wide, and no more than 98 pixels high. We usually make these by shrinking, and possibly cropping, the cover page image, to get something of the size we want. Slightly blurring the image before shrinking it can help make it clearer in its shrunken form, if your image editor doesn't do "anti-aliasing" when shrinking images. If you'd rather not have to make the thumbnail image yourself, you can leave that job to us. We can also make the cover page image too, if you tell us which figure we should extract from your document as the most representative final result of the tutorial.

Upload any new run files the tutorial needs, into the same directory on both dave2 and cliff. These can be uploaded there right away, as no further action is needed on our part. The showrun.cgi program on our web server will find them there and include them in its index. Similarly, any new or updated script files can go in /home/exp/scripts/ on both systems, and they'll automatically be found by the viewscript.cgi program on our web server.

Again, if you don't have access to our systems, please make all images, data files and scripts available to us in some other way, either by placing them on another web server or ftp server, or by e-mail.

Do some usability testing. Enlist the help of a few novice users (new students, technicians) and ask them to walk through the tutorial. This should help sift out any problem areas, which need further clarification or more elaboration of the steps to follow.

E-mail us to let us know of the tutorials you've just uploaded, so we can update the tutorial index page. Let us know where you put them, and what follow up work might still be required. We appreciate any contribution you can make, including producing the PDF files, cover page images, and thumbnails. However, we will gladly make these if you can't. The most valuable contribution is the source document itself, and the knowledge that went into it. Please also let us know which data files and scripts your tutorial uses, so we can include links to these on the cover page.

Keep it up to date. After the tutorial is up on the web site, you may find errors you missed before, or think of a better way of doing something. It may also be that changes in the software in the future will require updates to some tutorials. Please let us know of any updates they need, or better still, update them yourself. You can submit updated tutorials in the same way you contribute new ones. Again, just let us know what follow up work may be needed, such as updating the cover page, index page, thumbnail, data file links, or anything else.

We gratefully welcome any contribution you can make to aid in this effort.

See also: SCRC Software On-line Documentation, SCRC Software Tutorials

© Copyright 2008 G. R. Detillieux, Spinal Cord Research Centre, University of Manitoba. All Rights Reserved. Contact Us for more information.
Revised January 30, 2008.