polars-df 0.13.0 → 0.15.0

data/lib/polars/list_name_space.rb

@@ -133,6 +133,17 @@ module Polars
     # Sum all the arrays in the list.
     #
     # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new("values", [[1], [2, 3]])
+    #   s.list.sum
+    #   # =>
+    #   # shape: (2,)
+    #   # Series: 'values' [i64]
+    #   # [
+    #   #         1
+    #   #         5
+    #   # ]
     def sum
       super
     end
@@ -140,6 +151,17 @@ module Polars
     # Compute the max value of the arrays in the list.
     #
     # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new("values", [[4, 1], [2, 3]])
+    #   s.list.max
+    #   # =>
+    #   # shape: (2,)
+    #   # Series: 'values' [i64]
+    #   # [
+    #   #         4
+    #   #         3
+    #   # ]
     def max
       super
     end
@@ -147,6 +169,17 @@ module Polars
     # Compute the min value of the arrays in the list.
     #
     # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new("values", [[4, 1], [2, 3]])
+    #   s.list.min
+    #   # =>
+    #   # shape: (2,)
+    #   # Series: 'values' [i64]
+    #   # [
+    #   #         1
+    #   #         2
+    #   # ]
     def min
       super
     end
@@ -154,6 +187,17 @@ module Polars
     # Compute the mean value of the arrays in the list.
     #
     # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new("values", [[3, 1], [3, 3]])
+    #   s.list.mean
+    #   # =>
+    #   # shape: (2,)
+    #   # Series: 'values' [f64]
+    #   # [
+    #   #         2.0
+    #   #         3.0
+    #   # ]
     def mean
       super
     end
@@ -161,6 +205,27 @@ module Polars
     # Sort the arrays in the list.
     #
     # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new("a", [[3, 2, 1], [9, 1, 2]])
+    #   s.list.sort
+    #   # =>
+    #   # shape: (2,)
+    #   # Series: 'a' [list[i64]]
+    #   # [
+    #   #         [1, 2, 3]
+    #   #         [1, 2, 9]
+    #   # ]
+    #
+    # @example
+    #   s.list.sort(reverse: true)
+    #   # =>
+    #   # shape: (2,)
+    #   # Series: 'a' [list[i64]]
+    #   # [
+    #   #         [3, 2, 1]
+    #   #         [9, 2, 1]
+    #   # ]
     def sort(reverse: false)
       super
     end
@@ -168,6 +233,17 @@ module Polars
     # Reverse the arrays in the list.
     #
     # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new("a", [[3, 2, 1], [9, 1, 2]])
+    #   s.list.reverse
+    #   # =>
+    #   # shape: (2,)
+    #   # Series: 'a' [list[i64]]
+    #   # [
+    #   #         [1, 2, 3]
+    #   #         [2, 1, 9]
+    #   # ]
     def reverse
       super
     end
@@ -175,6 +251,17 @@ module Polars
     # Get the unique/distinct values in the list.
     #
     # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new("a", [[1, 1, 2], [2, 3, 3]])
+    #   s.list.unique()
+    #   # =>
+    #   # shape: (2,)
+    #   # Series: 'a' [list[i64]]
+    #   # [
+    #   #         [1, 2]
+    #   #         [2, 3]
+    #   # ]
     def unique
       super
     end
@@ -185,6 +272,18 @@ module Polars
     #   Columns to concat into a List Series
     #
     # @return [Series]
+    #
+    # @example
+    #   s1 = Polars::Series.new("a", [["a", "b"], ["c"]])
+    #   s2 = Polars::Series.new("b", [["c"], ["d", nil]])
+    #   s1.list.concat(s2)
+    #   # =>
+    #   # shape: (2,)
+    #   # Series: 'a' [list[str]]
+    #   # [
+    #   #         ["a", "b", "c"]
+    #   #         ["c", "d", null]
+    #   # ]
     def concat(other)
       super
     end
@@ -203,6 +302,18 @@ module Polars
     #   false -> raise an error
     #
     # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new("a", [[3, 2, 1], [], [1, 2]])
+    #   s.list.get(0, null_on_oob: true)
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: 'a' [i64]
+    #   # [
+    #   #         3
+    #   #         null
+    #   #         1
+    #   # ]
     def get(index, null_on_oob: false)
       super
     end
@@ -240,6 +351,18 @@ module Polars
     # Get the first value of the sublists.
     #
     # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new("a", [[3, 2, 1], [], [1, 2]])
+    #   s.list.first
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: 'a' [i64]
+    #   # [
+    #   #         3
+    #   #         null
+    #   #         1
+    #   # ]
     def first
       super
     end
@@ -247,6 +370,18 @@ module Polars
     # Get the last value of the sublists.
     #
     # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new("a", [[3, 2, 1], [], [1, 2]])
+    #   s.list.last
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: 'a' [i64]
+    #   # [
+    #   #         1
+    #   #         null
+    #   #         2
+    #   # ]
     def last
       super
     end
@@ -257,6 +392,18 @@ module Polars
     #   Item that will be checked for membership.
     #
     # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new("a", [[3, 2, 1], [], [1, 2]])
+    #   s.list.contains(1)
+    #   # =>
+    #   # shape: (3,)
+    #   # Series: 'a' [bool]
+    #   # [
+    #   #         true
+    #   #         false
+    #   #         true
+    #   # ]
     def contains(item)
       super
     end
@@ -264,6 +411,17 @@ module Polars
     # Retrieve the index of the minimal value in every sublist.
     #
     # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new("a", [[1, 2], [2, 1]])
+    #   s.list.arg_min
+    #   # =>
+    #   # shape: (2,)
+    #   # Series: 'a' [u32]
+    #   # [
+    #   #         0
+    #   #         1
+    #   # ]
     def arg_min
       super
     end
@@ -271,6 +429,17 @@ module Polars
     # Retrieve the index of the maximum value in every sublist.
     #
     # @return [Series]
+    #
+    # @example
+    #   s = Polars::Series.new("a", [[1, 2], [2, 1]])
+    #   s.list.arg_max
+    #   # =>
+    #   # shape: (2,)
+    #   # Series: 'a' [u32]
+    #   # [
+    #   #         1
+    #   #         0
+    #   # ]
     def arg_max
       super
     end