SID (Spot Intensity Detector) software
===================================

SID is a MATLAB program for detecting spot intensities in microscopy images in 2D
or 3D, in up to four channels.

This software is licensed for use under the GNU GPL v3 license. See LICENSE file
for details.


Installation
------------

No installation is necessary, simply copy the source code to the directory of
your choice. Enter that directory within MATLAB (use directory toolbar at top)
and then enter commands.


Usage
-----

A spot detection experiment can be processed using SID’s home console. To access
the home console:

   sidRun

This will display a GUI, from which all tasks can be processed – no more commands
are required. The home console allows creation of a set of new runs (or a jobset).

1. Creating new runs

Pressing ‘New Run’ will display a GUI to allow modification of spot detection
parameters. Click 'Select directory' to choose a directory to search for image
files. Select the images to analyse by highlighting them in the list, then either
click ‘Add’ to include the full image, or ‘Add + crop’ to allow cropping of one
or more ROIs. When selecting ROIs, click ‘Add ROI’, then double-click after drawing
each to save. Click ‘Finish’ when all ROIs have been selected for that image. After
ROI selection, configure channel and spot detection options. Select a channel in
which to detect spots, then select in which additional channels intensities should
be measured. The default spot detection options were tailored to detection of
kinetochores, so minimum and maximum spots may need to be changed on a case-by-case
basis. The value for intensity restriction is a value between 0 and 1, and should be
increased to include dimmer spots. Choose a name for the jobset. Finally, click
’Save' to allow further processing in the home console.

Clicking ‘Load Run’ will alternatively allow selection of a previously-created jobset.

Once a jobset has been created or loaded, its file path is shown below the ‘New Run’
and ‘Load Run’ buttons. The ‘Edit’ and ‘Run’ buttons then also become available. To
edit this jobset’s detection parameters, click ‘Edit’. To run spot detection for
this jobset, click ‘Run’.

After spot detection is complete, you will find a file named something like
‘siddetection001_exptname_imagefile.mat', where exptname is replaced with the name of
the jobset mat-file, and imagefile is replaced with the name of the image to which
this result is associated.

To run multiple jobsets at once, click ‘Multi-run’. This will display a GUI to allow
creation and loading of jobsets. Upon creation/loading, jobsets are listed below. If 
a jobset is already loaded into the home console, it will be listed here. To remove
a jobset from the list, highlight the given jobset and click ‘Remove’. Once all
jobsets for processing are listed, click ‘Run’. Click ‘Close’ once completed.


2. Manual filtering of data
 
Once the jobset loaded into the home console has been run, manual filtering of both
spots and cells can be done.

Clicking ‘Spot filtering’ will display a GUI showing a grid of all the spots
detected for a given image. Click on erroneous spots to deselect them, so that only
spots with green (red) borders are included (ignored) in analysis. Click ’Invert’ to
invert all green borders to red, and vice versa. Click ‘Next’ and ’Prev’ to move
between images, and click ‘Finish’ when manual filtering is complete.
N.B. No data is deleted. Ignored spots can be re-selected at a later time.

Clicking ‘Cell filtering’ will display a GUI showing a z-projection of each image
from the jobset. Dot plots will also be shown to demonstrate the measured intensities
in each channel for this image (red circles), relative to the data for the full
jobset (grey). Selecting either ‘Keep’ or ‘Discard’ will determine whether this cell
is included in analysis. This tool can be used to remove either cells visibly showing
an unwanted phenotype, or cells whose intensities are outliers of the full jobset
population. Click ‘Finish’ when cell filtering is complete.
N.B. No data is deleted. Ignored cells can be re-selected at a later time.

3. Full analysis

Once a number of jobsets have been run, analysis of the data can be done by clicking
‘Full analysis’. This displays a GUI to allow selection of jobsets for multiple
experimental conditions for comparison. Conditions are separated into tabs, where
they can be labelled. One condition can be selected for normalisation (labelled *),
so that all other conditions are plotted as a fraction of that condition. Select
multiple jobsets per condition by clicking ‘Find jobset(s)’, and highlight the
required jobsets. Select a control channel (one that is thought to be consistent
per condition), and additional channels to be analysed, providing labels for each.
Select a preferred plotting style. Click ‘Save directory:’ to select where to save
analysis, and provide a filename. Click ‘Run’ when complete. Figures can be forced
to remain open in MATLAB by ticking the checkbox.
Multiple files are saved in the save directory, including a .mat file, and .csv files
per condition, of intensity data. For each figure, an .eps file is saved. Figures show
background-corrected, cell-normalised (each spot normalised to its cell’s average
control channel intensity), and spot-normalised intensities (each spot normalised to
its own control channel intensity). Click ‘Close’ when finished’.


Bugs
----

Send bug or crash reports, and any feature requests, to c.smith.11@warwick.ac.uk.

Include:
  - Brief description of steps to reproduce error,
  - Copy of the error text,
  - Jobset mat-file (if available).

Images themselves will be useful but should be sent via e.g. Dropbox.


Credits
-------

SID evolved from KiT (Armond et al. 2016, Bioinformatics. 2016;32(12):1917-9).
Portions of the core spot detection code is adapted from KiT and renamed
appropriately.

C. Currie wrote the SID for Dummies document.

The SID package contains code from various other sources. See file headers to
identity sources and licenses.


MATLAB requirements
--------------------

MATLAB R2017a
MATLAB Image Processing Toolbox 9.1
MATLAB Statistics Toolbox 9.1