change readthedocs theme and update the landing page with new links (#…

…480)

* change readthedocs theme and update the landing page with new links

---------

Co-authored-by: henry senyondo <[email protected]>

HISTORY.rst

@@ -1,19 +1,19 @@
-=============================
+=====================
 DeepForest Change Log
-=============================
+=====================
 
-# 1.1.3
+**1.1.3**
 Add box coordinates to evaluate results frame.
 
-# 1.1.2
+**1.1.2**
 
 If there was more than one class, the precision in the class_recall.csv was computed incorrectly.
 
-# 1.1.1
+**1.1.1**
 
 Update to project_boxes to include an output for predict_tile and predict_image, the function was split into two. annotations_to_shapefile reverses shapefile_to_annotations. Thanks to @sdtaylor for this contribution.
 
-# 1.1.0
+**1.1.0**
 
 1.
 Empty frames are now allowed by passing annotations with 0's for all coords. A single row for each blank image.
@@ -23,16 +23,16 @@ image_path, 0,0,0,0, "Tree"
 2.
 A check_release function was implemented to reduce github rate limit issues. on use_release(), the local model will be used if check_release = False
 
-# 1.0.9
+**1.0.9**
 
 Minor update to improve windows users default dtype, thanks to @ElliotSalisbury
 
-# 1.0.0
+**1.0.0**
 
 Major update to replace tensorflow backend with pytorch. 
 
-#0.1.30
+**0.1.30**
 Bug fixes to allow learning rate monitoring and decay on val_classification_loss
 
-#0.1.34
+**0.1.34**
 Profiled the dataset and evaluation code for performance. Evaluation should be much faster now.

deepforest/dataset.py

@@ -58,10 +58,7 @@ def __init__(self,
                 on a sample.
             label_dict: a dictionary where keys are labels from the csv column and values are numeric labels "Tree" -> 0
         Returns:
-            If train:
-                path, image, targets
-            else:
-                image
+            If train, path, image, targets else image
         """
         self.annotations = pd.read_csv(csv_file)
         self.root_dir = root_dir

dev_requirements.txt

@@ -22,6 +22,7 @@ docutils<0.18
 slidingwindow
 opencv-python
 sphinx_rtd_theme
+furo
 sphinx_markdown_tables
 tqdm
 twine

docs/ConfigurationFile.md

@@ -44,19 +44,18 @@ validation:
 ## Dataloaders
 
 ### workers
-Number of workers to perform asynchronous data generation during model training. Corresponds to num_workers in pytorch base 
-class https://pytorch.org/docs/stable/data.html. To turn off asynchronous data generation set workers = 0.
+
+Number of workers to perform asynchronous data generation during model training. Corresponds to num_workers in pytorch [base class](https://pytorch.org/docs/stable/data.html). To turn off asynchronous data generation set workers = 0.
 
 ### devices
-The number of cpus/gpus to use during model training. Deepforest has been tested on up to 8 gpu and follows a pytorch lightning module, which means it can inherit any of the scaling functionality from this library, including TPU support.
-https://pytorch-lightning.readthedocs.io/en/stable/advanced/multi_gpu.html?highlight=multi%20gpu
+
+The number of cpus/gpus to use during model training. Deepforest has been tested on up to 8 gpu and follows a [pytorch lightning module](https://pytorch-lightning.readthedocs.io/en/stable/advanced/multi_gpu.html?highlight=multi%20gpu), which means it can inherit any of the scaling functionality from this library, including TPU support.
 
 ### accelerator
-Most commonly, 'cpu', 'gpu' or 'tpu' as well as other options listed:
 
-https://pytorch-lightning.readthedocs.io/en/1.4.0/advanced/multi_gpu.html.
+Most commonly, `cpu`, `gpu` or `tpu` as well as other [options](https://pytorch-lightning.readthedocs.io/en/1.4.0/advanced/multi_gpu.html) listed:
 
-If 'gpu', it can be helpful to specify the data parallelization strategy. This can be done using the 'strategy' arg in main.create_trainer()
+If `gpu`, it can be helpful to specify the data parallelization strategy. This can be done using the `strategy` arg in `main.create_trainer()`
 
 ```
 model.create_trainer(logger=comet_logger, strategy="ddp")
@@ -65,12 +64,12 @@ model.create_trainer(logger=comet_logger, strategy="ddp")
 This is passed to the pytorch-lightning trainer, documented in the link above for multi-gpu training.
 
 ### batch_size
+
 Number of images per batch during training. GPU memory limits this usually between 5-10
 
 ### nms_thresh
 
-Non-max suppression threshold. The higher scoring predicted box is kept when predictions overlap by greater than nms_thresh. For details see
-https://pytorch.org/vision/stable/ops.html#torchvision.ops.nms
+Non-max suppression threshold. The higher scoring predicted box is kept when predictions overlap by greater than nms_thresh. For details see [torchvision docs](https://pytorch.org/vision/stable/ops.html#torchvision.ops.nms)
 
 ### score_thresh
 
@@ -87,8 +86,8 @@ This will be updated when you can predict_tile, predict_image, predict_file, or
 
 ### csv_file
 
-Path to csv_file for training annotations. Annotations are .csv files with headers image_path, xmin, ymin, xmax, ymax, label. image_path are relative to the root_dir. 
-For example this file should have entries like myimage.tif not /path/to/myimage.tif
+Path to csv_file for training annotations. Annotations are `.csv` files with headers `image_path, xmin, ymin, xmax, ymax, label`. image_path are relative to the root_dir. 
+For example this file should have entries like `myimage.tif` not `/path/to/myimage.tif`
 
 ### root_dir
 
@@ -122,13 +121,12 @@ The number of times to run a full pass of the dataloader during model training.
 
 ### fast_dev_run
 
-A useful pytorch lightning flag that will run a debug run to test inputs. See 
-
-[pytorch lightning docs](https://pytorch-lightning.readthedocs.io/en/latest/common/trainer.html?highlight=fast_dev_run#fast-dev-run)
+A useful pytorch lightning flag that will run a debug run to test inputs. See [pytorch lightning docs](https://pytorch-lightning.readthedocs.io/en/latest/common/trainer.html?highlight=fast_dev_run#fast-dev-run)
 
 ### preload_images
 
-For large training runs, the time spent reading each image and passing it to the GPU can be a significant performance bottleneck. 
+For large training runs, the time spent reading each image and passing it to the GPU can be a significant performance bottleneck.
+
 If the training dataset is small enough to fit into GPU memory, pinning the entire dataset to memory before training will increase training speed. Warning, if the pinned memory is too large, the GPU will overflow/core dump and training will crash.
 
 ## Validation
@@ -137,8 +135,8 @@ Optional validation dataloader to run during training.
 
 ### csv_file
 
-Path to csv_file for validation annotations. Annotations are .csv files with headers image_path, xmin, ymin, xmax, ymax, label. image_path are relative to the root_dir. 
-For example this file should have entries like myimage.tif not /path/to/myimage.tif
+Path to csv_file for validation annotations. Annotations are `.csv` files with headers `image_path, xmin, ymin, xmax, ymax, label`. image_path are relative to the root_dir. 
+For example this file should have entries like `myimage.tif` not `/path/to/myimage.tif`
 
 ### root_dir
 

docs/FAQ.md

@@ -1,6 +1,6 @@
 # FAQ
 
-## Exception: RuntimeError: The size of tensor a (4) must match the size of tensor b (3) at non-singleton dimension 0
+**Exception: RuntimeError: The size of tensor a (4) must match the size of tensor b (3) at non-singleton dimension 0**
 
 This error is usually caused by the user accidentily adding a 4 channel image to a 3 channel RGB model. Sometimes .png or .jpeg images are saved with a 'alpha' channel controlling their transparency. This needs to be removed.
 
@@ -19,7 +19,7 @@ image = Image.fromarray(numpy_image)
 image.save(name)
 ```
 
-## How do I make training faster?
+**How do I make training faster?**
 
 While it is impossible to anticipate the setup for all users, there are a few guidelines. First, a GPU-enabled processor is key. Training on a CPU can be done, but it will take much longer (100x) and is probably only done if needed. Using Google Colab can be beneficial but prone to errors. Once on the GPU, the configuration includes a "workers" argument. This connects to PyTorch's dataloader. As the number of workers increases, data is fed to the GPU in parallel. Increase the worker argument slowly, we have found that the optimal number of workers varies by system.
 
@@ -53,7 +53,7 @@ m = main.deepforest(num_classes = 6, label_dict = {"a":0,"b":1,"c":2,"d":3,"e":4
 m.load_state_dict(ckpt["state_dict"])
 ```
 
-## Weakly referenced objects
+**Weakly referenced objects**
 
 On some devices and systems we have found an error referencing the model.trainer object that was created in m.create_trainer(). 
 We welcome a reproducible issue to address this error as it appears highly variable and relates to upstream issues. It appears more common on google colab and github actions.
@@ -71,7 +71,7 @@ for tile in tiles_to_predict:
 ```
 Usually creating this object does not cost too much computational time.
 
-### Saving
+**Saving**
 
 We have rarely heard that this appears on save:
 ```
@@ -92,7 +92,7 @@ model = main.deepforest()
 model.model.load_state_dict(torch.load(model_path))
 ```
 
-### Training
+**Training**
 
 We have heard that this error can appear when trying to deep copy the pytorch lighnting module. The trainer object is not pickleable.
 For example, on multi-gpu enviroments when trying to scale the deepforest model the entire module is copied leading to this error.
@@ -126,14 +126,14 @@ The added benefits of this is more control over the trainer object.
 The downside is that it doesn't align with the .config pattern where a user now has to look into the config to create the trainer. 
 We are open to changing this to be the default pattern in the future and welcome input from users.
 
-## How do I reduce double counting in overlapping images?
+**How do I reduce double counting in overlapping images?**
 
 If you have geospatial data for each image this is straightforward. 
 Here is a colab link example to project the predictions from image coordinates into geospatial coordinates and then apply non-max suppression.
 
 [https://colab.research.google.com/drive/1T4HC7i5zqe_9AX0pEZSSSzo6BFPFTgFK?usp=sharing](https://colab.research.google.com/drive/1T4HC7i5zqe_9AX0pEZSSSzo6BFPFTgFK?usp=sharing)
 
-## Issues
+**Issues**
 
 We welcome feedback on both the python package as well as the algorithm performance. Please submit detailed issues to the github repo.
 

docs/better.md

@@ -1,10 +1,13 @@
 # How do I make the predictions better?
 
-Give the enormous array of forest types and image acquisition environment, it is unlikely that your image will be perfectly predicted by the prebuilt model. Here are some tips to improve predictions
+Given the enormous array of forest types and image acquisition environments, it is unlikely that your image will be perfectly predicted by the prebuilt model. Below are some tips and some general guidelines to improve predictions.
+
+Get suggestions on how to improve a model by using the [discussion board](https://github.com/weecology/DeepForest/discussions). Please be aware that only feature requests or bug reports should be posted on the [issues' page](https://github.com/weecology/DeepForest/issues).
+
 
 ## Check patch size
 
-The prebuilt model was trained on 10cm data at 400px crops. The model is sensitive to predicting to new image resolutions that differ. We have found that increasing the patch size works better on higher quality data. For example, here is a drone collected data at the standard 400px
+The prebuilt model was trained on 10cm data at 400px crops. The model is sensitive to predicting new image resolutions that differ. We have found that increasing the patch size works better on higher quality data. For example, here is a drone collected data at the standard 400px.
 
 ```python
 tile = model.predict_tile("/Users/ben/Desktop/test.jpg",return_plot=True,patch_overlap=0,iou_threshold=0.05,patch_size=400)
@@ -25,18 +28,16 @@ improved.
 For more on this theme see:
 https://github.com/weecology/DeepForest_demos/blob/master/street_tree/StreetTrees.ipynb
 
-The cross-resolution prediction remains an open area of debate and should be explored carefully. For images similar to the 10cm data used to train the release model, keeping a 40m focal view is likely a good choice. For coarser resolutions, the answer will be best found through trial and error, but is almost certainly a wider field of view. This is likely less of an issue if you retrain the model based on data at the desired resolution, rather than directly use the release model to predict trees at novel resolutions.
+The cross-resolution prediction remains an open area of debate and should be explored carefully. For images similar to the 10cm data used to train the release model, keeping a 40m focal view is likely a good choice. For coarser resolutions, the answer will be best found through trial and error, but it is almost certainly a wider field of view. This is likely less of an issue if you retrain the model based on data at the desired resolution rather than directly using the release model to predict trees at novel resolutions.
 
 ## IoU threshold
 
-Object detection models have no inherent logic about overlapping bounding box proposals. For tree crown detection, we expect trees in dense forests to have some overlap, but not be completely intertwined. We therefore apply a postprocessing filter called ‘non-max-suppression’, which is a common approach in the broader computer vision literature. This routine starts with the boxes with the highest confidence scores and removes any overlapping boxes greater than the intersection-over-union threshold (IoU). Intersection-over-union is the most common object detection metric, defined as the area of intersection between two boxes divided by the area of union. If users find that there is too much overlap among boxes, increasing the IoU will return fewer boxes. To in-crease the number of overlapping boxes, reduce the IoU threshold.
+Object detection models have no inherent logic about overlapping bounding box proposals. For tree crown detection, we expect trees in dense forests to have some overlap but not be completely intertwined. We therefore apply a postprocessing filter called ‘non-max-suppression’, which is a common approach in the broader computer vision literature. This routine starts with the boxes with the highest confidence scores and removes any overlapping boxes greater than the intersection-over-union threshold (IoU). Intersection-over-union is the most common object detection metric, defined as the area of intersection between two boxes divided by the area of union. If users find that there is too much overlap among boxes, increasing the IoU will return fewer boxes. To increase the number of overlapping boxes, reduce the IoU threshold.
 
 ## Annotate local training data
 
-Ultimately, training a proper model with local data is the best chance at getting good performance. See DeepForest.train()
+Ultimately, training a proper model with local data is the best chance at getting good performance. See `DeepForest.train()`
 
 ## Issues
 
-We welcome feedback on both the python package as well as the algorithm performance. Please submit detailed issues to the github repo.
-
-[https://github.com/weecology/DeepForest/issues](https://github.com/weecology/DeepForest/issues)
+We welcome feedback on both the python package as well as the algorithm performance. Please submit detailed issues to the Github repo [issues' page](https://github.com/weecology/DeepForest/issues).

docs/conf.py

@@ -59,11 +59,11 @@
     'sphinx.ext.napoleon',
     'sphinx.ext.todo',
     'sphinx.ext.viewcode',
-    'sphinx_markdown_tables',
-]
+    'sphinx_markdown_tables']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
+
 # The master toctree document.
 master_doc = 'index'
 
@@ -72,20 +72,12 @@
 copyright = u"2019, Ben Weinstein"
 author = u"Ben Weinstein"
 version = u"__version__ = '__version__ = '__version__ = '1.2.7'''"
-language = None
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '**.ipynb_checkpoints']
 pygments_style = 'sphinx'
 todo_include_todos = False
 
 # -- Options for HTML output -------------------------------------------
-
-on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
-if not on_rtd:  # only import and set the theme if we're building docs locally
-    import sphinx_rtd_theme
-
-    html_theme = 'sphinx_rtd_theme'
-    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] + ["../.."]
-
+html_theme = 'furo'
 html_static_path = []
 
 # -- Options for HTMLHelp output ---------------------------------------