[wip] FAQ (#988)

* structure

* draft 1

* metrics update docs

* just more docs

* codestyle

catalyst/callbacks/early_stop.py

@@ -7,7 +7,46 @@
 
 
 class CheckRunCallback(Callback):
-    """Executes only a pipeline part from the ``Experiment``."""
+    """Executes only a pipeline part from the ``Experiment``.
+
+    Minimal working example (Notebook API):
+
+    .. code-block:: python
+
+        import torch
+        from torch.utils.data import DataLoader, TensorDataset
+        from catalyst import dl
+
+        # data
+        num_samples, num_features = int(1e4), int(1e1)
+        X, y = torch.rand(num_samples, num_features), torch.rand(num_samples)
+        dataset = TensorDataset(X, y)
+        loader = DataLoader(dataset, batch_size=32, num_workers=1)
+        loaders = {"train": loader, "valid": loader}
+
+        # model, criterion, optimizer, scheduler
+        model = torch.nn.Linear(num_features, 1)
+        criterion = torch.nn.MSELoss()
+        optimizer = torch.optim.Adam(model.parameters())
+        scheduler = torch.optim.lr_scheduler.MultiStepLR(optimizer, [3, 6])
+
+        # model training
+        runner = dl.SupervisedRunner()
+        runner.train(
+            model=model,
+            criterion=criterion,
+            optimizer=optimizer,
+            scheduler=scheduler,
+            loaders=loaders,
+            logdir="./logdir",
+            num_epochs=8,
+            verbose=True,
+            callbacks=[
+                dl.CheckRunCallback(num_batch_steps=3, num_epoch_steps=3)
+            ]
+        )
+
+    """
 
     def __init__(self, num_batch_steps: int = 3, num_epoch_steps: int = 2):
         """
@@ -41,24 +80,42 @@ def on_batch_end(self, runner: "IRunner"):
 class EarlyStoppingCallback(Callback):
     """Early exit based on metric.
 
-    Example of usage in notebook API:
+    Minimal working example (Notebook API):
 
     .. code-block:: python
 
-        runner = SupervisedRunner()
+        import torch
+        from torch.utils.data import DataLoader, TensorDataset
+        from catalyst import dl
+
+        # data
+        num_samples, num_features = int(1e4), int(1e1)
+        X, y = torch.rand(num_samples, num_features), torch.rand(num_samples)
+        dataset = TensorDataset(X, y)
+        loader = DataLoader(dataset, batch_size=32, num_workers=1)
+        loaders = {"train": loader, "valid": loader}
+
+        # model, criterion, optimizer, scheduler
+        model = torch.nn.Linear(num_features, 1)
+        criterion = torch.nn.MSELoss()
+        optimizer = torch.optim.Adam(model.parameters())
+        scheduler = torch.optim.lr_scheduler.MultiStepLR(optimizer, [3, 6])
+
+        # model training
+        runner = dl.SupervisedRunner()
         runner.train(
-            ...
-            callbacks=[
-                ...
-                EarlyStoppingCallback(
-                    patience=5,
-                    metric="my_metric",
-                    minimize=True,
-                )
-                ...
-            ]
+          model=model,
+          criterion=criterion,
+          optimizer=optimizer,
+          scheduler=scheduler,
+          loaders=loaders,
+          logdir="./logdir",
+          num_epochs=8,
+          verbose=True,
+          callbacks=[
+            dl.EarlyStoppingCallback(patience=2, metric="loss", minimize=True)
+          ]
         )
-        ...
 
     Example of usage in config API:
 

catalyst/metrics/__init__.py

@@ -1,16 +1,4 @@
 # flake8: noqa
-from catalyst.metrics.accuracy import accuracy, multi_label_accuracy
-from catalyst.metrics.avg_precision import avg_precision, mean_avg_precision
-from catalyst.metrics.auc import auc
-from catalyst.metrics.cmc_score import cmc_score, cmc_score_count
-from catalyst.metrics.ndcg import dcg, ndcg
-from catalyst.metrics.dice import dice, calculate_dice
-from catalyst.metrics.f1_score import f1_score, fbeta_score
-from catalyst.metrics.hitrate import hitrate
-from catalyst.metrics.classification import precision_recall_fbeta_support
-from catalyst.metrics.precision import precision
-from catalyst.metrics.recall import recall
-from catalyst.metrics.focal import sigmoid_focal_loss, reduced_focal_loss
 from catalyst.metrics.functional import (
     process_multilabel_components,
     get_binary_statistics,
@@ -20,6 +8,18 @@
     wrap_class_metric2dict,
     wrap_topk_metric2dict,
 )
+from catalyst.metrics.classification import precision_recall_fbeta_support
+
+from catalyst.metrics.accuracy import accuracy, multi_label_accuracy
+from catalyst.metrics.auc import auc
+from catalyst.metrics.avg_precision import avg_precision, mean_avg_precision
+from catalyst.metrics.cmc_score import cmc_score, cmc_score_count
+from catalyst.metrics.dice import dice, calculate_dice
+from catalyst.metrics.f1_score import f1_score, fbeta_score
+from catalyst.metrics.focal import sigmoid_focal_loss, reduced_focal_loss
+from catalyst.metrics.hitrate import hitrate
 from catalyst.metrics.iou import iou, jaccard
 from catalyst.metrics.mrr import mrr
-from catalyst.metrics.precision import average_precision
+from catalyst.metrics.ndcg import dcg, ndcg
+from catalyst.metrics.precision import average_precision, precision
+from catalyst.metrics.recall import recall

catalyst/metrics/recall.py

@@ -37,3 +37,6 @@ def recall(
     )
 
     return recall_score
+
+
+__all__ = ["recall"]

docs/api/metrics.rst

@@ -78,13 +78,6 @@ MRR
 
 MAP
 ------------------------
-.. automodule:: catalyst.metrics.mean_avg_precision
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-AP
-------------------------
 .. automodule:: catalyst.metrics.avg_precision
     :members:
     :undoc-members:
@@ -97,16 +90,16 @@ NDCG
     :undoc-members:
     :show-inheritance:
 
-DCG
+Precision
 ------------------------
-.. automodule:: catalyst.metrics.dcg
+.. automodule:: catalyst.metrics.precision
     :members:
     :undoc-members:
     :show-inheritance:
 
-Precision
+Recall
 ------------------------
-.. automodule:: catalyst.metrics.precision
+.. automodule:: catalyst.metrics.recall
     :members:
     :undoc-members:
     :show-inheritance:

docs/core/callback.rst

@@ -0,0 +1,3 @@
+Callback
+==============================================================================
+

docs/core/experiment.rst

@@ -0,0 +1,29 @@
+Experiment
+==============================================================================
+
+Experiment - an abstraction that contains information about the experiment
+- a model, a criterion, an optimizer, a scheduler, and their hyperparameters.
+It also holds information about the data and transformations to apply.
+The Experiment knows **what** you would like to run.
+
+Each deep learning project has several main components.
+These primitives define what we want to use during the experiment:
+
+- the data
+- the model(s)
+- the optimizer(s)
+- the loss(es)
+- and the scheduler(s) if we need them.
+
+That are the abstractions that Experiment covers in Catalyst,
+with a few modifications for easier experiment monitoring
+and hyperparameters logging. For each stage of our experiment,
+the Experiment provides interfaces to all primitives above + the callbacks.
+
+.. image:: https://raw.githubusercontent.com/catalyst-team/catalyst-pics/master/third_party_pics/catalyst102-experiment.png
+    :alt: Experiment
+
+
+---
+
+- what is the difference between different Experiments?

docs/core/runner.rst

@@ -0,0 +1,6 @@
+Runner
+==============================================================================
+
+---
+
+- what is the difference between different Runners?

docs/faq/amp.rst

@@ -0,0 +1,9 @@
+Mixed precision training
+==============================================================================
+
+- How to use Nvidia Apex?
+- How to use torch.amp?
+
+If you haven't found the answer for your question, feel free to `join our slack`_ for the discussion.
+
+.. _`join our slack`: https://join.slack.com/t/catalyst-team-core/shared_invite/zt-d9miirnn-z86oKDzFMKlMG4fgFdZafw

docs/faq/checkpointing.rst

@@ -0,0 +1,12 @@
+[WIP] Model checkpointing
+==============================================================================
+
+- how to load bset model?
+- notebook and config api
+- how to save model?
+- how to load model?
+- whats the difference between checkpoint and checkpoint_full?
+
+If you haven't found the answer for your question, feel free to `join our slack`_ for the discussion.
+
+.. _`join our slack`: https://join.slack.com/t/catalyst-team-core/shared_invite/zt-d9miirnn-z86oKDzFMKlMG4fgFdZafw

docs/contributing/codestyle.rst → docs/faq/config_api.rst

@@ -1,4 +1,4 @@
-Codestyle
+[WIP] Config API
 ==============================================================================
 
 Hi,
@@ -11,4 +11,8 @@ But don't feel upset, check out the kitty... `Kittylyst`_ tutorial.
 
 .. image:: https://raw.githubusercontent.com/Scitator/kittylyst/master/assets/kitty.jpg
     :target: https://github.com/Scitator/kittylyst
-    :alt: kitty
+    :alt: kitty
+
+If you haven't found the answer for your question, feel free to `join our slack`_ for the discussion.
+
+.. _`join our slack`: https://join.slack.com/t/catalyst-team-core/shared_invite/zt-d9miirnn-z86oKDzFMKlMG4fgFdZafw