usage:feature_extraction [FAST]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== The Feature Extraction module ======

{{logos:Features.png?nolink&80 }} In the next module, feature information (such as object shape and colour) are extracted from the input images using the segmentations generated in the previous module. In many cases, these features are both the data that you want to track over time and the data used to perform that tracking.

Upon clicking the **Features** button on the home panel, the feature extraction window should appear:

{{ :usage:featureextractionannotated.png?400 |}}
===== Choosing features to extract =====

You can choose the features that you want FAST to quantify by checking or unchecking each box. *Centroid* indicates object position, and in almost all cases should be selected.

To choose channel intensity features to extract, push the **Channel Selection** button. This will bring up a new selection dialog:

{{ :usage:channelselection.png?300px }}

In this dialog, 'mean' indicates the average pixel value within the object's mask, while 'std' indicates the standard deviation of pixel values within this mask. This latter feature can be useful for detecting the presence of fluorescent foci within your objects.

Once you have chosen the channels and features you want to include from this dialog, click **Make selection** to finalise your choice.

<note tip>

Don't select features if you don't need them! This will reduce processing times and space requirements.

</note>

<note tip>

If you want to measure a feature that you can't see here, you may be able to write a new function to extract it using FAST's integrated custom feature extraction system. [[usage:advanced_usage#custom_feature_extraction|Please see the documentation on this topic to see whether this could work for you.]]

</note>
===== The morphology algorithms =====

FAST provides the option to use one of two algorithms for determining the morphological properties of objects:

=== Ellipse fitting ===

With the **ellipse fitting** option selected, an algorithm will be used that attempts to fit an ellipse to the outer boundary of your objects using a least-squares method. The major and minor semi-axes of this ellipse are then used as the length and width of the object, while the orientation of the ellipse is used as the object's orientation.

=== Perimeter distances ===

The **perimeter distance** algorithm simply calculates the distance between each pair of points on the perimeter. The length of the object is then estimated as the greatest of these values, while the width is estimated as the smallest (for all pairs of points at least a quarter of the total distance around the object). The angle of the 'length line' (the line joining the two points the furthest away from each other) is then used as the orientation of the object.

{{ :usage:fittingalgorithms.png?nolink&600 |}}

<note tip>

Ellipse fitting is generally more robust than perimeter distances, as it makes use of the entire cell outline (rather than the points that are the greatest outliers). However, it can produce inaccurate results if your objects are not approximately elliptical in shape. For example, it tends to overestimate the length of long, skinny objects. In these cases, the perimeter distance algorithm should be used.

</note>

===== Outputs =====

Once feature extraction has finished, the file 'cellFeatures.mat' will be saved in the root directory. This contains the following data:

  * **featSettings:** The settings chosen in the feature extraction GUI used to extract features.
  * **maxT:** The maximum timepoint in the dataset (retained as a legacy variable).
  * **trackableData:** The feature data associated with each object at each timepoint.

The trackableData structure forms the basis of the feature tracking module, and can be used by itself for [[extra:faqs#what_is_image_cytometry_can_it_be_performed_by_fast|image cytometry]]. It is organised as shown in the below figure:

{{ :usage:trackabledatadepiction.png?nolink&700 |}}

Values stored in identically indexed locations in the different fields of trackableData belong to the same object. For example, the width of object 10 at time 20 is stored in 

  trackableData.Width{20}(10)

while its orientation is stored in 

  trackableData.Orientation{20}(10)
  
For fields that contain multi-dimensional arrays rather than vectors (such as 'Centroid'), the object index corresponds to the row of the array. For example, the $x,y$-coordinates of the above object are stored in

  trackableData.Centroid{20}(10,:)

All geometrical measurements (length, width, area, position and orientation) are stored in physical units, while fluorescence-associated measurements (channel mean and channel standard deviation) are stored in arbitrary units.

===== Video demonstration =====

{{ youtube>h6kEowehxMo?large }}