Skip to content

Introduction

Jump to bottom
Jan edited this page Mar 27, 2021 · 6 revisions

Overview

LAND is programmed in Matlab. To speed up processing some functions are implemented in C++. As input it takes single molecule coordinates provided in a .mat file. These coordinates can be obtained with any localization software that generates a list of coordinates from the raw SMLM image stack (overview of available software packages: http://bigwww.epfl.ch/smlm/software/index.html). However, there format might be different from LAND's input format so that a conversion might be necessary. For 2D raw data, ILE can be used to directly obtain the input format of LAND.

Input and Output Format

Input data should be in contained in a numeric n x 12 .mat file. Each row (n) should correspond to a single molecule signal. The columns should be ordered in the following way:

column 2/3/11 = x/y/z-position
column 4/5/12 = x/y/z-localization precision
column 9      = frame number

The remaining columns can be filled with zeros. If the data does not contain any localization precisions or z-positions (i.e. 2D data), these columns should be also filled with zeros.

Outputs are saved as .mat file. A detailed explanation of the design of the software is given in ??.

Requirements

To run LAND the following programs and toolboxes are required:

  • Matlab R2014b or newer
    • Statistics and Machine Learning Toolbox
    • Image Processing Toolbox
  • External dependencies:

A copy of multiWaitbar is included in this distribution, a separate download and installation is not necessary. For faster computation LAND’s algorithm utilize a k-d tree included in Matlab’s Statistics and Machine Learning Toolbox. Since it’s performance is quite low we recommend to install Andrea Tagliasachhi’s kdtree.

Hardware: Beside the minimum system requirements to run Matlab, a minimum of 8 GByte RAM are recommended.

Installation

  • download the software package from https://github.com/Jan-NM/LAND/releases
  • extract LAND-master.zip
  • copy the generated LAND-master directory into your local MATLAB working directory
  • to use LAND, right click on LAND-master in MATLAB's current folder panel, go to Add to Path and click on Selected Folders and Subfolders

LAND can be used via the command window or by opening a user interface. To open the user interface type startClusterAnalysis in the command window.

Recommended Installation: ataiya/kdtree

  • configure a MEX environment by downloading and installing a Matlab-supported C++ compiler
  • open "...\LAND-master\utilities\ataiya_kdtree..." in Matlab's current folder panel
  • execute the following commands in MATLAB's command window to setup the mex environment
    mex -setup C++
    mex kdtree_build.cpp
    mex kdtree_ball_query.cpp
    mex kdtree_delete.cpp

Quick Start Guide

LAND can be used via an user interface or directly via the command line. This sections serves as a quick start guide for both of them. We recommend to use the user interface for batch processing and the command line for data exploration and parameter optimization. A detailed description is shown in ??.

Input Format

LAND can read .mat files. The files should be formatted column-wise i.e. each row should represent a localization signal. The data should contain at minimum the 2D or 3D coordinates of the localization signals. Localization precision and frame numbers are optional. A default column order can be entered. Internally, LAND uses the following format:

  • x-position (column 1)
  • y-position (column 2)
  • z-position (column 3)
  • x-localization precision (column 4)
  • y-localization precision (column 5)
  • z-localization precision (column 6)
  • frame number (column 7)

By default (without any file conversion) LAND can read .mat files that are provided in the Orte format:

  • x-position (column 2)
  • y-position (column 3)
  • z-position (column 11)
  • x-localization precision (column 4)
  • y-localization precision (column 5)
  • z-localization precision (column 12)
  • frame number (column 9)

User Interface

To start the user interface, execute startClusterAnalysis in the command line. The user interface will pop up. In the file settings panel select the location of your files. The files should be in .mat format and should contain at minimum the column-wise 2D or 3D coordinates of the single molecules. Optionally the input files may contain the corresponding localization precision and a frame ID. Next, click in the File Selector list on the files you would like to evaluate. Set up your evaluation settings i.e. select data dimension, random data evaluation, the algorithm and its parameters. Finally, press the Start button. When the calculation is finished the data will be saved as .mat file in a folder denoted in the Output Directory panel. To load the files into Matlab, ensure that LAND is added to the path and double-click on the .mat file.

Command Line

To use LAND from the command line, load a .mat file in the Orte format into Matlab. Type

    variableName = ClusterAnalysis(localizationFile, additionalArguments);

into the command line. The first argument localizationFile is mandatory. Cluster- Analysis can take up to 5 optional input arguments:

  1. argument: name or number of the sample (default: ’001’)
  2. argument: dimension (default: 2)
  3. argument: algorithm to calculate the local density (default: ’averageDensity’)
  4. argument: additional parameter for 3. argument (default: [])
  5. argument: random data with complete spatial randomness (default: true)

For example, if your localization file is called testExperiment in the workspace folder, type

cell01 = ClusterAnalysis(testExperiment);

into the command window. This will prepare everything with default settings for further evaluation. An object with the name cell01 will appear in the workspace. Double-click on the name will open the object and its associated settings. To execute one of the evaluation routines type

variableName.functionName(parameters);

For example

cell01.DBSCAN(30, 6, 0, 1000, 0);

will execute DBSCAN on the dataset with radius = 30 nm, minimum number of points = 6, random data=false, maximum diameter of clusters = 1000 nm, show plot =false.

Clone this wiki locally