Merge branch 'release/v0.4.2'

marcellejs · Oct 9, 2021 · 5f19da3 · 5f19da3
2 parents b40939c + 5c24624
commit 5f19da3
Show file tree

Hide file tree

Showing 63 changed files with 3,236 additions and 2,006 deletions.
diff --git a/.gitignore b/.gitignore
@@ -2,5 +2,5 @@
 node_modules
 dist
 types
-*.onnx
-examples/dist
+examples/dist
+.netlify
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,12 @@
 # Marcelle changelog
 
+## 0.4.2
+
+- New `trainingHistory` component to track and monitor training runs.
+- `datasetTable` now automatically extracts columns from service data
+- Removed `onnxModel` from release due to limited operator support.
+- Improved documentation website
+
 ## 0.4.1
 
 - new component: `datasetTable` to display the contents of a dataset as a table

diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
@@ -24,6 +24,10 @@ module.exports = {
         text: 'Examples',
         link: '/examples/',
       },
+      {
+        text: 'Credits',
+        link: '/credits/',
+      },
     ],
     sidebar: {
       '/api/': [

diff --git a/docs/.vuepress/public/banner.png b/docs/.vuepress/public/banner.png
diff --git a/docs/.vuepress/styles/index.styl b/docs/.vuepress/styles/index.styl
@@ -60,3 +60,96 @@ td:last-child
   // width: 10%
 tr
   border: none
+
+.home
+  // box-sizing: border-box
+  .blob
+    position: absolute
+    top: 0
+    right: 0
+  .title
+    font-size: 6rem
+    font-weight: 300
+    margin-top: 2rem
+    margin-bottom: 0
+    position: relative
+    mix-blend-mode: multiply
+  .subtitle
+    font-size: 2.5rem
+    font-weight: 300
+    color: #6a8bad
+    position: relative
+    mix-blend-mode: multiply
+  .row
+    position: relative
+    display: flex
+    text-align: justify
+    text-justify: inter-character
+    margin: 3rem auto
+    width: 100%
+    @media (max-width: 900px)
+      flex-direction: column-reverse
+    :first-child
+      flex-shrink: 1
+      max-width: 100%
+      width: 340px
+      margin-top: 1rem
+    :last-child
+      max-width: 500px
+      margin-right: 0
+      margin-left: auto
+      font-size: 1.2rem
+      line-height: 1.3rem
+      flex-shrink: 0
+  .intro
+    justify-content: space-between
+  .teaser
+    margin: 3rem 0
+    position: relative
+    display: flex
+    align-items: flex-end
+    width: 100%
+    @media (max-width: 900px)
+      flex-direction: column
+    .teaser-title
+      width: 350px
+      max-width: 100%
+      // position absolute
+      margin-right: -2rem
+      margin-bottom: 2rem
+      background: white
+      opacity: 0.8
+      color: $textColor
+      padding: 1rem
+      border: 1px solid #ffc9b2;
+      // border-radius: 0.5rem
+      @media (max-width: 900px)
+        margin: 0 auto
+    p
+      img
+        max-width: 100%
+        width: 600px
+    &.top
+      align-items: flex-start
+    &.reversed
+      flex-direction: row-reverse
+      @media (max-width: 900px)
+        flex-direction: column
+      .teaser-title
+        margin-left: -2rem
+        margin-right: 0
+  .action-button
+    box-sizing: border-box
+    background-color: #FF6F61 !important
+    border-color: #FF6151 !important
+    margin-bottom: 2rem
+  a.demos
+    color: #FF6151 !important
+    margin-left: 1rem
+  h2.centered
+    text-align: center
+    font-size: 3rem
+    font-weight: 400
+    border: none
+  .feat
+    text-align: left
diff --git a/docs/.vuepress/styles/palette.styl b/docs/.vuepress/styles/palette.styl
@@ -1,5 +1,5 @@
 // colors
-$accentColor =rgb(56, 178, 172) // #3eaf7c
+$accentColor =#F7770F // rgb(56, 178, 172) // #3eaf7c
 $textColor = #2c3e50
 $borderColor = #eaecef
 $codeBgColor = #282c34

diff --git a/docs/README.md b/docs/README.md
@@ -1,20 +1,102 @@
 ---
 home: true
-heroImage: /banner.png
-heroText: Marcelle
-tagline: Composing Interactive Machine Learning Workflows and Interfaces
-actionText: Get Started →
-actionLink: /guide/
-features:
-  - title: Modular
-    details: Marcelle provides building blocks to easily compose interactive machine learning applications.
-  - title: Reactive
-    details: Marcelle relies on reactive programming to facilitate the design of event-driven ML applications and provide users with instant feedback.
-  - title: Visual
-    details: Marcelle components come with UI components that can be arranged in a graphical interface according to the requirements of the task.
-footer: MIT Licensed | Copyright © 2020-present Anonymized for Review
+heroText:
+tagline:
+# heroImage: /banner.jpg
+# heroText: Marcelle
+# tagline: Composing Interactive Machine Learning Workflows and Interfaces
+# actionText: Get Started →
+# actionLink: /guide/
+# features:
+#   - title: Modular
+#     details: Marcelle provides building blocks to easily compose interactive machine learning applications.
+#   - title: Reactive
+#     details: Marcelle relies on reactive programming to facilitate the design of event-driven ML applications and provide users with instant feedback.
+#   - title: Visual
+#     details: Marcelle components come with UI components that can be arranged in a graphical interface according to the requirements of the task.
+footer: MIT Licensed | Copyright © 2020-present Jules Françoise, Baptiste Caramiaux
 ---
 
-::: warning ⚠️ Experimental
-Marcelle is still experimental and is currently under active development. Breaking changes are expected.
-:::
+<div class="blob">
+<svg id="visual" viewBox="0 0 900 600" width="900" height="600" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1"><g transform="translate(872.524067255215 -24.3207671090629)"><path d="M349.7 -387.1C442.3 -339.1 498.8 -218.5 516.8 -94.4C534.8 29.7 514.2 157.4 449 248.7C383.7 340 273.8 395.1 161.1 431.1C48.5 467 -66.9 483.9 -126.7 427.7C-186.5 371.4 -190.7 242 -255 141.8C-319.3 41.6 -443.8 -29.3 -464.8 -111.8C-485.7 -194.2 -403.2 -288.2 -308.5 -335.9C-213.8 -383.5 -106.9 -384.8 10.8 -397.6C128.6 -410.5 257.1 -435.1 349.7 -387.1" fill="#FCAF3C"></path></g></svg>
+</div>
+
+<h1 class="title">Marcelle</h1>
+<div class="subtitle">A Toolkit for Composing Interactive Machine Learning Workflows and Interfaces</div>
+
+<div class="row intro">
+
+![Intro blob](./images/intro-blob.jpg)
+
+<!-- <svg id="visual" viewBox="0 0 300 300" width="300" height="300" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1"><g transform="translate(137.1465233658941 164.78352067797127)"><path d="M56.1 -84C75.4 -63.1 95.7 -50.4 116.3 -28.1C136.8 -5.8 157.6 26.1 154.5 54.7C151.4 83.4 124.5 108.8 94.8 118.2C65 127.5 32.5 120.8 3.8 115.5C-24.9 110.2 -49.8 106.5 -73.5 95.2C-97.3 83.9 -120 65.2 -126.7 41.8C-133.5 18.4 -124.3 -9.5 -118.4 -41.9C-112.6 -74.3 -110.1 -111.2 -90.9 -132.1C-71.7 -153 -35.9 -158 -8.7 -146C18.4 -134 36.7 -104.9 56.1 -84" fill="#F7770F"></path></g></svg> -->
+
+**Marcelle** is a modular open source toolkit for programming interactive machine learning applications. Marcelle is built around components embedding computation and interaction that can be composed to form reactive machine learning pipelines and custom user interfaces. This architecture enables rapid prototyping and extension. Marcelle can be used to build interfaces to Python scripts, and it provides flexible data stores to facilitate collaboration between machine learning experts, designers and end users.</p></div>
+
+<div class="hero"><p class="action">
+<a href="/guide/" class="nav-link action-button">Get Started →</a>
+<a href="https://demos.marcelle.dev/" class="nav-link demos">Try the Demos <svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg></a>
+</p></div>
+
+<!-- <div class="arch"> -->
+
+<!-- ![Marcelle Overview](/banner.jpg) -->
+
+<!-- </div> -->
+
+---
+
+<div class="teaser">
+<span class="teaser-title">
+<strong>Design Human-AI interactions in minutes.</strong><br>
+Marcelle provides a high-level API enabling rapid prototyping of applications where human directly interact with machine learning systems.
+</span>
+<!-- <span class="teaser-desc"></span> -->
+
+![GIF Webcam recognition](./images/sketch-gif.gif)
+
+</div>
+
+---
+
+<h2 class="centered">Features</h2>
+
+<div class="teaser">
+<span class="teaser-title">
+<strong>Modular</strong><br>
+Marcelle is built around various components providing a graphical user interface that can be displayed on demand.
+Components can typically be data sources (for instance a webcam capturing images), data structures (such as datasets), models, or visualization.
+</span>
+
+![Component-based architecture Animation](./guide/images/principle-01.gif)
+
+</div>
+
+<div class="teaser reversed top">
+<span class="teaser-title">
+<strong>Composable</strong><br>
+Marcelle provides two layout mechanisms for user interface composition: dashboards and wizards.
+</span>
+
+![Composable Interfaces Animation](./guide/images/principle-02.png)
+
+</div>
+
+<div class="teaser top">
+<span class="teaser-title">
+<strong>Interaction-Driven</strong><br>
+Marcelle emphasizes machine learning pipelines driven by user interactions, through reactive programming.
+</span>
+
+![Interaction-driven pipelines Animation](./guide/images/principle-03.gif)
+
+</div>
+
+<div class="teaser reversed top">
+<span class="teaser-title">
+<strong>Designed for collaboration</strong><br>
+Marcelle's data stores enable sharing data and models among stakeholders
+</span>
+
+![Collaboration](./images/teaser-pres.jpg)
+
+</div>
diff --git a/docs/api/components/images/training-history.png b/docs/api/components/images/training-history.png
diff --git a/docs/api/components/model-interfaces.md b/docs/api/components/model-interfaces.md
@@ -47,7 +47,7 @@ dashboard.page('Training').use(params);
 ## trainingProgress
 
 ```tsx
-marcelle.trainingProgress(m: Model): Progress;
+marcelle.trainingProgress(m: Model): TrainingProgress;
 ```
 
 Displays the progress of the training process for a given model.
@@ -74,7 +74,7 @@ const prog = marcelle.trainingProgress(classifier);
 ## trainingPlot
 
 ```tsx
-marcelle.trainingPlot(m: Model): Progress;
+marcelle.trainingPlot(m: Model): TrainingPlot;
 ```
 
 Displays the training/validation loss and accuracies during the training of a neural network.
@@ -97,3 +97,86 @@ Displays the training/validation loss and accuracies during the training of a ne
 const classifier = marcelle.mlp({ layers: [64, 32], epochs: 20 });
 const prog = marcelle.trainingPlot(classifier);
 ```
+
+## trainingHistory
+
+```tsx
+marcelle.trainingHistory(dataStore: DataStore, options: {
+  metrics?: string[];
+  actions?: Array<string | { name: string; multiple?: boolean }>;
+}): TrainingHistory;
+```
+
+The `TrainingHistory` component can be used to track and visualize training runs stored in a data store. This component is useful to compare experiments, compare model versions, and revert back to previously trained models. When using Marcelle's Python package, each training run is recorded to a data store, and can be accessed with the `TrainingHistory` component.
+
+### Parameters
+
+| Option          | Type                                                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Required |
+| --------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------: |
+| dataStore       | DataStore                                             | The [dataStore](/api/data-stores) used to store the training runs.                                                                                                                                                                                                                                                                                                                                                                                                             |    ✓     |
+| options.metrics | string[]                                              | The metrics to display in the run comparison table. Defaults to ['accuracy', 'accuracyVal', 'loss', 'lossVal'].                                                                                                                                                                                                                                                                                                                                                                |    ✓     |
+| options.actions | Array<string \| { name: string; multiple?: boolean }> | This option defines a set of actions that can be associated with the training runs. Actions are displayed as buttons at the end of each line in the main table and can be applied to selected runs. Actions are passed as an array of either strings (defining the name of each action) or objects (specifying the name and whether or not the action can be applied to multiple selection, i.e. several selected runs). Actions are then exposed using the `$actions` stream. |    ✓     |
+
+### Streams
+
+| Name        | Type                                        | Description                                                                                                                                                                            | Hold |
+| ----------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--: |
+| \$selection | Stream<TrainingRun[]>                       | Stream of training runs selected through the user interface.                                                                                                                           |  ✓   |
+| \$actions   | Stream<{ name: string; data: TrainingRun }> | Stream of actions triggered by the user through the associated buttons. Each event is an object containing the action's `name` and the associated training run(s) in the `data` field. |      |
+
+Training runs and model checkpoints have the following interfaces:
+
+```ts
+export interface TrainingRun {
+  id?: ObjectId;
+  name: string;
+  basename: string;
+  start: string;
+  status: TrainingStatus['status'];
+  epoch?: number;
+  epochs?: number;
+  params?: Record<string, unknown>;
+  logs?: TrainingStatus['data'];
+  checkpoints?: Array<ModelCheckpoint>;
+  model?: {
+    summary?: string;
+    [key: string]: unknown;
+  };
+  [key: string]: unknown;
+}
+
+export interface ModelCheckpoint {
+  id: ObjectId;
+  name: string;
+  service: string;
+  metadata?: Record<string, unknown>;
+}
+```
+
+### Methods
+
+#### .track()
+
+```tsx
+track(model: Model<InputType, OutputType>, basename = 'anonymous'): TrainingHistory
+```
+
+Start tracking a given machine learning model. Every time the model is trained, the run will be recorded to the data store and displayed in the trainingHistory component. A name `basename` can be given to the model, so that training runs are named `basename-<run index>`.
+
+### Screenshot
+
+<div style="background: rgb(237, 242, 247); padding: 8px; margin-top: 1rem;">
+  <img src="./images/training-history.png" alt="Screenshot of the trainingHistory component">
+</div>
+
+### Example
+
+```js
+const hist = trainingHistory(store, {
+  actions: ['select model'],
+}).track(classifier, 'mlp-webcam');
+
+hist.$actions.subscribe(({ name, data }) => {
+  console.log(`Action [${name}]`, data);
+});
+```
diff --git a/docs/api/python.md b/docs/api/python.md
@@ -415,13 +415,14 @@ class KerasCallback(tf.keras.callbacks.Callback)
 ### \_\_init\_\_
 
 ```python
- | __init__(backend_root="http://localhost:3030", disk_save_format="h5", remote_save_format="tfjs", model_checkpoint_freq=None, base_log_dir="marcelle-logs", run_params={})
+ | __init__(name, backend_root="http://localhost:3030", disk_save_format="h5", remote_save_format="tfjs", model_checkpoint_freq=None, base_log_dir="marcelle-logs", run_params={})
 ```
 
 A Keras Callback to store training information in a Marcelle backend and locally.
 
 **Arguments**:
 
+- `name` _str_ - The base name for the run.
 - `backend_root` _str, optional_ - The backend's root URL.
   Defaults to "http://localhost:3030".
 - `disk_save_format` _str, optional_ - Format used to store the models locally.
@@ -485,13 +486,14 @@ class Writer()
 ### \_\_init\_\_
 
 ```python
- | __init__(backend_root="http://localhost:3030", disk_save_format="h5", remote_save_format="tfjs", base_log_dir="marcelle-logs", source="keras")
+ | __init__(name, backend_root="http://localhost:3030", disk_save_format="h5", remote_save_format="tfjs", base_log_dir="marcelle-logs", source="keras")
 ```
 
 The Writer class allows to save training information locally and to a backend
 
 **Arguments**:
 
+- `name` _str_ - The base name for the run.
 - `backend_root` _str, optional_ - The backend's root URL.
   Defaults to "http://localhost:3030".
 - `disk_save_format` _str, optional_ - Format used to store the models locally.