Improve docs

warner-benjamin · Jun 6, 2022 · 6713ffc · 6713ffc
1 parent c183fdc
commit 6713ffc
Show file tree

Hide file tree

Showing 10 changed files with 132 additions and 28 deletions.
diff --git a/docs/_data/sidebars/home_sidebar.yml b/docs/_data/sidebars/home_sidebar.yml
@@ -47,6 +47,12 @@ entries:
       url: callback.tracker.html
     output: web
     title: Callbacks
+  - folderitems:
+    - output: web,pdf
+      title: Splitters
+      url: data.transforms.html
+    output: web
+    title: Data
   - folderitems:
     - output: web,pdf
       title: Losses
@@ -69,6 +75,9 @@ entries:
     output: web
     title: Schedulers
   - folderitems:
+    - output: web,pdf
+      title: Data
+      url: vision.data.html
     - output: web,pdf
       title: TensorImage & TensorMask item_tfms
       url: vision.augment.itemtensor.html

diff --git a/docs/data.transforms.html b/docs/data.transforms.html
@@ -1,13 +1,13 @@
 ---
 
-title: Processing data and basic transforms
+title: Splitters
 
 
 keywords: fastai
 sidebar: home_sidebar
 
-summary: "Additional functions for getting, splitting, and labeling data, as well as generic transforms"
-description: "Additional functions for getting, splitting, and labeling data, as well as generic transforms"
+summary: "Additional functions for splitting data"
+description: "Additional functions for splitting data"
 nb_path: "nbs/data.transforms.ipynb"
 ---
 <!--
@@ -50,6 +50,29 @@
 <h4 id="KFoldColSplitter" class="doc_header"><code>KFoldColSplitter</code><a href="https://github.com/warner-benjamin/fastxtend/tree/main/fastxtend/data/transforms.py#L22" class="source_link" style="float:right">[source]</a></h4><blockquote><p><code>KFoldColSplitter</code>(<strong><code>fold</code></strong>:<code>listified[int]</code>=<em><code>0</code></em>, <strong><code>col</code></strong>:<code>int | str</code>=<em><code>'folds'</code></em>)</p>
 </blockquote>
 <p>Split <code>items</code> (supposed to be a dataframe) by <code>fold</code> in <code>col</code></p>
+<table>
+<thead><tr>
+<th></th>
+<th>Type</th>
+<th>Default</th>
+<th>Details</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><strong><code>fold</code></strong></td>
+<td><code>listified[int]</code></td>
+<td><code>0</code></td>
+<td>Valid set fold(s)</td>
+</tr>
+<tr>
+<td><strong><code>col</code></strong></td>
+<td><code>int or str</code></td>
+<td><code>folds</code></td>
+<td>Column with folds</td>
+</tr>
+</tbody>
+</table>
 
 </div>
 
@@ -79,9 +102,32 @@ <h4 id="KFoldColSplitter" class="doc_header"><code>KFoldColSplitter</code><a hre
 
 
 <div class="output_markdown rendered_html output_subarea ">
-<h4 id="ParentSplitter" class="doc_header"><code>ParentSplitter</code><a href="https://github.com/warner-benjamin/fastxtend/tree/main/fastxtend/data/transforms.py#L37" class="source_link" style="float:right">[source]</a></h4><blockquote><p><code>ParentSplitter</code>(<strong><code>train_name</code></strong>:<code>str</code>=<em><code>'train'</code></em>, <strong><code>valid_name</code></strong>:<code>str</code>=<em><code>'valid'</code></em>)</p>
+<h4 id="ParentSplitter" class="doc_header"><code>ParentSplitter</code><a href="https://github.com/warner-benjamin/fastxtend/tree/main/fastxtend/data/transforms.py#L40" class="source_link" style="float:right">[source]</a></h4><blockquote><p><code>ParentSplitter</code>(<strong><code>train_name</code></strong>:<code>str</code>=<em><code>'train'</code></em>, <strong><code>valid_name</code></strong>:<code>str</code>=<em><code>'valid'</code></em>)</p>
 </blockquote>
 <p>Split <code>items</code> from the parent folder names (<code>train_name</code> and <code>valid_name</code>).</p>
+<table>
+<thead><tr>
+<th></th>
+<th>Type</th>
+<th>Default</th>
+<th>Details</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><strong><code>train_name</code></strong></td>
+<td><code>str</code></td>
+<td><code>train</code></td>
+<td>Train set folder name</td>
+</tr>
+<tr>
+<td><strong><code>valid_name</code></strong></td>
+<td><code>str</code></td>
+<td><code>valid</code></td>
+<td>Valid set folder name</td>
+</tr>
+</tbody>
+</table>
 
 </div>
 
@@ -111,9 +157,32 @@ <h4 id="ParentSplitter" class="doc_header"><code>ParentSplitter</code><a href="h
 
 
 <div class="output_markdown rendered_html output_subarea ">
-<h4 id="GreatGrandparentSplitter" class="doc_header"><code>GreatGrandparentSplitter</code><a href="https://github.com/warner-benjamin/fastxtend/tree/main/fastxtend/data/transforms.py#L49" class="source_link" style="float:right">[source]</a></h4><blockquote><p><code>GreatGrandparentSplitter</code>(<strong><code>train_name</code></strong>:<code>str</code>=<em><code>'train'</code></em>, <strong><code>valid_name</code></strong>:<code>str</code>=<em><code>'valid'</code></em>)</p>
+<h4 id="GreatGrandparentSplitter" class="doc_header"><code>GreatGrandparentSplitter</code><a href="https://github.com/warner-benjamin/fastxtend/tree/main/fastxtend/data/transforms.py#L55" class="source_link" style="float:right">[source]</a></h4><blockquote><p><code>GreatGrandparentSplitter</code>(<strong><code>train_name</code></strong>:<code>str</code>=<em><code>'train'</code></em>, <strong><code>valid_name</code></strong>:<code>str</code>=<em><code>'valid'</code></em>)</p>
 </blockquote>
 <p>Split <code>items</code> from the great grand parent folder names (<code>train_name</code> and <code>valid_name</code>).</p>
+<table>
+<thead><tr>
+<th></th>
+<th>Type</th>
+<th>Default</th>
+<th>Details</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><strong><code>train_name</code></strong></td>
+<td><code>str</code></td>
+<td><code>train</code></td>
+<td>Train set folder name</td>
+</tr>
+<tr>
+<td><strong><code>valid_name</code></strong></td>
+<td><code>str</code></td>
+<td><code>valid</code></td>
+<td>Valid set folder name</td>
+</tr>
+</tbody>
+</table>
 
 </div>
 

diff --git a/docs/multiloss.html b/docs/multiloss.html
@@ -64,7 +64,7 @@ <h2 id="MultiLoss" class="doc_header"><code>class</code> <code>MultiLoss</code><
 <td><strong><code>loss_funcs</code></strong></td>
 <td><code>listy[nn.Module or FunctionType]</code></td>
 <td></td>
-<td>Uninitilized loss functions or classes. Must support PyTorch <code>reduction</code> string.</td>
+<td>Uninitialized loss functions or classes. Must support PyTorch <code>reduction</code> string.</td>
 </tr>
 <tr>
 <td><strong><code>weights</code></strong></td>
@@ -82,7 +82,7 @@ <h2 id="MultiLoss" class="doc_header"><code>class</code> <code>MultiLoss</code><
 <td><strong><code>loss_names</code></strong></td>
 <td><code>listy[str] or None</code></td>
 <td><code>None</code></td>
-<td>Loss names to log using <a href="/fastxtend/multiloss.html#MultiLossCallback"><code>MultiLossCallback</code></a>. Defaults to loss <strong>name</strong>.</td>
+<td>Loss names to log using <a href="/fastxtend/multiloss.html#MultiLossCallback"><code>MultiLossCallback</code></a>. Defaults to loss <code>__name__</code>.</td>
 </tr>
 <tr>
 <td><strong><code>reduction</code></strong></td>
@@ -148,7 +148,7 @@ <h2 id="MultiTargetLoss" class="doc_header"><code>class</code> <code>MultiTarget
 <td><strong><code>loss_funcs</code></strong></td>
 <td><code>listy[nn.Module or FunctionType]</code></td>
 <td></td>
-<td>Uninitilized loss functions or classes. One per prediction and target. Must support PyTorch <code>reduction</code> string.</td>
+<td>Uninitialized loss functions or classes. One per prediction and target. Must support PyTorch <code>reduction</code> string.</td>
 </tr>
 <tr>
 <td><strong><code>weights</code></strong></td>
@@ -166,7 +166,7 @@ <h2 id="MultiTargetLoss" class="doc_header"><code>class</code> <code>MultiTarget
 <td><strong><code>loss_names</code></strong></td>
 <td><code>listy[str] or None</code></td>
 <td><code>None</code></td>
-<td>Loss names to log using <a href="/fastxtend/multiloss.html#MultiLossCallback"><code>MultiLossCallback</code></a>. Defaults to loss <strong>name</strong>.</td>
+<td>Loss names to log using <a href="/fastxtend/multiloss.html#MultiLossCallback"><code>MultiLossCallback</code></a>. Defaults to loss <code>__name__</code>.</td>
 </tr>
 <tr>
 <td><strong><code>reduction</code></strong></td>
@@ -215,7 +215,7 @@ <h2 id="MultiTargetLoss" class="doc_header"><code>class</code> <code>MultiTarget
 
 
 <div class="output_markdown rendered_html output_subarea ">
-<h2 id="MultiLossCallback" class="doc_header"><code>class</code> <code>MultiLossCallback</code><a href="https://github.com/warner-benjamin/fastxtend/tree/main/fastxtend/multiloss.py#L160" class="source_link" style="float:right">[source]</a></h2><blockquote><p><code>MultiLossCallback</code>(<strong><code>beta</code></strong>:<code>float</code>=<em><code>0.98</code></em>, <strong><code>reduction</code></strong>:<code>str | None</code>=<em><code>'mean'</code></em>) :: <code>Callback</code></p>
+<h2 id="MultiLossCallback" class="doc_header"><code>class</code> <code>MultiLossCallback</code><a href="https://github.com/warner-benjamin/fastxtend/tree/main/fastxtend/multiloss.py#L162" class="source_link" style="float:right">[source]</a></h2><blockquote><p><code>MultiLossCallback</code>(<strong><code>beta</code></strong>:<code>float</code>=<em><code>0.98</code></em>, <strong><code>reduction</code></strong>:<code>str | None</code>=<em><code>'mean'</code></em>) :: <code>Callback</code></p>
 </blockquote>
 <p>Callback to automatically log and name <a href="/fastxtend/multiloss.html#MultiLoss"><code>MultiLoss</code></a> losses as fastxtend metrics</p>
 <table>

diff --git a/docs/sidebar.json b/docs/sidebar.json
@@ -16,6 +16,9 @@
     "Simple Profiler": "callback.simpleprofiler.html",
     "Tracker": "callback.tracker.html"
   },
+  "Data": {
+    "Splitters": "data.transforms.html"
+  },
   "Losses": {
     "Losses": "losses.html",
     "Multiloss": "multiloss.html"
@@ -27,6 +30,7 @@
     "Fit Flat Varied": "schedulers.fit_flat_varied.html"
   },
   "Vision": {
+    "Data": "vision.data.html",
     "TensorImage & TensorMask item_tfms": "vision.augment.itemtensor.html",
     "": {
       "Models":{

diff --git a/docs/vision.data.html b/docs/vision.data.html
@@ -187,7 +187,7 @@ <h4 id="MaskCPUBlock" class="doc_header"><code>MaskCPUBlock</code><a href="https
 
 <div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
 <div class="text_cell_render border-box-sizing rendered_html">
-<h2 id="Batch-Transforms-on-CPU-Example">Batch Transforms on CPU Example<a class="anchor-link" href="#Batch-Transforms-on-CPU-Example"> </a></h2>
+<h3 id="Batch-Transforms-on-CPU-Example">Batch Transforms on CPU Example<a class="anchor-link" href="#Batch-Transforms-on-CPU-Example"> </a></h3>
 </div>
 </div>
 </div>

diff --git a/fastxtend/data/transforms.py b/fastxtend/data/transforms.py
@@ -19,7 +19,10 @@
 from ..imports import *
 
 # Cell
-def KFoldColSplitter(fold:listified[int]=0, col:int|str='folds'):
+def KFoldColSplitter(
+    fold:listified[int]=0, # Valid set fold(s)
+    col:int|str='folds' # Column with folds
+):
     "Split `items` (supposed to be a dataframe) by `fold` in `col`"
     def _inner(o):
         assert isinstance(o, pd.DataFrame), "KFoldColSplitter only works when your items are a pandas DataFrame"
@@ -34,7 +37,10 @@ def _inner(items, name): return mask2idxs(Path(o).parent.name == name for o in i
     return [i for n in L(name) for i in _inner(items,n)]
 
 # Cell
-def ParentSplitter(train_name:str='train', valid_name:str='valid'):
+def ParentSplitter(
+    train_name:str='train', # Train set folder name
+    valid_name:str='valid' # Valid set folder name
+):
     "Split `items` from the parent folder names (`train_name` and `valid_name`)."
     def _inner(o):
         return _parent_idxs(o, train_name),_parent_idxs(o, valid_name)
@@ -46,7 +52,10 @@ def _inner(items, name): return mask2idxs(Path(o).parent.parent.parent.name == n
     return [i for n in L(name) for i in _inner(items,n)]
 
 # Cell
-def GreatGrandparentSplitter(train_name:str='train', valid_name:str='valid'):
+def GreatGrandparentSplitter(
+    train_name:str='train', # Train set folder name
+    valid_name:str='valid' # Valid set folder name
+):
     "Split `items` from the great grand parent folder names (`train_name` and `valid_name`)."
     def _inner(o):
         return _greatgrandparent_idxs(o, train_name),_greatgrandparent_idxs(o, valid_name)

diff --git a/fastxtend/multiloss.py b/fastxtend/multiloss.py
@@ -30,10 +30,10 @@ class MultiLoss(Module):
     Log `loss_funcs` as metrics via `MultiLossCallback`, optionally using `loss_names`.
     """
     def __init__(self,
-        loss_funcs:listy[nn.Module|FunctionType], # Uninitilized loss functions or classes. Must support PyTorch `reduction` string.
+        loss_funcs:listy[nn.Module|FunctionType], # Uninitialized loss functions or classes. Must support PyTorch `reduction` string.
         weights:listified[Number]|None=None, # Weight per loss. Defaults to uniform weighting.
         loss_kwargs:listy[dict[str,Any]]|None=None, # kwargs to pass to each loss function. Defaults to None.
-        loss_names:listy[str]|None=None, # Loss names to log using `MultiLossCallback`. Defaults to loss __name__.
+        loss_names:listy[str]|None=None, # Loss names to log using `MultiLossCallback`. Defaults to loss `__name__`.
         reduction:str|None='mean' # PyTorch loss reduction
     ):
         store_attr(but='loss_names')
@@ -96,10 +96,10 @@ class MultiTargetLoss(MultiLoss):
     Log `loss_funcs` as metrics via `MultiLossCallback`, optionally using `loss_names`.
     """
     def __init__(self,
-        loss_funcs:listy[nn.Module|FunctionType], # Uninitilized loss functions or classes. One per prediction and target. Must support PyTorch `reduction` string.
+        loss_funcs:listy[nn.Module|FunctionType], # Uninitialized loss functions or classes. One per prediction and target. Must support PyTorch `reduction` string.
         weights:listified[Number]|None=None, # Weight per loss. Defaults to uniform weighting.
         loss_kwargs:listy[dict[str,Any]]|None=None, # kwargs to pass to each loss function. Defaults to None.
-        loss_names:listy[str]|None=None, # Loss names to log using `MultiLossCallback`. Defaults to loss __name__.
+        loss_names:listy[str]|None=None, # Loss names to log using `MultiLossCallback`. Defaults to loss `__name__`.
         reduction:str|None='mean' # PyTorch loss reduction
     ):
         super().__init__(loss_funcs, weights, loss_kwargs, loss_names, reduction)
@@ -114,9 +114,11 @@ def forward(self, preds, targs):
         return loss.mean() if self._reduction=='mean' else loss.sum() if self._reduction=='sum' else loss
 
     def activation(self, preds):
+        "Returns list of `activation`"
         return [getattr(self.loss_funcs[i], 'activation', noop)(pred) for i, pred in enumerate(preds)]
 
     def decodes(self, preds):
+        "Returns list of `decodes`"
         return [getattr(self.loss_funcs[i], 'decodes', noop)(pred) for i, pred in enumerate(preds)]
 
 # Internal Cell

diff --git a/nbs/data.transforms.ipynb b/nbs/data.transforms.ipynb
@@ -32,9 +32,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Processing data and basic transforms\n",
+    "# Splitters\n",
     "\n",
-    "> Additional functions for getting, splitting, and labeling data, as well as generic transforms"
+    "> Additional functions for splitting data"
    ]
   },
   {
@@ -55,7 +55,10 @@
    "outputs": [],
    "source": [
     "#|export\n",
-    "def KFoldColSplitter(fold:listified[int]=0, col:int|str='folds'):\n",
+    "def KFoldColSplitter(\n",
+    "    fold:listified[int]=0, # Valid set fold(s)\n",
+    "    col:int|str='folds' # Column with folds \n",
+    "):\n",
     "    \"Split `items` (supposed to be a dataframe) by `fold` in `col`\"\n",
     "    def _inner(o):\n",
     "        assert isinstance(o, pd.DataFrame), \"KFoldColSplitter only works when your items are a pandas DataFrame\"\n",
@@ -126,7 +129,10 @@
    "outputs": [],
    "source": [
     "#|export\n",
-    "def ParentSplitter(train_name:str='train', valid_name:str='valid'):\n",
+    "def ParentSplitter(\n",
+    "    train_name:str='train', # Train set folder name\n",
+    "    valid_name:str='valid' # Valid set folder name\n",
+    "):\n",
     "    \"Split `items` from the parent folder names (`train_name` and `valid_name`).\"\n",
     "    def _inner(o):\n",
     "        return _parent_idxs(o, train_name),_parent_idxs(o, valid_name)\n",
@@ -169,7 +175,10 @@
    "outputs": [],
    "source": [
     "#|export\n",
-    "def GreatGrandparentSplitter(train_name:str='train', valid_name:str='valid'):\n",
+    "def GreatGrandparentSplitter(\n",
+    "    train_name:str='train', # Train set folder name\n",
+    "    valid_name:str='valid' # Valid set folder name\n",
+    "):\n",
     "    \"Split `items` from the great grand parent folder names (`train_name` and `valid_name`).\"\n",
     "    def _inner(o):\n",
     "        return _greatgrandparent_idxs(o, train_name),_greatgrandparent_idxs(o, valid_name)\n",

diff --git a/nbs/multiloss.ipynb b/nbs/multiloss.ipynb
@@ -72,10 +72,10 @@
     "    Log `loss_funcs` as metrics via `MultiLossCallback`, optionally using `loss_names`.\n",
     "    \"\"\"\n",
     "    def __init__(self, \n",
-    "        loss_funcs:listy[nn.Module|FunctionType], # Uninitilized loss functions or classes. Must support PyTorch `reduction` string.\n",
+    "        loss_funcs:listy[nn.Module|FunctionType], # Uninitialized loss functions or classes. Must support PyTorch `reduction` string.\n",
     "        weights:listified[Number]|None=None, # Weight per loss. Defaults to uniform weighting.\n",
     "        loss_kwargs:listy[dict[str,Any]]|None=None, # kwargs to pass to each loss function. Defaults to None.\n",
-    "        loss_names:listy[str]|None=None, # Loss names to log using `MultiLossCallback`. Defaults to loss __name__.\n",
+    "        loss_names:listy[str]|None=None, # Loss names to log using `MultiLossCallback`. Defaults to loss `__name__`.\n",
     "        reduction:str|None='mean' # PyTorch loss reduction\n",
     "    ):\n",
     "        store_attr(but='loss_names')\n",
@@ -205,10 +205,10 @@
     "    Log `loss_funcs` as metrics via `MultiLossCallback`, optionally using `loss_names`.\n",
     "    \"\"\"\n",
     "    def __init__(self, \n",
-    "        loss_funcs:listy[nn.Module|FunctionType], # Uninitilized loss functions or classes. One per prediction and target. Must support PyTorch `reduction` string.\n",
+    "        loss_funcs:listy[nn.Module|FunctionType], # Uninitialized loss functions or classes. One per prediction and target. Must support PyTorch `reduction` string.\n",
     "        weights:listified[Number]|None=None, # Weight per loss. Defaults to uniform weighting.\n",
     "        loss_kwargs:listy[dict[str,Any]]|None=None, # kwargs to pass to each loss function. Defaults to None.\n",
-    "        loss_names:listy[str]|None=None, # Loss names to log using `MultiLossCallback`. Defaults to loss __name__.\n",
+    "        loss_names:listy[str]|None=None, # Loss names to log using `MultiLossCallback`. Defaults to loss `__name__`.\n",
     "        reduction:str|None='mean' # PyTorch loss reduction\n",
     "    ):\n",
     "        super().__init__(loss_funcs, weights, loss_kwargs, loss_names, reduction)\n",
@@ -223,9 +223,11 @@
     "        return loss.mean() if self._reduction=='mean' else loss.sum() if self._reduction=='sum' else loss\n",
     "\n",
     "    def activation(self, preds):\n",
+    "        \"Returns list of `activation`\"\n",
     "        return [getattr(self.loss_funcs[i], 'activation', noop)(pred) for i, pred in enumerate(preds)]\n",
     "\n",
     "    def decodes(self, preds):\n",
+    "        \"Returns list of `decodes`\"\n",
     "        return [getattr(self.loss_funcs[i], 'decodes', noop)(pred) for i, pred in enumerate(preds)]"
    ]
   },

diff --git a/nbs/vision.data.ipynb b/nbs/vision.data.ipynb
@@ -146,7 +146,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Batch Transforms on CPU Example"
+    "### Batch Transforms on CPU Example"
    ]
   },
   {