feat: categorize API elements (#1263)

### Summary of Changes Modifies the language stubs in preparation for the Custom Editor/Visualization PR #1243. Defines/Adjusts the DataScienceCategories and assigns them to a sample amount of functions and classes from the Safe-Ds language. --------- Co-authored-by: Lars Reimann <mail@larsreimann.com>
Safe-DS · Nov 14, 2024 · d0d971e · d0d971e
1 parent 011ba31
commit d0d971e
Show file tree

Hide file tree

Showing 40 changed files with 196 additions and 10 deletions.
diff --git a/packages/safe-ds-lang/src/resources/builtins/safeds/data/image/containers/Image.sdsstub b/packages/safe-ds-lang/src/resources/builtins/safeds/data/image/containers/Image.sdsstub
@@ -43,6 +43,7 @@ class Image {
      */
     @Impure([ImpurityReason.FileReadFromParameterizedPath("path")])
     @PythonName("from_file")
+    @Category(DataScienceCategory.DataImport)
     static fun fromFile(
         path: String
     ) -> image: Image
@@ -60,6 +61,7 @@ class Image {
      */
     @Impure([ImpurityReason.FileWriteToParameterizedPath("path")])
     @PythonName("to_jpeg_file")
+    @Category(DataScienceCategory.DataExport)
     fun toJpegFile(
         path: String
     )
@@ -77,6 +79,7 @@ class Image {
      */
     @Impure([ImpurityReason.FileWriteToParameterizedPath("path")])
     @PythonName("to_png_file")
+    @Category(DataScienceCategory.DataExport)
     fun toPngFile(
         path: String
     )
@@ -98,6 +101,7 @@ class Image {
      */
     @Pure
     @PythonName("change_channel")
+    @Category(DataScienceCategory.DataProcessingQImage)
     fun changeChannel(
         channel: Int
     ) -> newImage: Image
@@ -119,6 +123,7 @@ class Image {
      * }
      */
     @Pure
+    @Category(DataScienceCategory.DataProcessingQImage)
     fun resize(
         @PythonName("new_width") const newWidth: Int,
         @PythonName("new_height") const newHeight: Int
@@ -145,6 +150,7 @@ class Image {
      */
     @Pure
     @PythonName("convert_to_grayscale")
+    @Category(DataScienceCategory.DataProcessingQImage)
     fun convertToGrayscale() -> newImage: Image
 
     /**
@@ -166,6 +172,7 @@ class Image {
      * }
      */
     @Pure
+    @Category(DataScienceCategory.DataProcessingQImage)
     fun crop(
         const x: Int,
         const y: Int,
@@ -193,6 +200,7 @@ class Image {
      */
     @Pure
     @PythonName("flip_vertically")
+    @Category(DataScienceCategory.DataProcessingQImage)
     fun flipVertically() -> newImage: Image
 
     /**
@@ -210,6 +218,7 @@ class Image {
      */
     @Pure
     @PythonName("flip_horizontally")
+    @Category(DataScienceCategory.DataProcessingQImage)
     fun flipHorizontally() -> newImage: Image
 
     /**
@@ -233,6 +242,7 @@ class Image {
      */
     @Pure
     @PythonName("adjust_brightness")
+    @Category(DataScienceCategory.DataProcessingQImage)
     fun adjustBrightness(
         const factor: Float
     ) -> newImage: Image where {
@@ -256,6 +266,7 @@ class Image {
      */
     @Pure
     @PythonName("add_noise")
+    @Category(DataScienceCategory.DataProcessingQImage)
     fun addNoise(
         @PythonName("standard_deviation") const standardDeviation: Float
     ) -> newImage: Image where {
@@ -282,6 +293,7 @@ class Image {
      */
     @Pure
     @PythonName("adjust_contrast")
+    @Category(DataScienceCategory.DataProcessingQImage)
     fun adjustContrast(
         const factor: Float
     ) -> newImage: Image where {
@@ -308,6 +320,7 @@ class Image {
      */
     @Pure
     @PythonName("adjust_color_balance")
+    @Category(DataScienceCategory.DataProcessingQImage)
     fun adjustColorBalance(
         const factor: Float
     ) -> newImage: Image where {
@@ -331,6 +344,7 @@ class Image {
      * }
      */
     @Pure
+    @Category(DataScienceCategory.DataProcessingQImage)
     fun blur(
         const radius: Int
     ) -> newImage: Image where {
@@ -356,6 +370,7 @@ class Image {
      * }
      */
     @Pure
+    @Category(DataScienceCategory.DataProcessingQImage)
     fun sharpen(
         const factor: Float
     ) -> newImage: Image where {
@@ -377,6 +392,7 @@ class Image {
      */
     @Pure
     @PythonName("invert_colors")
+    @Category(DataScienceCategory.DataProcessingQImage)
     fun invertColors() -> newImage: Image
 
     /**
@@ -394,6 +410,7 @@ class Image {
      */
     @Pure
     @PythonName("rotate_right")
+    @Category(DataScienceCategory.DataProcessingQImage)
     fun rotateRight() -> newImage: Image
 
     /**
@@ -411,6 +428,7 @@ class Image {
      */
     @Pure
     @PythonName("rotate_left")
+    @Category(DataScienceCategory.DataProcessingQImage)
     fun rotateLeft() -> newImage: Image
 
     /**
@@ -428,5 +446,6 @@ class Image {
      */
     @Pure
     @PythonName("find_edges")
+    @Category(DataScienceCategory.DataProcessingQImage)
     fun findEdges() -> newImage: Image
 }
diff --git a/packages/safe-ds-lang/src/resources/builtins/safeds/data/image/containers/ImageList.sdsstub b/packages/safe-ds-lang/src/resources/builtins/safeds/data/image/containers/ImageList.sdsstub
@@ -49,6 +49,7 @@ class ImageList {
      */
     @Pure
     @PythonName("from_images")
+    @Category(DataScienceCategory.DataImport)
     static fun fromImages(
         images: List<Image>
     ) -> imageList: ImageList
@@ -64,6 +65,7 @@ class ImageList {
      */
     @Impure([ImpurityReason.FileReadFromParameterizedPath("path")])
     @PythonName("from_files")
+    @Category(DataScienceCategory.DataImport)
     static fun fromFiles(
         path: union<List<String>, String>
     ) -> imageList: ImageList
@@ -77,6 +79,7 @@ class ImageList {
      */
     @Pure
     @PythonName("get_image")
+    @Category(DataScienceCategory.UtilitiesQImage)
     fun getImage(
         index: Int
     ) -> image: Image
@@ -91,6 +94,7 @@ class ImageList {
      * @result indices all occurrences of the image
      */
     @Pure
+    @Category(DataScienceCategory.UtilitiesQImage)
     fun index(
         image: Image
     ) -> indices: List<Int>
@@ -104,6 +108,7 @@ class ImageList {
      */
     @Pure
     @PythonName("has_image")
+    @Category(DataScienceCategory.UtilitiesQImage)
     fun hasImage(
         image: Image
     ) -> hasImage: Boolean
@@ -115,6 +120,7 @@ class ImageList {
      */
     @Impure([ImpurityReason.FileWriteToParameterizedPath("path")])
     @PythonName("to_jpeg_files")
+    @Category(DataScienceCategory.DataExport)
     fun toJpegFiles(
         path: union<List<String>, String>
     )
@@ -126,6 +132,7 @@ class ImageList {
      */
     @Impure([ImpurityReason.FileWriteToParameterizedPath("path")])
     @PythonName("to_png_files")
+    @Category(DataScienceCategory.DataExport)
     fun toPngFiles(
         path: union<List<String>, String>
     )
@@ -139,6 +146,7 @@ class ImageList {
      */
     @Pure
     @PythonName("to_images")
+    @Category(DataScienceCategory.UtilitiesQConversion)
     fun toImages(
         indices: List<Int>? = null
     ) -> images: List<Image>

diff --git a/packages/safe-ds-lang/src/resources/builtins/safeds/data/tabular/containers/Column.sdsstub b/packages/safe-ds-lang/src/resources/builtins/safeds/data/tabular/containers/Column.sdsstub
@@ -15,6 +15,7 @@ from safeds.data.tabular.typing import DataType
  *     val column = Column("test", [1, 2, 3]);
  * }
  */
+@Category(DataScienceCategory.BasicElement)
 class Column<out T = Any?>(
     name: String,
     data: List<T> = []
@@ -130,6 +131,7 @@ class Column<out T = Any?>(
      * }
      */
     @Pure
+    @Category(DataScienceCategory.DataExplorationQGeneral)
     fun all(
         predicate: (cell: Cell<T>) -> satisfiesPredicate: Cell<Boolean?>,
         @PythonName("ignore_unknown") ignoreUnknown: Boolean = true,
@@ -173,6 +175,7 @@ class Column<out T = Any?>(
      * }
      */
     @Pure
+    @Category(DataScienceCategory.DataExplorationQGeneral)
     fun any(
         predicate: (cell: Cell<T>) -> satisfiesPredicate: Cell<Boolean?>,
         @PythonName("ignore_unknown") ignoreUnknown: Boolean = true,
@@ -211,6 +214,7 @@ class Column<out T = Any?>(
      * }
      */
     @Pure
+    @Category(DataScienceCategory.DataExplorationQGeneral)
     fun countIf(
         predicate: (cell: Cell<T>) -> satisfiesPredicate: Cell<Boolean?>,
         @PythonName("ignore_unknown") ignoreUnknown: Boolean = true,
@@ -254,6 +258,7 @@ class Column<out T = Any?>(
      * }
      */
     @Pure
+    @Category(DataScienceCategory.DataExplorationQGeneral)
     fun none(
         predicate: (cell: Cell<T>) -> satisfiesPredicate: Cell<Boolean?>,
         @PythonName("ignore_unknown") ignoreUnknown: Boolean = true,
@@ -276,6 +281,7 @@ class Column<out T = Any?>(
      * }
      */
     @Pure
+    @Category(DataScienceCategory.DataProcessingQColumn)
     fun rename(
         @PythonName("new_name") newName: String
     ) -> renamedColumn: Column<T>
@@ -297,6 +303,7 @@ class Column<out T = Any?>(
      * }
      */
     @Pure
+    @Category(DataScienceCategory.DataProcessingQColumn)
     fun transform<R>(
         transformer: (cell: Cell<T>) -> transformedCell: Cell<R>
     ) -> transformedColumn: Column<R>
@@ -346,6 +353,7 @@ class Column<out T = Any?>(
      */
     @Pure
     @PythonName("correlation_with")
+    @Category(DataScienceCategory.DataExplorationQMetric)
     fun correlationWith(
         other: Column<Any>
     ) -> correlation: Float
@@ -365,6 +373,7 @@ class Column<out T = Any?>(
      */
     @Pure
     @PythonName("distinct_value_count")
+    @Category(DataScienceCategory.DataExplorationQMetric)
     fun distinctValueCount(
         @PythonName("ignore_missing_values") ignoreMissingValues: Boolean = true
     ) -> distinctValueCount: Int
@@ -393,6 +402,7 @@ class Column<out T = Any?>(
      * }
      */
     @Pure
+    @Category(DataScienceCategory.DataExplorationQMetric)
     fun idness() -> idness: Float
 
     /**
@@ -407,6 +417,7 @@ class Column<out T = Any?>(
      * }
      */
     @Pure
+    @Category(DataScienceCategory.DataExplorationQMetric)
     fun max() -> max: T?
 
     /**
@@ -423,6 +434,7 @@ class Column<out T = Any?>(
      * }
      */
     @Pure
+    @Category(DataScienceCategory.DataExplorationQMetric)
     fun mean() -> mean: T
 
     /**
@@ -440,6 +452,7 @@ class Column<out T = Any?>(
      * }
      */
     @Pure
+    @Category(DataScienceCategory.DataExplorationQMetric)
     fun median() -> median: T
 
     /**
@@ -454,6 +467,7 @@ class Column<out T = Any?>(
      * }
      */
     @Pure
+    @Category(DataScienceCategory.DataExplorationQMetric)
     fun min() -> min: T?
 
     /**
@@ -469,6 +483,7 @@ class Column<out T = Any?>(
      */
     @Pure
     @PythonName("missing_value_count")
+    @Category(DataScienceCategory.DataExplorationQMetric)
     fun missingValueCount() -> missingValueCount: Int
 
     /**
@@ -490,6 +505,7 @@ class Column<out T = Any?>(
      */
     @Pure
     @PythonName("missing_value_ratio")
+    @Category(DataScienceCategory.DataExplorationQMetric)
     fun missingValueRatio() -> missingValueRatio: Float
 
     /**
@@ -509,6 +525,7 @@ class Column<out T = Any?>(
      * }
      */
     @Pure
+    @Category(DataScienceCategory.DataExplorationQMetric)
     fun mode(
         @PythonName("ignore_missing_values") ignoreMissingValues: Boolean = true,
     ) -> mode: List<T?>
@@ -531,6 +548,7 @@ class Column<out T = Any?>(
      * }
      */
     @Pure
+    @Category(DataScienceCategory.DataExplorationQMetric)
     fun stability() -> stability: Float
 
     /**
@@ -549,6 +567,7 @@ class Column<out T = Any?>(
      */
     @Pure
     @PythonName("standard_deviation")
+    @Category(DataScienceCategory.DataExplorationQMetric)
     fun standardDeviation() -> standardDeviation: Float
 
     /**
@@ -566,6 +585,7 @@ class Column<out T = Any?>(
      * }
      */
     @Pure
+    @Category(DataScienceCategory.DataExplorationQMetric)
     fun variance() -> variance: Float
 
     /**
@@ -581,6 +601,7 @@ class Column<out T = Any?>(
      */
     @Pure
     @PythonName("to_list")
+    @Category(DataScienceCategory.UtilitiesQConversion)
     fun toList() -> values: List<T>
 
     /**
@@ -597,5 +618,6 @@ class Column<out T = Any?>(
      */
     @Pure
     @PythonName("to_table")
+    @Category(DataScienceCategory.UtilitiesQConversion)
     fun toTable() -> table: Table
 }