docs: examples for datasets (#1203)

### Summary of Changes - Adds examples in the documentation for all datasets --------- Co-authored-by: Tim Locke <tlc@objektkultur.de> Co-authored-by: Lars Reimann <mail@larsreimann.com>
Safe-DS · Jun 17, 2024 · cedbdfb · cedbdfb
1 parent 288e67c
commit cedbdfb
Show file tree

Hide file tree

Showing 6 changed files with 218 additions and 28 deletions.
diff --git a/docs/api/safeds/data/labeled/containers/ImageDataset.md b/docs/api/safeds/data/labeled/containers/ImageDataset.md
@@ -10,20 +10,31 @@ A Dataset for ImageLists as input and ImageLists, Tables or Columns as output.
 
 | Name | Type | Description | Default |
 |------|------|-------------|---------|
-| `inputData` | [`ImageList`][safeds.data.image.containers.ImageList] | the input ImageList | - |
-| `outputData` | `#!sds O` | the output data | - |
-| `batchSize` | [`Int`][safeds.lang.Int] | the batch size used for training | `#!sds 1` |
-| `shuffle` | [`Boolean`][safeds.lang.Boolean] | weather the data should be shuffled after each epoch of training | `#!sds false` |
+| `inputData` | [`ImageList`][safeds.data.image.containers.ImageList] | The input ImageList | - |
+| `outputData` | `#!sds O` | The output data | - |
+| `batchSize` | [`Int`][safeds.lang.Int] | The batch size used for training | `#!sds 1` |
+| `shuffle` | [`Boolean`][safeds.lang.Boolean] | Whether the data should be shuffled after each epoch of training | `#!sds false` |
 
 **Type parameters:**
 
 | Name | Upper Bound | Description | Default |
 |------|-------------|-------------|---------|
 | `O` | [`Any?`][safeds.lang.Any] | - | - |
 
+**Examples:**
+
+```sds hl_lines="5"
+pipeline example {
+    val image = Image.fromFile("example.png");
+    val imageList = ImageList.fromImages([image]);
+    val labels = Column("label", ["example"]);
+    val dataset = ImageDataset(imageList, labels);
+}
+```
+
 ??? quote "Stub code in `ImageDataset.sdsstub`"
 
-    ```sds linenums="17"
+    ```sds linenums="25"
     class ImageDataset<out O>(
         @PythonName("input_data") inputData: ImageList,
         @PythonName("output_data") outputData: O,
@@ -43,6 +54,15 @@ A Dataset for ImageLists as input and ImageLists, Tables or Columns as output.
          * Get the input data of this dataset.
          *
          * @result input the input data of this dataset
+         *
+         * @example
+         * pipeline example {
+         *     val image = Image.fromFile("example.png");
+         *     val imageList = ImageList.fromImages([image]);
+         *     val labels = Column("label", ["example"]);
+         *     val dataset = ImageDataset(imageList, labels);
+         *     val input = dataset.getInput();
+         * }
          */
         @Pure
         @PythonName("get_input")
@@ -52,6 +72,15 @@ A Dataset for ImageLists as input and ImageLists, Tables or Columns as output.
          * Get the output data of this dataset.
          *
          * @result output the output data of this dataset
+         *
+         * @example
+         * pipeline example {
+         *     val image = Image.fromFile("example.png");
+         *     val imageList = ImageList.fromImages([image]);
+         *     val labels = Column("label", ["example"]);
+         *     val dataset = ImageDataset(imageList, labels);
+         *     val output = dataset.getOutput();
+         * }
          */
         @Pure
         @PythonName("get_output")
@@ -63,6 +92,15 @@ A Dataset for ImageLists as input and ImageLists, Tables or Columns as output.
          * The original dataset list is not modified.
          *
          * @result imageDataset the shuffled `ImageDataset`
+         *
+         * @example
+         * pipeline example {
+         *     val image = Image.fromFile("example.png");
+         *     val imageList = ImageList.fromImages([image]);
+         *     val labels = Column("label", ["example"]);
+         *     val dataset = ImageDataset(imageList, labels);
+         *     val shuffledDataset = dataset.shuffle();
+         * }
          */
         @Pure
         fun shuffle() -> imageDataset: ImageDataset<O>
@@ -91,9 +129,21 @@ Get the input data of this dataset.
 |------|------|-------------|
 | `input` | [`ImageList`][safeds.data.image.containers.ImageList] | the input data of this dataset |
 
+**Examples:**
+
+```sds hl_lines="6"
+pipeline example {
+    val image = Image.fromFile("example.png");
+    val imageList = ImageList.fromImages([image]);
+    val labels = Column("label", ["example"]);
+    val dataset = ImageDataset(imageList, labels);
+    val input = dataset.getInput();
+}
+```
+
 ??? quote "Stub code in `ImageDataset.sdsstub`"
 
-    ```sds linenums="37"
+    ```sds linenums="54"
     @Pure
     @PythonName("get_input")
     fun getInput() -> input: ImageList
@@ -109,9 +159,21 @@ Get the output data of this dataset.
 |------|------|-------------|
 | `output` | `#!sds O` | the output data of this dataset |
 
+**Examples:**
+
+```sds hl_lines="6"
+pipeline example {
+    val image = Image.fromFile("example.png");
+    val imageList = ImageList.fromImages([image]);
+    val labels = Column("label", ["example"]);
+    val dataset = ImageDataset(imageList, labels);
+    val output = dataset.getOutput();
+}
+```
+
 ??? quote "Stub code in `ImageDataset.sdsstub`"
 
-    ```sds linenums="46"
+    ```sds linenums="72"
     @Pure
     @PythonName("get_output")
     fun getOutput() -> output: O
@@ -129,9 +191,21 @@ The original dataset list is not modified.
 |------|------|-------------|
 | `imageDataset` | [`ImageDataset<O>`][safeds.data.labeled.containers.ImageDataset] | the shuffled `ImageDataset` |
 
+**Examples:**
+
+```sds hl_lines="6"
+pipeline example {
+    val image = Image.fromFile("example.png");
+    val imageList = ImageList.fromImages([image]);
+    val labels = Column("label", ["example"]);
+    val dataset = ImageDataset(imageList, labels);
+    val shuffledDataset = dataset.shuffle();
+}
+```
+
 ??? quote "Stub code in `ImageDataset.sdsstub`"
 
-    ```sds linenums="57"
+    ```sds linenums="92"
     @Pure
     fun shuffle() -> imageDataset: ImageDataset<O>
     ```
diff --git a/docs/api/safeds/data/labeled/containers/TabularDataset.md b/docs/api/safeds/data/labeled/containers/TabularDataset.md
@@ -66,6 +66,19 @@ pipeline example {
          * Return a table containing all columns of the tabular dataset.
          *
          * @result table A table containing all columns of the tabular dataset.
+         *
+         * @example
+         * pipeline example {
+         *     val table = Table(
+         *         {
+         *             "id": [1, 2, 3],
+         *             "feature": [4, 5, 6],
+         *             "target": [1, 2, 3],
+         *         },
+         *     );
+         *     val tabularDataset = table.toTabularDataset(targetName="target", extraNames=["id"]);
+         *     val result = tabularDataset.toTable();
+         * }
          */
         @Pure
         @PythonName("to_table")
@@ -103,9 +116,25 @@ Return a table containing all columns of the tabular dataset.
 |------|------|-------------|
 | `table` | [`Table`][safeds.data.tabular.containers.Table] | A table containing all columns of the tabular dataset. |
 
+**Examples:**
+
+```sds hl_lines="10"
+pipeline example {
+    val table = Table(
+        {
+            "id": [1, 2, 3],
+            "feature": [4, 5, 6],
+            "target": [1, 2, 3],
+        },
+    );
+    val tabularDataset = table.toTabularDataset(targetName="target", extraNames=["id"]);
+    val result = tabularDataset.toTable();
+}
+```
+
 ??? quote "Stub code in `TabularDataset.sdsstub`"
 
-    ```sds linenums="61"
+    ```sds linenums="74"
     @Pure
     @PythonName("to_table")
     fun toTable() -> table: Table

diff --git a/docs/api/safeds/data/labeled/containers/TimeSeriesDataset.md b/docs/api/safeds/data/labeled/containers/TimeSeriesDataset.md
@@ -23,13 +23,13 @@ Unlike a TabularDataset, a TimeSeries needs to contain one target and one time c
 
 ```sds hl_lines="2"
 pipeline example {
-    // dataset = TimeSeriesDataset(
-    //     {"id": [1, 2, 3], "feature": [4, 5, 6], "target": [1, 2, 3], "error":[0,0,1]},
-    //     target_name="target",
-    //     time_name = "id",
-    //     window_size=1,
-    //     extra_names=["error"],
-    // )
+    val dataset = TimeSeriesDataset(
+        {"time": [1, 2, 3], "feature": [4, 5, 6], "target": [1, 2, 3], "id": [1, 2, 3]},
+        targetName = "target",
+        timeName = "time",
+        windowSize = 1,
+        extraNames = ["id"]
+    );
 }
 ```
 
@@ -77,6 +77,18 @@ pipeline example {
          * The original `TimeSeriesDataset` is not modified.
          *
          * @result table A table containing the feature columns, the target column, the time column and the extra columns.
+         *
+         * @example
+         * pipeline example {
+         *     val dataset = TimeSeriesDataset(
+         *         {"time": [1, 2, 3], "feature": [4, 5, 6], "target": [1, 2, 3], "id": [1, 2, 3]},
+         *         targetName = "target",
+         *         timeName = "time",
+         *         windowSize = 1,
+         *         extraNames = ["id"]
+         *     );
+         *     val result = dataset.toTable();
+         * }
          */
         @Pure
         @PythonName("to_table")
@@ -134,9 +146,24 @@ The original `TimeSeriesDataset` is not modified.
 |------|------|-------------|
 | `table` | [`Table`][safeds.data.tabular.containers.Table] | A table containing the feature columns, the target column, the time column and the extra columns. |
 
+**Examples:**
+
+```sds hl_lines="9"
+pipeline example {
+    val dataset = TimeSeriesDataset(
+        {"time": [1, 2, 3], "feature": [4, 5, 6], "target": [1, 2, 3], "id": [1, 2, 3]},
+        targetName = "target",
+        timeName = "time",
+        windowSize = 1,
+        extraNames = ["id"]
+    );
+    val result = dataset.toTable();
+}
+```
+
 ??? quote "Stub code in `TimeSeriesDataset.sdsstub`"
 
-    ```sds linenums="72"
+    ```sds linenums="84"
     @Pure
     @PythonName("to_table")
     fun toTable() -> table: Table

diff --git a/...s/safe-ds-lang/src/resources/builtins/safeds/data/labeled/containers/ImageDataset.sdsstub b/...s/safe-ds-lang/src/resources/builtins/safeds/data/labeled/containers/ImageDataset.sdsstub
@@ -8,10 +8,18 @@ from safeds.data.tabular.containers import Table
 /**
  * A Dataset for ImageLists as input and ImageLists, Tables or Columns as output.
  *
- * @param inputData the input ImageList
- * @param outputData the output data
- * @param batchSize the batch size used for training
- * @param shuffle weather the data should be shuffled after each epoch of training
+ * @param inputData The input ImageList
+ * @param outputData The output data
+ * @param batchSize The batch size used for training
+ * @param shuffle Whether the data should be shuffled after each epoch of training
+ *
+ * @example
+ * pipeline example {
+ *     val image = Image.fromFile("example.png");
+ *     val imageList = ImageList.fromImages([image]);
+ *     val labels = Column("label", ["example"]);
+ *     val dataset = ImageDataset(imageList, labels);
+ * }
  */
 @Experimental
 class ImageDataset<out O>(
@@ -33,6 +41,15 @@ class ImageDataset<out O>(
      * Get the input data of this dataset.
      *
      * @result input the input data of this dataset
+     *
+     * @example
+     * pipeline example {
+     *     val image = Image.fromFile("example.png");
+     *     val imageList = ImageList.fromImages([image]);
+     *     val labels = Column("label", ["example"]);
+     *     val dataset = ImageDataset(imageList, labels);
+     *     val input = dataset.getInput();
+     * }
      */
     @Pure
     @PythonName("get_input")
@@ -42,6 +59,15 @@ class ImageDataset<out O>(
      * Get the output data of this dataset.
      *
      * @result output the output data of this dataset
+     *
+     * @example
+     * pipeline example {
+     *     val image = Image.fromFile("example.png");
+     *     val imageList = ImageList.fromImages([image]);
+     *     val labels = Column("label", ["example"]);
+     *     val dataset = ImageDataset(imageList, labels);
+     *     val output = dataset.getOutput();
+     * }
      */
     @Pure
     @PythonName("get_output")
@@ -53,6 +79,15 @@ class ImageDataset<out O>(
      * The original dataset list is not modified.
      *
      * @result imageDataset the shuffled `ImageDataset`
+     *
+     * @example
+     * pipeline example {
+     *     val image = Image.fromFile("example.png");
+     *     val imageList = ImageList.fromImages([image]);
+     *     val labels = Column("label", ["example"]);
+     *     val dataset = ImageDataset(imageList, labels);
+     *     val shuffledDataset = dataset.shuffle();
+     * }
      */
     @Pure
     fun shuffle() -> imageDataset: ImageDataset<O>

diff --git a/...safe-ds-lang/src/resources/builtins/safeds/data/labeled/containers/TabularDataset.sdsstub b/...safe-ds-lang/src/resources/builtins/safeds/data/labeled/containers/TabularDataset.sdsstub
@@ -57,6 +57,19 @@ class TabularDataset(
      * Return a table containing all columns of the tabular dataset.
      *
      * @result table A table containing all columns of the tabular dataset.
+     *
+     * @example
+     * pipeline example {
+     *     val table = Table(
+     *         {
+     *             "id": [1, 2, 3],
+     *             "feature": [4, 5, 6],
+     *             "target": [1, 2, 3],
+     *         },
+     *     );
+     *     val tabularDataset = table.toTabularDataset(targetName="target", extraNames=["id"]);
+     *     val result = tabularDataset.toTable();
+     * }
      */
     @Pure
     @PythonName("to_table")

diff --git a/...e-ds-lang/src/resources/builtins/safeds/data/labeled/containers/TimeSeriesDataset.sdsstub b/...e-ds-lang/src/resources/builtins/safeds/data/labeled/containers/TimeSeriesDataset.sdsstub
@@ -17,13 +17,13 @@ from safeds.data.tabular.containers import Table
  *
  * @example
  * pipeline example {
- *     // dataset = TimeSeriesDataset(
- *     //     {"id": [1, 2, 3], "feature": [4, 5, 6], "target": [1, 2, 3], "error":[0,0,1]},
- *     //     target_name="target",
- *     //     time_name = "id",
- *     //     window_size=1,
- *     //     extra_names=["error"],
- *     // )
+ *     val dataset = TimeSeriesDataset(
+ *         {"time": [1, 2, 3], "feature": [4, 5, 6], "target": [1, 2, 3], "id": [1, 2, 3]},
+ *         targetName = "target",
+ *         timeName = "time",
+ *         windowSize = 1,
+ *         extraNames = ["id"]
+ *     );
  * }
  */
 @Experimental
@@ -68,6 +68,18 @@ class TimeSeriesDataset(
      * The original `TimeSeriesDataset` is not modified.
      *
      * @result table A table containing the feature columns, the target column, the time column and the extra columns.
+     *
+     * @example
+     * pipeline example {
+     *     val dataset = TimeSeriesDataset(
+     *         {"time": [1, 2, 3], "feature": [4, 5, 6], "target": [1, 2, 3], "id": [1, 2, 3]},
+     *         targetName = "target",
+     *         timeName = "time",
+     *         windowSize = 1,
+     *         extraNames = ["id"]
+     *     );
+     *     val result = dataset.toTable();
+     * }
      */
     @Pure
     @PythonName("to_table")