Background ratio (#159)

* fix download_tiles_tms function argument error

* docs update for background ratio

* background ratio for multi class classification

* fix docs

* undo older tms commit

* fix background ratio in example config

* move limit into if statement where it's used

* update parameters docs for background ratio

Author: Martha Morrissey

config.example.json

@@ -7,6 +7,6 @@
     { "name": "Buildings", "filter": ["has", "building"] }
   ],
   "imagery": "http://a.tiles.mapbox.com/v4/mapbox.satellite/{z}/{x}/{y}.jpg?access_token=ACCESS_TOKEN",
-  "background_ratio": 1,
+  "background_ratio": 0,
   "ml_type": "classification"
 }

docs/index.rst

@@ -71,7 +71,7 @@ Retiles the OSM data to the desired zoom level, creates label data (``labels.npz
 
 Accepts one additional flag:
 
-	``-s`` or ``--sparse``: boolean 
+	``-s`` or ``--sparse``: boolean
 		Specifies if features in the class of interest are sparse. If ``True``, only save labels for up to ``n`` background tiles, where ``n`` is equal to ``background_ratio`` times the number of tiles with a class label. Defaults to ``False``.
 
 .. code-block:: bash
@@ -103,6 +103,8 @@ CLI Step 4: images
 ^^^^^^^^^^^^^^^^^^
 
 Downloads all imagery tiles needed to create the training data. Requires the ``labels.npz`` file from the ``label-maker labels`` step.
+The number of background tiles added depends on the `background_ratio` parameter specified in the `config.json` file.
+A background_ratio of 0 will return no background tiles. 
 
 .. code-block:: bash
 

docs/parameters.rst

@@ -38,7 +38,7 @@ Here is the full list of configuration parameters you can specify in a ``config.
 	Optional parameter to specify a username and password for restricted WMS services. For example, ``['my_username', 'my_password']``.
 
 **background_ratio**: float
-	Specify how many background (or "negative") training examples to create when there is only one class specified with the ``classes`` parameter. Label Maker will generate ``background_ratio`` times the number of images matching the one class.
+	Specify how many background (or "negative") training examples to create. Label Maker will generate ``background_ratio`` times the number of images matching the total number class tiles.
 
 **ml_type**: string
 	One of ``'classification'``, ``'object-detection'``, or ``'segmentation'``. This defines the output format for the final label numpy arrays (``y_train`` and ``y_test``).

label_maker/images.py

@@ -55,11 +55,11 @@ def class_test(value):
         return None
     class_tiles = [tile for tile in tiles.files if class_test(tiles[tile])]
 
-    # for classification problems with a single class, we also get background
+    # for classification problems, we also get background
     # tiles up to len(class_tiles) * config.get('background_ratio')
     background_tiles = []
-    limit = len(class_tiles) * background_ratio
-    if ml_type == 'classification' and len(classes) == 1:
+    if ml_type == 'classification':
+        limit = len(class_tiles) * background_ratio
         background_tiles_full = [tile for tile in tiles.files if tile not in class_tiles]
         shuffle(background_tiles_full)
         background_tiles = background_tiles_full[:limit]