Tutorial

This is a walk-through tutorial which explains all the steps necessary in order to design an examination sheet, collect desired data and preview examination results.

Instructions on these pages are for Windows and a 32-bit Python interpreters. Many of the tools will work on other systems as well, please contact the author if you need support for other operating systems or Python distributions.

Installation of Python and Inkscape

If you are a scientists and you have never used Python before it is advisable to get Python distribution called Enthought Canopy. Otherwise, head over to http://python.org and download an install the lastest 2.x version of Python for you operating system. We recommend using the 32-bit Python (X86 or win32), for example the wacom modules are available only in 32-bit version. Most of the tools provided with CogExTools work in both 32-bit and 64-bit (X86-64 or amd64) Python environments.

CogExTools have a few dependencies. Some of the portable dependencies are included with the program. Users using the Enthough Canopy Python distribution should have all the packages available for use. The recommended method of installation of missing packages in other Python distribution is from Windows installers available at a repository at http://www.lfd.uci.edu/~gohlke/pythonlibs/.

The packages that CogExTools depends on are as follows:

numpy numerical python, required for all data recording and processing
matplotlib MATLAB style plotting, required for data evaluation scripts

Packages included in “cogex_packages.zip”:

pyPdf compose PDF files
pyglet graphics and visualization interface (included in cogex_packages.zip)
cairo rasterization engine, used only by cgexam_tablet.py
wintab Wacom interface for Python

This tutorial will rely on one more application independent of Python. The Inkscape application is available at http://www.inkscape.org/, again choose the latest version of the software for your operating system.

Designing an examination sheet

CogExTools is a framework designed around the open format for scalable vector graphics called SVG. SVG is a mark-up language, similar to HTML, developed for the description of graphical elements (see http://www.w3schools.com/svg/). In theory it is possible to create SVG graphics using a text editor. A modern web browser like Google Chrome, Mozilla Firefox, Apple Safari of IE10 will render SVG examination sheets directly without any plugins.

In order to create an examination sheets in this tutorial we will use the free vector graphics editor Inkscape (http://www.inkscape.org/en/). This application will be helpful in many other tasks besides the sheet design. Inkscape can be used for for translation of SVG to other formats, such as PDF (for printing) or PNG (for consumer tablet experiments).

We are going to create a simple test sheet for a “Figure copy” task. Subjects will be asked to copy and rotate (mirror) figures from upper half of the sheets to the lower half, as on the following image:

_images/clip0007.png

The red figures in image above will be not visible on the examination sheet, however they will be available in the sheets SVG file. Later we will show how such information can be used for automating evaluation of the collected data.

Next we explain how to create the SVG sheet for the “Figure copy” task. First launch the Inkscape application. Create a new design using the menu and head to the “Document Properties ...” dialog in the “File” menu. We prefer to design examinations on B4 (one of Japanese standard paper sizes). This is the size that fits best into the pen sensitive portion of Wacom Intuos5 tablet. Keeping the proper dimension at the time of sheet design will ensure that proportions of objects and thickness of lines will be exact when sheets are printed. The “Document Properties” dialogue allows one to choose the size as well as the units of the design.

_images/clip0006.png

Other tablets of different sizes can be used as well. Sheets can be either adjusted by hand, or they can be automatically resized by export tools in the toolbox.

Once the paper is ready we create the figure for copying. The resulting sheet is in figure below:

_images/Tutorial_tools.png

The elements in the upper half of the sheet were created by tools highlighted by red enclosure close to the left border of the image. The “Context” tools in blue enclosure in the toolbar above the sheet ere used to rotate the lower red copies of the top figures. The red items were moved into a second layer (see green enclosure), which is used to separate the visible elements of . The “Truth” layer can be made invisible by clicking its eye icon in the “Layers” panel. Such invisible elements are not visible when image is exported or printed, however the sheet’s SVG file preserves their definition. These elements can be used later for evaluation of collected data.

The sheet design step of cognitive developments ends with saving the SVG file, in this example we will use the “File -> Save As ...” option from menu to save the sheet as “TutorialExam/Sheet1.svg”.

Many scripts of CogExTools work with multiple sheets, if multiple sheets are processed they are always processed in alphabetical order.

Preparing sheets for paper based examination.

Paper based examination requires:

  1. pen input enabled tablet (currently Wacom Intuos5 Pro has been tested)
  2. printed sheets

A small number of sheets can be printed manually from within the editor or web browser which supports the SVG format. For larger amounts and extra features CogExTools provides a script that can generate PDFs for printing. The usage of this script for SVG sheets stored in subdirectory “TutorialExam” is:

cgtmake_sheets.py TutorialExam

Detailed documentation of this tool is provided within the source code of this file and in the Documentation.

Preparing sheets for examination in tablets.

Tablet based examination requires:

  1. a touch or pen enabled tablet, running Windows operating system (not the RT version) [1]
  2. rasterized examination sheets (images of sheets in PNG format)

The tools described in the “Preparing sheets for paper based examination” section can be used in order to generate rasterized versions of the examination sheets. The usage is as follows:

cgtmake_sheets.py -nopdf TutorialExam

The “-nopdf” option only disables the PDF generation, by default this script generates both the PNG and PDF versions of the sheets.

Detailed documentation of this tool is provided within the source code of this file and in the Documentation.

Footnotes

[1]Mouse controller can be also used, however this controller is not well suited for the task developed in this tutorial.

Running an examination.

To execute an examination use the application that supports your input digitizer. At the moment the CogExTools package contains demo code for recording using Wacom tablets, and desktop and tablet PCs running Windows. The Windows demo application uses the computer’s mouse as the input digitizer, this you can test and extend the application even without a pen enabled tablet. Touch events are detected as mouse button clicks and mouse dragging.

To execute an examination and start recording use one of the two scripts provided for recording.

For Windows devices use

cgexam_tablet.py TutorialExam

This script executes a fullscreen application that shows all PNG images from folder “TutorialExam” in alphabetical order.

For Wacom devices use

cgexam_wacom.py TutorialExam

the “TutorialExam” (the directory used throughout this tutorial) should point the application to the folder of examination sheets.

We can use the Windows program to test our examination sheet on a regular windows PC. As mentioned, the input if Windows examination tools is simulated by mouse.

Previewing recorded data

Examination tools introduced in previous sections produce data files, which contain raw time-series of values provided by input pen sensors. One tool in toolbox will work on any type of examination. This tool can be used to display the complete recording while enhancing desired features of the drawing. The examples below show data collected based on our “Figure copy” design:

_images/wacom_ses20140728105056[Sheet1].png _images/wacom_ses20140728103730[Sheet1].png

The command used to obtain these figrues was:

cgtdata_preview.py data/wacom_ses20140728105056[Sheet1].i4

where the string of numbers 20140728105056 is a timestamp unique to every recording.

Analyzing data

It is better to explore the data on-line, in an interactive console. Probably the best option currently for doing this is IPython. In an interactive session we can open a data recording and obtain a 2d array (matrix) containing among aothers the 3d pen tip coordinates and, if tablet supports it, pressure and angle of the pen in time. The following example shows two basic functions of the cogextools package that are used by most of included analysis programs. The function penopen transforms recorded data into an array of time-series a (each column holds a different feature). The function segments then computes a list of indices, pairs i0 and i1, which mark the beginning and end of a stroke. The snippet demonstrates how to use these indices in order to plot the strokes and color each with a random color.

# import cogextools functions
from cogextools import *

# open data file
fname = 'data/tablet_CDT_age5.f8'
a = penopen(fname)
ins = segments(a)

# plot in-air movement with a red line
j0 = 0
for i0,i1 in ins[:-2]:
    plot(a[j0:i0,2],a[j0:i0,3],'r.-',ms=3.0,lw=0.25)
    j0 = i1

# plot strokes with blue line
ci = 0
colors = 'bgrcmyk'*(len(ins)//7 + 1)
for i0,i1 in ins[:-2]:
    plot(a[i0:i1,2],a[i0:i1,3],'o',ms=5.0,
         color=colors[ci%len(colors)],mec='none',alpha=0.2)
    ci += 1

axis('image')
axis([450,900,100,520])
# turn off the box axis and save the figure
axis('off')
savefig('CDT_age5.png')

A correct execution will reult in an image similar to this:

_images/CDT_age5.png