Added cell tracking functionality

.coveragerc

@@ -18,3 +18,4 @@ omit =
     deepcell/utils/testing_utils.py
     deepcell/datasets/*
     deepcell/notebooks/*
+    deepcell/tracking.py

README.md

@@ -7,10 +7,16 @@ DeepCell is neural network library for single cell analysis, written in Python a
 
 DeepCell aids in biological analysis by automatically segmenting and classifying cells in optical microscopy images.  The framework processes raw images and uniquely annotates each cell in the image.  These annotations can be used to quantify a variety of cellular properties.
 
-Read the documentaiton at [deepcell.readthedocs.io](https://deepcell.readthedocs.io)
+Read the documentation at [deepcell.readthedocs.io](https://deepcell.readthedocs.io)
 
 For more information on deploying DeepCell in the cloud [refer to the DeepCell Kiosk documentation](https://deepcell-kiosk.readthedocs.io)
 
+## Examples
+
+Raw Image                  |  Segmented and Tracked
+:-------------------------:|:-------------------------:
+![](/docs/images/raw.gif)  |  ![](/docs/images/tracked.gif)  
+
 ## Getting Started
 
 The fastest way to get started with DeepCell is to run the latest docker image:
@@ -41,6 +47,10 @@ This will start a jupyter session, with several example notebooks detailing vari
 
 * [3D Watershed - Sample Based.ipynb](scripts/watershed/Watershed%20Transform%203D%20Sample%20Based.ipynb)
 
+### Cell Tracking in Live Cell Imaging
+
+* [Tracking Example.ipynb](scripts/tracking/Tracking%20Example.ipynb)
+
 ## DeepCell for Developers
 
 DeepCell uses `nvidia-docker` and `tensorflow` to enable GPU processing.  

deepcell/datasets/__init__.py

@@ -29,6 +29,7 @@
 from __future__ import division
 from __future__ import print_function
 
+from deepcell.datasets import tracked
 from deepcell.datasets import hek293
 from deepcell.datasets import hela_s3
 from deepcell.datasets import mousebrain

deepcell/datasets/tracked/__init__.py

@@ -0,0 +1,38 @@
+# Copyright 2016-2019 The Van Valen Lab at the California Institute of
+# Technology (Caltech), with support from the Paul Allen Family Foundation,
+# Google, & National Institutes of Health (NIH) under Grant U24CA224309-01.
+# All rights reserved.
+#
+# Licensed under a modified Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.github.com/vanvalenlab/deepcell-tf/LICENSE
+#
+# The Work provided may be used for non-commercial academic purposes only.
+# For any other use of the Work, including commercial use, please contact:
+# vanvalenlab@gmail.com
+#
+# Neither the name of Caltech nor the names of its contributors may be used
+# to endorse or promote products derived from this software without specific
+# prior written permission.
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ==============================================================================
+"""Builtin Datasets"""
+
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import print_function
+
+from deepcell.datasets.tracked import nih_3t3
+from deepcell.datasets.tracked import hela_s3
+from deepcell.datasets.tracked import hek293
+
+del absolute_import
+del division
+del print_function

deepcell/datasets/tracked/hek293.py

@@ -0,0 +1,71 @@
+# Copyright 2016-2019 The Van Valen Lab at the California Institute of
+# Technology (Caltech), with support from the Paul Allen Family Foundation,
+# Google, & National Institutes of Health (NIH) under Grant U24CA224309-01.
+# All rights reserved.
+#
+# Licensed under a modified Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.github.com/vanvalenlab/deepcell-tf/LICENSE
+#
+# The Work provided may be used for non-commercial academic purposes only.
+# For any other use of the Work, including commercial use, please contact:
+# vanvalenlab@gmail.com
+#
+# Neither the name of Caltech nor the names of its contributors may be used
+# to endorse or promote products derived from this software without specific
+# prior written permission.
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ==============================================================================
+"""Tracked HEK293 Nuclear Dataset with lineage data for each batch."""
+
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import print_function
+
+import os
+
+try:
+    from tensorflow.python.keras.utils.data_utils import get_file
+except ImportError:  # tf v1.9 moves conv_utils from _impl to keras.utils
+    from tensorflow.python.keras._impl.keras.utils.data_utils import get_file
+
+from deepcell.utils.data_utils import get_data
+
+
+def load_tracked_data(path='HEK293.trks', test_size=.2, seed=0):
+    """Loads the tracked HEK293 dataset.
+
+    # Args:
+        path: path where to cache the dataset locally
+            (relative to ~/.keras/datasets).
+        test_size: fraction of data to reserve as test data
+        seed: the seed for randomly shuffling the dataset
+
+    Returns:
+        Tuple of Numpy arrays: `(x_train, y_train), (x_test, y_test)`.
+    """
+    basepath = os.path.expanduser(os.path.join('~', '.keras', 'datasets'))
+    prefix = path.split(os.path.sep)[:-1]
+    data_dir = os.path.join(basepath, *prefix) if prefix else basepath
+    if not os.path.exists(data_dir):
+        os.makedirs(data_dir)
+    elif not os.path.isdir(data_dir):
+        raise IOError('{} exists but is not a directory'.format(data_dir))
+
+    path = get_file(path,
+                    origin='https://deepcell-data.s3.amazonaws.com/tracked/HEK293.trks',
+                    file_hash='d19e0fe144633a08d41cf6695e11f72b')
+
+    train_dict, test_dict = get_data(path, mode='siamese_daughters',
+                                    test_size=test_size, seed=seed)
+
+    x_train, y_train = train_dict['X'], train_dict['y']
+    x_test, y_test = test_dict['X'], test_dict['y']
+    return (x_train, y_train), (x_test, y_test)

deepcell/datasets/tracked/hela_s3.py

@@ -0,0 +1,71 @@
+# Copyright 2016-2019 The Van Valen Lab at the California Institute of
+# Technology (Caltech), with support from the Paul Allen Family Foundation,
+# Google, & National Institutes of Health (NIH) under Grant U24CA224309-01.
+# All rights reserved.
+#
+# Licensed under a modified Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.github.com/vanvalenlab/deepcell-tf/LICENSE
+#
+# The Work provided may be used for non-commercial academic purposes only.
+# For any other use of the Work, including commercial use, please contact:
+# vanvalenlab@gmail.com
+#
+# Neither the name of Caltech nor the names of its contributors may be used
+# to endorse or promote products derived from this software without specific
+# prior written permission.
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ==============================================================================
+"""Tracked HeLa S3 Nuclear Dataset with lineage data for each batch."""
+
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import print_function
+
+import os
+
+try:
+    from tensorflow.python.keras.utils.data_utils import get_file
+except ImportError:  # tf v1.9 moves conv_utils from _impl to keras.utils
+    from tensorflow.python.keras._impl.keras.utils.data_utils import get_file
+
+from deepcell.utils.data_utils import get_data
+
+
+def load_tracked_data(path='HeLa_S3.trks', test_size=.2, seed=0):
+    """Loads the tracked HeLa-S3 dataset.
+
+    # Args:
+        path: path where to cache the dataset locally
+            (relative to ~/.keras/datasets).
+        test_size: fraction of data to reserve as test data
+        seed: the seed for randomly shuffling the dataset
+
+    Returns:
+        Tuple of Numpy arrays: `(x_train, y_train), (x_test, y_test)`.
+    """
+    basepath = os.path.expanduser(os.path.join('~', '.keras', 'datasets'))
+    prefix = path.split(os.path.sep)[:-1]
+    data_dir = os.path.join(basepath, *prefix) if prefix else basepath
+    if not os.path.exists(data_dir):
+        os.makedirs(data_dir)
+    elif not os.path.isdir(data_dir):
+        raise IOError('{} exists but is not a directory'.format(data_dir))
+
+    path = get_file(path,
+                    origin='https://deepcell-data.s3.amazonaws.com/tracked/HeLa_S3.trks',
+                    file_hash='590ee37d3c703cfe029a2e60c9dc777b')
+
+    train_dict, test_dict = get_data(path, mode='siamese_daughters',
+                                    test_size=test_size, seed=seed)
+
+    x_train, y_train = train_dict['X'], train_dict['y']
+    x_test, y_test = test_dict['X'], test_dict['y']
+    return (x_train, y_train), (x_test, y_test)

deepcell/datasets/tracked/nih_3t3.py

@@ -0,0 +1,71 @@
+# Copyright 2016-2019 The Van Valen Lab at the California Institute of
+# Technology (Caltech), with support from the Paul Allen Family Foundation,
+# Google, & National Institutes of Health (NIH) under Grant U24CA224309-01.
+# All rights reserved.
+#
+# Licensed under a modified Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.github.com/vanvalenlab/deepcell-tf/LICENSE
+#
+# The Work provided may be used for non-commercial academic purposes only.
+# For any other use of the Work, including commercial use, please contact:
+# vanvalenlab@gmail.com
+#
+# Neither the name of Caltech nor the names of its contributors may be used
+# to endorse or promote products derived from this software without specific
+# prior written permission.
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ==============================================================================
+"""Tracked 3T3 Nuclear Dataset from the NIH with lineage data for each batch."""
+
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import print_function
+
+import os
+
+try:
+    from tensorflow.python.keras.utils.data_utils import get_file
+except ImportError:  # tf v1.9 moves conv_utils from _impl to keras.utils
+    from tensorflow.python.keras._impl.keras.utils.data_utils import get_file
+
+from deepcell.utils.data_utils import get_data
+
+
+def load_tracked_data(path='3T3_NIH.trks', test_size=.2, seed=0):
+    """Loads the tracked 3T3-NIH dataset.
+
+    # Args:
+        path: path where to cache the dataset locally
+            (relative to ~/.keras/datasets).
+        test_size: fraction of data to reserve as test data
+        seed: the seed for randomly shuffling the dataset
+
+    Returns:
+        Tuple of Numpy arrays: `(x_train, y_train), (x_test, y_test)`.
+    """
+    basepath = os.path.expanduser(os.path.join('~', '.keras', 'datasets'))
+    prefix = path.split(os.path.sep)[:-1]
+    data_dir = os.path.join(basepath, *prefix) if prefix else basepath
+    if not os.path.exists(data_dir):
+        os.makedirs(data_dir)
+    elif not os.path.isdir(data_dir):
+        raise IOError('{} exists but is not a directory'.format(data_dir))
+
+    path = get_file(path,
+                    origin='https://deepcell-data.s3.amazonaws.com/tracked/3T3_NIH.trks',
+                    file_hash='0d90ad370e1cb9655727065ada3ded65')
+
+    train_dict, test_dict = get_data(path, mode='siamese_daughters',
+                                    test_size=test_size, seed=seed)
+
+    x_train, y_train = train_dict['X'], train_dict['y']
+    x_test, y_test = test_dict['X'], test_dict['y']
+    return (x_train, y_train), (x_test, y_test)