QDREC Usage Instructions
Please carefully peruse the following instructions before using QDREC. Failure to follow these instructions precisely will lead to errors.
An existing project may be loaded by selecting its name from the drop-down menu and clicking . A project can also be loaded directly by entering its 6-character identifier string into the "project identifier" field and clicking .
At least one set of files must be uploaded to create a project in QDREC. Archives containing example images which comply with the requirements enumerated below may be downloaded here. Image files should be uploaded individually; it is convenient to select a number of image files in the operating system file explorer and drag them all into the file upload area.
Segmentation may be performed automatically with either the Asarnow-Singh method, using phase congruency edge detection for separating touching parasites, or the "Canny" method which uses Canny edge detection for that purpose. These options are both present in the "Segmentation" drop-down menu. Alternatively, previously computed segmentations (such as those provided with the example images) may be provided by selecting "Upload" from the "Segmentation" drop-down. In this case, an additional file upload dialog will appear.
The project must also be given a unique, descriptive name of at least 4 characters in length.
By default, "public project" is checked, indicating that the project will appear in the list of existing projects. To prevent this, uncheck the box. After project creation, a 6-character text identifier will be supplied. This identifier must be saved in order to re-load private projects in the future.
Once images have been uploaded and the form fields filled, click . Project creation may take several minutes depending on the size of the data and the segmentation method selected. New projects will be retained for one week (seven days).
Images must conform strictly to the following requirements:
- Must follow the file name convention defined below
- Must be non-indexed grayscale or RGB images
- Must have a bit-depth of 8
- Must be use the Portable Network Graphics (PNG) format
- Must have the ".png" file extension
- Must have the same name as the corresponding parasite image
- Must have a bit-depth of 1
- Some images may not have a bit-depth of 1 even if they appear black-and-white
- Must use the Portable Network Graphics (PNG) format
- Must have the ".png" file extension
File name convention
QDREC requires that you use a specific file name convention. The convention permits QDREC to record each image uniquely in the database and, critically, to associate each experimental image with the appropriate control. This association is a key component of the QDREC parasite classification approach. See here for details.
Files must be named as follows, not including ".png" extension:
- The date should be a 6-digit, American style (middle-endian) date such as "062113" (21 June, 2013)
- The compound may be any string containing alphabetic characters only
- It is recommended to use an abbreviation of the full compound name
- Control images must have the string "control" in the compound field
- The concentration is the decimal concentration in micromolars, with a leading zero but no decimal point
- For example, the string "001" indicates a concentration of 0.01 µM
- Control images must have concentration of zero
- Exposure time must be an integer number of elapsed time units (e.g. days)
- The "series" field is used when replicate experiments have been performed, which would otherwise lead to identically named files
- The series must be a single, alphabetic character, such as "a" (or another letter)
Here are several examples:
Date: 29 July, 2013
Concentration: 0.1 µM
Exposure: 4 units (e.g. days)
Date: 21 June, 2012
Compound: N/A (control)
Concentration: 0 (control)
Exposure: 2 units (e.g. days)
Date: 21 June, 2012
Concentration: 10 µM
Exposure: 1 unit (e.g. days)
When a new project is created, you will be given the chance to review the segmented images, to ensure that they are sufficiently accurate. If previously segmented images were uploaded, or if an existing project is loaded, segmentation review will not launch immediately. Instead, it may be accessed by navigating to Review Segmentation.
If segmented images appear insufficiently accurate, you may resegment the project. Click the to show the form for resegmentation. After selected the appropriate segmentation algorithm, fields for any required method parameters will appear. For details, see here.
Different sets of images should be used to train and test the classifier. Thus, it is necessary to divide a project into subsets which can be separately selected for training or testing. If only testing will be performed, it is acceptable to place all project images into a single subset.
Subsets are defined by selecting multiple images from a project, providing a descriptive name of at least 5 characters in length and clicking .
The form also lists existing subsets. Clicking one will automatically select the images belonging to that subset. If the same name as an existing subset is provided before clicking , then the existing subset will be updated to reflect the currently selected images.
Clicking will invert the selection (selected images are unselected, and vice-versa). Clicking will clear the selection (unselect all images).
Newly defined or updated subsets will be immediately reflected in the list of subsets. It is recommended to create at least two subsets, one for training and one for testing.
Images must be associated to controls in order to be used in QDREC. If a control has been left out of a subset definition, it will be added automatically and you will be notified. If any images are missing controls, you will be asked to manually associate these images with the appropriate controls before continuing.
If manual association is required, a new form area will appear containing a drop-down menu for the images which are missing associations. After selecting an image in the left drop-down menu, the right menu will be populated with possible controls. Select one, then click . Once the association is complete, that image will be removed from the left of images which need manual association.
Create New Classifier
The first step in training is to select the appropriate subset from the menu at the top of the training interface. Once selected, the interface will switch to the chosen set of images.
No training is required to use the existing classifier. Also note that if separate subsets for training and testing have been defined, it is not necessary to provide annotations for the test set.
The QDREC Trainer will present you with a series of matched experiment and control images. The experimental images are decorated with bounding rectangles which indicate the parasites which were found by the computer vision algorithm. These rectangles are blue, which indicates the "normal" classification.
Click inside a bounding box to mark a parasite as "degenerate." The bounding box will turn red, reflecting the recorded state of that parasite. You can switch a "degenerate" parasite back to "normal" by clicking in the box again. This will also toggle the box color back to blue.
Clicking will cause all parasites in the image to swtich state (e.g. from normal to degenerate or vice versa). Clicking will reset all of the parasites to the normal state.
When you have finished classifying the parasites in an image, click to advance to the next image. As you advance through the images, your progress will be noted. You may also return to previously visited images by clicking .
The Trainer will remember your progress, so if at any time you would like a break from training, just exit the system. When you return and load the project, you will be able to pick up with training where you left off. You may also explicitly save annotations for the current image by clicking , for example if you plan on immediately closing the browser window completely.
If a new classifier should be trained, navigate to the "Train Classifier" tab.
Use the drop-down menu for selection of the subset for training, then use the radio buttons to select the desired classification algorithm. Fields for any required method parameters will appear. For details, see here. It should be fine to leave the parameters set to their default values.
Once the training set and parameter values have been selected, click to train. Be aware that training may take several minutes depending on the size of the data. When training is complete, the cross-validated confusion matrix for classification of the training set, as well as the single-image response values, will be displayed in tabular form.
If no new classifier has been trained, simply select a subset from the first drop-down list, and click . If a new classifier is available, you may use the radio buttons to select either the new classifier, or the existing one. Be aware that classification may take several minutes depending on the size of the data.
When classification is complete, the results will be available in two forms (see below). Keep in mind that the most recent classification results will be stored until you either 1) create or load a new project or 2) end the browser session.
First, a simple plotting interface will appear under the "Plot Results" heading. Click this heading to hide and show the plotting interface.
A particular drug compound can be chosen from the drop-down menu. Click in order to display interactive response plots for the selected compound.
The tabular results include single-image response values for the test set. Click under this heading in order to view the results table. Click to download the results in comma-separated-values (CSV) format.