Welcome to Masterful: The Training Platform for Computer Vision Models
======================================================================

Intro
-----

Masterful is the training platform for computer vision models. 

Masterful is designed with three objectives:

1. **Accuracy**, achieved via comprehensive regularization and semi-supervised learning (e.g. learning from raw, unlabeled images).
2. **Developer Productivity**, achieved via high-speed metalearning. It's a waste of developer time to guess-and-check of hyperparameters or do long runs with a black box optimizer. 
3. **Speed**, or minimizing GPU-hours and wall clock time, achieved via high-speed metalearning to discover ideal optimization hyperparameters. 

.. image:: _static/arch.png

Users define the two inputs to Masterful: 

* **Data**

* **Model architecture**



Masterful processes these inputs through four modules: 

* **Regularization**, which improves accuracy from the existing information.

* **Semi-supervised learning (SSL)**, which improves accuracy by learning from the information in raw, unlabeled images.

* **Optimization**, which minimizes GPU-hours and wall-clock time of training.

* **Meta-learning**, which minimizes developer "guessing and checking" and eliminates black box optimization. 


Masterful returns a **trained model** (e.g. model weights).

Masterful supports most types of classification, detection, and segmentation.

Currently available for Tensorflow2, with PyTorch support coming soon. 

Getting Started
---------------

Install with ``pip install --upgrade pip; pip install masterful``. 

For detailed installation instructions, visit the :doc:`tutorials/tutorial_installation`.

Then execute your first training run with Masterful with the :doc:`notebooks/tutorial_quickstart`. 

Finally, visualize Masterful's performance with the :doc:`tutorials/tutorial_frontend`.

.. raw:: html

    <iframe width="560" height="315" src="https://www.youtube.com/embed/lr5reA0bPF0" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

Design
------

To learn about the concepts within the Masterful CV Platform, visit the `technical report preprint`_.

.. _`technical report preprint`: https://arxiv.org/abs/2205.10469

|arXiv_badge|_

.. |arXiv_badge| image:: https://img.shields.io/badge/arXiv-2205.10469-b31b1b
.. _arXiv_badge: https://arxiv.org/abs/2205.10469


If you use Masterful for academic research, you are encouraged to cite:

::

   @article{wookeyhorikert2022masterful,
   title={Masterful: A Training Platform for Computer Vision Models},
   author={Wookey, Samuel and Ho, Yaoshiang and Rikert, Tom and Lopez, Juan David Gil and Beancur, Juan Manuel Mu{\~n}oz and Cortes, Santiago and Tawil, Ray and Sabin, Aaron and Lynch, Jack and Harper, Travis and others},
   journal={arXiv preprint arXiv:2205.10469},
   year={2022}
   }

Documentation
-------------

The rest of the documentation is organized into the following sections:

Getting Started
   Installation and Quickstart Tutorial.

Image Classification, Detection, and Segmentation
   Code examples to help you get started with the Masterful AutoML platform.

Semi-Supervised Learning
   Code examples exploring SSL using Masterful.

Advanced Topics
   Code examples for advanced use cases.

API Reference
   Documenting the classes, methods, and functions.

.. toctree::
   :maxdepth: 1
   :caption: Getting Started
   :hidden:
   :includehidden:

   Installation <tutorials/tutorial_installation>
   Quickstart Tutorial <notebooks/tutorial_quickstart>
   Visualizing the Results <tutorials/tutorial_frontend>

.. toctree::
   :maxdepth: 1
   :caption: Image Classification, Detection, and Segmentation
   :hidden:
   :includehidden:

   Classification <notebooks/guide_classification>
   Object Detection <notebooks/guide_object_detection>
   Semantic Segmentation <notebooks/guide_semantic_segmentation>

.. toctree::
   :maxdepth: 1
   :caption: Semi-Supervised Learning
   :hidden:
   :includehidden:

   Introduction to SSL <concepts/intro_to_ssl>
   Using Unlabeled Data Part 1 <notebooks/guide_ssl_using_unlabeled_data_part1>
   Using Unlabeled Data Part 2 <notebooks/guide_ssl_using_unlabeled_data_part2>
   Simple Semi-Supervised Learning Recipe <notebooks/guide_simple_ssl>
   Unsupervised Pre-Training <notebooks/guide_pretraining>

.. toctree::
   :maxdepth: 1
   :caption: Advanced Topics
   :hidden:
   :includehidden:

   Data Input Types <concepts/guide_data_input_types>
   Batch Size and Learning Rate Finder <notebooks/guide_batch_lr_finder>
   Transfer Learning <notebooks/guide_transfer_learning>
   Ensembling <notebooks/guide_ensembling>
   Distillation <notebooks/guide_distillation>

.. toctree::
   :maxdepth: 3
   :caption: API Reference
   :hidden:
   :includehidden:

   masterful.architecture <api/api_architecture>
   masterful.data <api/api_data>
   masterful.enums <api/api_enums>
   masterful.evaluation <api/api_evaluation>
   masterful.optimization <api/api_optimization>
   masterful.register <api/api_register>
   masterful.regularization <api/api_regularization>
   masterful.ssl <api/api_ssl>
   masterful.training <api/api_training>

.. toctree::
   :maxdepth: 3
   :caption: Release Notes
   :hidden:
   :includehidden:

   release_notes/release_notes