View Source Explorer.Series (Explorer v0.3.1)

The Series struct and API.

A series can be of the following data types:

  • :float - 64-bit floating point number
  • :integer - 64-bit signed integer
  • :boolean - Boolean
  • :string - UTF-8 encoded binary
  • :date - Date type that unwraps to Elixir.Date
  • :datetime - DateTime type that unwraps to Elixir.NaiveDateTime

A series must consist of a single data type only. Series are nullable, but may not consist only of nils.

Many functions only apply to certain dtypes. Where that is the case, you'll find a Supported dtypes section in the function documentation and the function will raise an ArgumentError if a series with an invalid dtype is used.

Link to this section Summary

Functions: Introspection

Returns the data type of the series.

Returns the size of the series.

Functions: Aggregation

Creates a new dataframe with unique values and the count of each.

Gets the maximum value of the series.

Gets the mean value of the series.

Gets the median value of the series.

Gets the minimum value of the series.

Returns the number of unique values in the series.

Gets the given quantile of the series.

Gets the standard deviation of the series.

Gets the sum of the series.

Gets the variance of the series.

Functions: Element-wise

Adds right to left, element-wise.

Checks equality between two entire series.

Returns a boolean mask of left and right, element-wise

Cast the series to another type.

Finds the first non-missing element at each position.

Divides left by right, element-wise.

Returns boolean mask of left == right, element-wise.

Returns boolean mask of left > right, element-wise.

Returns boolean mask of left >= right, element-wise.

Returns a mask of nil values.

Returns a mask of not nil values.

Returns boolean mask of left < right, element-wise.

Returns boolean mask of left <= right, element-wise.

Multiplies left and right, element-wise.

Returns boolean mask of left != right, element-wise.

Returns a boolean mask of left or right, element-wise

Returns a boolean mask with true where the 'peaks' (series max or min, default max) are.

Raises a numeric series to the power of the exponent.

Subtracts right from left, element-wise.

Functions: Transformation

Returns the indices that would sort the series.

Finds the first non-missing element at each position.

Concatenate one or more series.

Concatenate one or more series.

Returns the unique values of the series.

Returns the value of the series at the given index.

Returns the first element of the series.

Creates a new series from a list.

Converts a t:Nx.Tensor.t/0 to a series.

Returns the first N elements of the series.

Returns the last element of the series.

Filters a series with a mask.

Reverses the series order.

Returns a random sample of the series.

Returns the elements at the given indices as a new series.

Returns a slice of the series, with size elements starting at offset.

Sorts the series.

Returns the last N elements of the series.

Takes every nth value in this series, returned as a new series.

Converts a series to an enumerable.

Converts a series to a list.

Converts a series to a t:Nx.Tensor.t/0.

Returns an Explorer.Series where each element is the result of invoking fun on each corresponding element of series.

Returns the unique values of the series, but does not maintain order.

Functions: Window

Calculates the cumulative maximum of the series.

Calculates the cumulative minimum of the series.

Calculates the cumulative sum of the series.

Fill missing values with the given strategy. If a scalar value is provided instead of a strategy atom, nil will be replaced with that value. It must be of the same dtype as the series.

Calculate the rolling max, given a window size and optional list of weights.

Calculate the rolling mean, given a window size and optional list of weights.

Calculate the rolling min, given a window size and optional list of weights.

Calculate the rolling sum, given a window size and optional list of weights.

Link to this section Types

@type dtype() :: :integer | :float | :boolean | :string | :date | :datetime
@type lazy_t() :: %Explorer.Series{
  data: Explorer.Backend.LazySeries.t(),
  dtype: dtype()
}
@type t() :: %Explorer.Series{data: Explorer.Backend.Series.t(), dtype: dtype()}

Link to this section Functions: Introspection

@spec dtype(series :: t()) :: dtype()

Returns the data type of the series.

A series can be of the following data types:

  • :float - 64-bit floating point number
  • :integer - 64-bit signed integer
  • :boolean - Boolean
  • :string - UTF-8 encoded binary
  • :date - Date type that unwraps to Elixir.Date
  • :datetime - DateTime type that unwraps to Elixir.NaiveDateTime

examples

Examples

iex> s = Explorer.Series.from_list([1, 2, 3])
iex> Explorer.Series.dtype(s)
:integer

iex> s = Explorer.Series.from_list(["a", nil, "b", "c"])
iex> Explorer.Series.dtype(s)
:string
@spec size(series :: t()) :: integer()

Returns the size of the series.

examples

Examples

iex> s = Explorer.Series.from_list([~D[1999-12-31], ~D[1989-01-01]])
iex> Explorer.Series.size(s)
2

Link to this section Functions: Aggregation

Creates a new dataframe with unique values and the count of each.

In the context of lazy series - using DataFrame.*_with/2 functions -, count/1 is going to count the elements inside the same group. If no group is in use, then count is going to return the length of the series.

examples

Examples

iex> s = Explorer.Series.from_list(["a", "a", "b", "c", "c", "c"])
iex> Explorer.Series.count(s)
#Explorer.DataFrame<
  Polars[3 x 2]
  values string ["c", "a", "b"]
  counts integer [3, 2, 1]
>
@spec max(series :: t()) :: number() | Date.t() | NaiveDateTime.t()

Gets the maximum value of the series.

supported-dtypes

Supported dtypes

  • :integer
  • :float
  • :date
  • :datetime

examples

Examples

iex> s = Explorer.Series.from_list([1, 2, nil, 3])
iex> Explorer.Series.max(s)
3

iex> s = Explorer.Series.from_list([1.0, 2.0, nil, 3.0])
iex> Explorer.Series.max(s)
3.0

iex> s = Explorer.Series.from_list([~D[2021-01-01], ~D[1999-12-31]])
iex> Explorer.Series.max(s)
~D[2021-01-01]

iex> s = Explorer.Series.from_list([~N[2021-01-01 00:00:00], ~N[1999-12-31 00:00:00]])
iex> Explorer.Series.max(s)
~N[2021-01-01 00:00:00.000000]

iex> s = Explorer.Series.from_list(["a", "b", "c"])
iex> Explorer.Series.max(s)
** (ArgumentError) Explorer.Series.max/1 not implemented for dtype :string. Valid dtypes are [:integer, :float, :date, :datetime].
@spec mean(series :: t()) :: float()

Gets the mean value of the series.

supported-dtypes

Supported dtypes

  • :integer
  • :float

examples

Examples

iex> s = Explorer.Series.from_list([1, 2, nil, 3])
iex> Explorer.Series.mean(s)
2.0

iex> s = Explorer.Series.from_list([1.0, 2.0, nil, 3.0])
iex> Explorer.Series.mean(s)
2.0

iex> s = Explorer.Series.from_list([~D[2021-01-01], ~D[1999-12-31]])
iex> Explorer.Series.mean(s)
** (ArgumentError) Explorer.Series.mean/1 not implemented for dtype :date. Valid dtypes are [:integer, :float].
@spec median(series :: t()) :: float()

Gets the median value of the series.

supported-dtypes

Supported dtypes

  • :integer
  • :float

examples

Examples

iex> s = Explorer.Series.from_list([1, 2, nil, 3])
iex> Explorer.Series.median(s)
2.0

iex> s = Explorer.Series.from_list([1.0, 2.0, nil, 3.0])
iex> Explorer.Series.median(s)
2.0

iex> s = Explorer.Series.from_list([~D[2021-01-01], ~D[1999-12-31]])
iex> Explorer.Series.median(s)
** (ArgumentError) Explorer.Series.median/1 not implemented for dtype :date. Valid dtypes are [:integer, :float].
@spec min(series :: t()) :: number() | Date.t() | NaiveDateTime.t()

Gets the minimum value of the series.

supported-dtypes

Supported dtypes

  • :integer
  • :float
  • :date
  • :datetime

examples

Examples

iex> s = Explorer.Series.from_list([1, 2, nil, 3])
iex> Explorer.Series.min(s)
1

iex> s = Explorer.Series.from_list([1.0, 2.0, nil, 3.0])
iex> Explorer.Series.min(s)
1.0

iex> s = Explorer.Series.from_list([~D[2021-01-01], ~D[1999-12-31]])
iex> Explorer.Series.min(s)
~D[1999-12-31]

iex> s = Explorer.Series.from_list([~N[2021-01-01 00:00:00], ~N[1999-12-31 00:00:00]])
iex> Explorer.Series.min(s)
~N[1999-12-31 00:00:00.000000]

iex> s = Explorer.Series.from_list(["a", "b", "c"])
iex> Explorer.Series.min(s)
** (ArgumentError) Explorer.Series.min/1 not implemented for dtype :string. Valid dtypes are [:integer, :float, :date, :datetime].

Returns the number of unique values in the series.

examples

Examples

iex> s = Explorer.Series.from_list(["a", "b", "a", "b"])
iex> Explorer.Series.n_distinct(s)
2
Link to this function

quantile(series, quantile)

View Source
@spec quantile(series :: t(), quantile :: float()) :: any()

Gets the given quantile of the series.

supported-dtypes

Supported dtypes

  • :integer
  • :float
  • :date
  • :datetime

examples

Examples

iex> s = Explorer.Series.from_list([1, 2, nil, 3])
iex> Explorer.Series.quantile(s, 0.2)
1

iex> s = Explorer.Series.from_list([1.0, 2.0, nil, 3.0])
iex> Explorer.Series.quantile(s, 0.5)
2.0

iex> s = Explorer.Series.from_list([~D[2021-01-01], ~D[1999-12-31]])
iex> Explorer.Series.quantile(s, 0.5)
~D[2021-01-01]

iex> s = Explorer.Series.from_list([~N[2021-01-01 00:00:00], ~N[1999-12-31 00:00:00]])
iex> Explorer.Series.quantile(s, 0.5)
~N[2021-01-01 00:00:00.000000]

iex> s = Explorer.Series.from_list([true, false, true])
iex> Explorer.Series.quantile(s, 0.5)
** (ArgumentError) Explorer.Series.quantile/2 not implemented for dtype :boolean. Valid dtypes are [:integer, :float, :date, :datetime].
@spec std(series :: t()) :: float()

Gets the standard deviation of the series.

supported-dtypes

Supported dtypes

  • :integer
  • :float

examples

Examples

iex> s = Explorer.Series.from_list([1, 2, nil, 3])
iex> Explorer.Series.std(s)
1.0

iex> s = Explorer.Series.from_list([1.0, 2.0, nil, 3.0])
iex> Explorer.Series.std(s)
1.0

iex> s = Explorer.Series.from_list(["a", "b", "c"])
iex> Explorer.Series.std(s)
** (ArgumentError) Explorer.Series.std/1 not implemented for dtype :string. Valid dtypes are [:integer, :float].
@spec sum(series :: t()) :: number()

Gets the sum of the series.

supported-dtypes

Supported dtypes

  • :integer
  • :float
  • :boolean

examples

Examples

iex> s = Explorer.Series.from_list([1, 2, nil, 3])
iex> Explorer.Series.sum(s)
6

iex> s = Explorer.Series.from_list([1.0, 2.0, nil, 3.0])
iex> Explorer.Series.sum(s)
6.0

iex> s = Explorer.Series.from_list([true, false, true])
iex> Explorer.Series.sum(s)
2

iex> s = Explorer.Series.from_list([~D[2021-01-01], ~D[1999-12-31]])
iex> Explorer.Series.sum(s)
** (ArgumentError) Explorer.Series.sum/1 not implemented for dtype :date. Valid dtypes are [:integer, :float, :boolean].
@spec var(series :: t()) :: float()

Gets the variance of the series.

supported-dtypes

Supported dtypes

  • :integer
  • :float

examples

Examples

iex> s = Explorer.Series.from_list([1, 2, nil, 3])
iex> Explorer.Series.var(s)
1.0

iex> s = Explorer.Series.from_list([1.0, 2.0, nil, 3.0])
iex> Explorer.Series.var(s)
1.0

iex> s = Explorer.Series.from_list([~N[2021-01-01 00:00:00], ~N[1999-12-31 00:00:00]])
iex> Explorer.Series.var(s)
** (ArgumentError) Explorer.Series.var/1 not implemented for dtype :datetime. Valid dtypes are [:integer, :float].

Link to this section Functions: Element-wise

@spec add(left :: t(), right :: t() | number()) :: t()

Adds right to left, element-wise.

When mixing floats and integers, the resulting series will have dtype :float.

supported-dtypes

Supported dtypes

  • :integer
  • :float

examples

Examples

iex> s1 = Explorer.Series.from_list([1, 2, 3])
iex> s2 = Explorer.Series.from_list([4, 5, 6])
iex> Explorer.Series.add(s1, s2)
#Explorer.Series<
  integer[3]
  [5, 7, 9]
>

Checks equality between two entire series.

examples

Examples

iex> s1 = Explorer.Series.from_list(["a", "b"])
iex> s2 = Explorer.Series.from_list(["a", "b"])
iex> Explorer.Series.all_equal(s1, s2)
true

iex> s1 = Explorer.Series.from_list(["a", "b"])
iex> s2 = Explorer.Series.from_list(["a", "c"])
iex> Explorer.Series.all_equal(s1, s2)
false

iex> s1 = Explorer.Series.from_list(["a", "b"])
iex> s2 = Explorer.Series.from_list([1, 2])
iex> Explorer.Series.all_equal(s1, s2)
false

Returns a boolean mask of left and right, element-wise

examples

Examples

iex> s1 = Explorer.Series.from_list([1, 2, 3])
iex> mask1 = Explorer.Series.greater(s1, 1)
iex> mask2 = Explorer.Series.less(s1, 3)
iex> Explorer.Series.and(mask1, mask2)
#Explorer.Series<
  boolean[3]
  [false, true, false]
>
@spec cast(series :: t(), dtype :: dtype()) :: t()

Cast the series to another type.

examples

Examples

iex> s = Explorer.Series.from_list([1, 2, 3])
iex> Explorer.Series.cast(s, :string)
#Explorer.Series<
  string[3]
  ["1", "2", "3"]
>

iex> s = Explorer.Series.from_list([1, 2, 3])
iex> Explorer.Series.cast(s, :float)
#Explorer.Series<
  float[3]
  [1.0, 2.0, 3.0]
>

iex> s = Explorer.Series.from_list([1, 2, 3])
iex> Explorer.Series.cast(s, :date)
#Explorer.Series<
  date[3]
  [1970-01-02, 1970-01-03, 1970-01-04]
>

Note that datetime is represented as an integer of microseconds since Unix Epoch (1970-01-01 00:00:00).

iex> s = Explorer.Series.from_list([1, 2, 3])
iex> Explorer.Series.cast(s, :datetime)
#Explorer.Series<
  datetime[3]
  [1970-01-01 00:00:00.000001, 1970-01-01 00:00:00.000002, 1970-01-01 00:00:00.000003]
>

iex> s = Explorer.Series.from_list([1649883642 * 1_000 * 1_000])
iex> Explorer.Series.cast(s, :datetime)
#Explorer.Series<
  datetime[1]
  [2022-04-13 21:00:42.000000]
>

cast/2 will return the series as a no-op if you try to cast to the same dtype.

iex> s = Explorer.Series.from_list([1, 2, 3])
iex> Explorer.Series.cast(s, :integer)
#Explorer.Series<
  integer[3]
  [1, 2, 3]
>
@spec coalesce([t()]) :: t()

Finds the first non-missing element at each position.

examples

Examples

iex> s1 = Explorer.Series.from_list([1, 2, nil, nil])
iex> s2 = Explorer.Series.from_list([1, 2, nil, 4])
iex> s3 = Explorer.Series.from_list([nil, nil, 3, 4])
iex> Explorer.Series.coalesce([s1, s2, s3])
#Explorer.Series<
  integer[4]
  [1, 2, 3, 4]
>
@spec divide(left :: t(), right :: t() | number()) :: t()

Divides left by right, element-wise.

When mixing floats and integers, the resulting series will have dtype :float.

supported-dtypes

Supported dtypes

  • :integer
  • :float

examples

Examples

iex> s1 = [10, 10 ,10] |> Explorer.Series.from_list()
iex> s2 = [2, 2, 2] |> Explorer.Series.from_list()
iex> Explorer.Series.divide(s1, s2)
#Explorer.Series<
  integer[3]
  [5, 5, 5]
>

iex> s1 = [10, 10 ,10] |> Explorer.Series.from_list()
iex> Explorer.Series.divide(s1, 2)
#Explorer.Series<
  integer[3]
  [5, 5, 5]
>
@spec equal(
  left :: t(),
  right ::
    t() | number() | Date.t() | NaiveDateTime.t() | boolean() | String.t()
) :: t()

Returns boolean mask of left == right, element-wise.

examples

Examples

iex> s1 = Explorer.Series.from_list([1, 2, 3])
iex> s2 = Explorer.Series.from_list([1, 2, 4])
iex> Explorer.Series.equal(s1, s2)
#Explorer.Series<
  boolean[3]
  [true, true, false]
>

iex> s = Explorer.Series.from_list([1, 2, 3])
iex> Explorer.Series.equal(s, 1)
#Explorer.Series<
  boolean[3]
  [true, false, false]
>

iex> s = Explorer.Series.from_list([true, true, false])
iex> Explorer.Series.equal(s, true)
#Explorer.Series<
  boolean[3]
  [true, true, false]
>

iex> s = Explorer.Series.from_list(["a", "b", "c"])
iex> Explorer.Series.equal(s, "a")
#Explorer.Series<
  boolean[3]
  [true, false, false]
>

iex> s = Explorer.Series.from_list([~D[2021-01-01], ~D[1999-12-31]])
iex> Explorer.Series.equal(s, ~D[1999-12-31])
#Explorer.Series<
  boolean[2]
  [false, true]
>

iex> s = Explorer.Series.from_list([~N[2022-01-01 00:00:00], ~N[2022-01-01 23:00:00]])
iex> Explorer.Series.equal(s, ~N[2022-01-01 00:00:00])
#Explorer.Series<
  boolean[2]
  [true, false]
>

iex> s = Explorer.Series.from_list(["a", "b", "c"])
iex> Explorer.Series.equal(s, false)
** (ArgumentError) cannot invoke Explorer.Series.equal/2 with mismatched dtypes: string and false.
@spec greater(
  left :: t(),
  right :: t() | number() | Date.t() | NaiveDateTime.t()
) :: t()

Returns boolean mask of left > right, element-wise.

supported-dtypes

Supported dtypes

  • :integer
  • :float
  • :date
  • :datetime

examples

Examples

iex> s1 = Explorer.Series.from_list([1, 2, 3])
iex> s2 = Explorer.Series.from_list([1, 2, 4])
iex> Explorer.Series.greater(s1, s2)
#Explorer.Series<
  boolean[3]
  [false, false, false]
>
Link to this function

greater_equal(left, right)

View Source
@spec greater_equal(
  left :: t(),
  right :: t() | number() | Date.t() | NaiveDateTime.t()
) :: t()

Returns boolean mask of left >= right, element-wise.

supported-dtypes

Supported dtypes

  • :integer
  • :float
  • :date
  • :datetime

examples

Examples

iex> s1 = Explorer.Series.from_list([1, 2, 3])
iex> s2 = Explorer.Series.from_list([1, 2, 4])
iex> Explorer.Series.greater_equal(s1, s2)
#Explorer.Series<
  boolean[3]
  [true, true, false]
>
@spec is_nil(t()) :: t()

Returns a mask of nil values.

examples

Examples

iex> s = Explorer.Series.from_list([1, 2, nil, 4])
iex> Explorer.Series.is_nil(s)
#Explorer.Series<
  boolean[4]
  [false, false, true, false]
>
@spec is_not_nil(t()) :: t()

Returns a mask of not nil values.

examples

Examples

iex> s = Explorer.Series.from_list([1, 2, nil, 4])
iex> Explorer.Series.is_not_nil(s)
#Explorer.Series<
  boolean[4]
  [true, true, false, true]
>
@spec less(
  left :: t(),
  right :: t() | number() | Date.t() | NaiveDateTime.t()
) :: t()

Returns boolean mask of left < right, element-wise.

supported-dtypes

Supported dtypes

  • :integer
  • :float
  • :date
  • :datetime

examples

Examples

iex> s1 = Explorer.Series.from_list([1, 2, 3])
iex> s2 = Explorer.Series.from_list([1, 2, 4])
iex> Explorer.Series.less(s1, s2)
#Explorer.Series<
  boolean[3]
  [false, false, true]
>
@spec less_equal(
  left :: t(),
  right :: t() | number() | Date.t() | NaiveDateTime.t()
) :: t()

Returns boolean mask of left <= right, element-wise.

supported-dtypes

Supported dtypes

  • :integer
  • :float
  • :date
  • :datetime

examples

Examples

iex> s1 = Explorer.Series.from_list([1, 2, 3])
iex> s2 = Explorer.Series.from_list([1, 2, 4])
iex> Explorer.Series.less_equal(s1, s2)
#Explorer.Series<
  boolean[3]
  [true, true, true]
>
@spec multiply(left :: t(), right :: t() | number()) :: t()

Multiplies left and right, element-wise.

When mixing floats and integers, the resulting series will have dtype :float.

supported-dtypes

Supported dtypes

  • :integer
  • :float

examples

Examples

iex> s1 = 1..10 |> Enum.to_list() |> Explorer.Series.from_list()
iex> s2 = 11..20 |> Enum.to_list() |> Explorer.Series.from_list()
iex> Explorer.Series.multiply(s1, s2)
#Explorer.Series<
  integer[10]
  [11, 24, 39, 56, 75, 96, 119, 144, 171, 200]
>

iex> s1 = 1..5 |> Enum.to_list() |> Explorer.Series.from_list()
iex> Explorer.Series.multiply(s1, 2)
#Explorer.Series<
  integer[5]
  [2, 4, 6, 8, 10]
>
@spec not_equal(
  left :: t(),
  right ::
    t() | number() | Date.t() | NaiveDateTime.t() | boolean() | String.t()
) :: t()

Returns boolean mask of left != right, element-wise.

examples

Examples

iex> s1 = Explorer.Series.from_list([1, 2, 3])
iex> s2 = Explorer.Series.from_list([1, 2, 4])
iex> Explorer.Series.not_equal(s1, s2)
#Explorer.Series<
  boolean[3]
  [false, false, true]
>

iex> s = Explorer.Series.from_list([1, 2, 3])
iex> Explorer.Series.not_equal(s, 1)
#Explorer.Series<
  boolean[3]
  [false, true, true]
>

iex> s = Explorer.Series.from_list([true, true, false])
iex> Explorer.Series.not_equal(s, true)
#Explorer.Series<
  boolean[3]
  [false, false, true]
>

iex> s = Explorer.Series.from_list(["a", "b", "c"])
iex> Explorer.Series.not_equal(s, "a")
#Explorer.Series<
  boolean[3]
  [false, true, true]
>

iex> s = Explorer.Series.from_list([~D[2021-01-01], ~D[1999-12-31]])
iex> Explorer.Series.not_equal(s, ~D[1999-12-31])
#Explorer.Series<
  boolean[2]
  [true, false]
>

iex> s = Explorer.Series.from_list([~N[2022-01-01 00:00:00], ~N[2022-01-01 23:00:00]])
iex> Explorer.Series.not_equal(s, ~N[2022-01-01 00:00:00])
#Explorer.Series<
  boolean[2]
  [false, true]
>

iex> s = Explorer.Series.from_list(["a", "b", "c"])
iex> Explorer.Series.not_equal(s, false)
** (ArgumentError) cannot invoke Explorer.Series.not_equal/2 with mismatched dtypes: string and false.

Returns a boolean mask of left or right, element-wise

examples

Examples

iex> s1 = Explorer.Series.from_list([1, 2, 3])
iex> mask1 = Explorer.Series.less(s1, 2)
iex> mask2 = Explorer.Series.greater(s1, 2)
iex> Explorer.Series.or(mask1, mask2)
#Explorer.Series<
  boolean[3]
  [true, false, true]
>
Link to this function

peaks(series, max_or_min \\ :max)

View Source
@spec peaks(series :: t(), max_or_min :: :max | :min) :: t()

Returns a boolean mask with true where the 'peaks' (series max or min, default max) are.

supported-dtypes

Supported dtypes

  • :integer
  • :float
  • :date
  • :datetime

examples

Examples

iex> s = Explorer.Series.from_list([1, 2, 4, 1, 4])
iex> Explorer.Series.peaks(s)
#Explorer.Series<
  boolean[5]
  [false, false, true, false, true]
>
@spec pow(series :: t(), exponent :: number()) :: t()

Raises a numeric series to the power of the exponent.

supported-dtypes

Supported dtypes

  • :integer
  • :float

examples

Examples

iex> s = [8, 16, 32] |> Explorer.Series.from_list()
iex> Explorer.Series.pow(s, 2.0)
#Explorer.Series<
  float[3]
  [64.0, 256.0, 1024.0]
>

iex> s = [2, 4, 6] |> Explorer.Series.from_list()
iex> Explorer.Series.pow(s, 3)
#Explorer.Series<
  integer[3]
  [8, 64, 216]
>

iex> s = [2, 4, 6] |> Explorer.Series.from_list()
iex> Explorer.Series.pow(s, -3.0)
#Explorer.Series<
  float[3]
  [0.125, 0.015625, 0.004629629629629629]
>

iex> s = [1.0, 2.0, 3.0] |> Explorer.Series.from_list()
iex> s |> Explorer.Series.pow(3.0)
#Explorer.Series<
  float[3]
  [1.0, 8.0, 27.0]
>

iex> s = [2.0, 4.0, 6.0] |> Explorer.Series.from_list()
iex> s |> Explorer.Series.pow(2)
#Explorer.Series<
  float[3]
  [4.0, 16.0, 36.0]
>
@spec subtract(left :: t(), right :: t() | number()) :: t()

Subtracts right from left, element-wise.

When mixing floats and integers, the resulting series will have dtype :float.

supported-dtypes

Supported dtypes

  • :integer
  • :float

examples

Examples

iex> s1 = Explorer.Series.from_list([1, 2, 3])
iex> s2 = Explorer.Series.from_list([4, 5, 6])
iex> Explorer.Series.subtract(s1, s2)
#Explorer.Series<
  integer[3]
  [-3, -3, -3]
>

Link to this section Functions: Transformation

Link to this function

argsort(series, reverse \\ false)

View Source

Returns the indices that would sort the series.

@spec coalesce(s1 :: t(), s2 :: t()) :: t()

Finds the first non-missing element at each position.

coalesce(s1, s2) is equivalent to coalesce([s1, s2]).

examples

Examples

iex> s1 = Explorer.Series.from_list([1, nil, 3, nil])
iex> s2 = Explorer.Series.from_list([1, 2, nil, 4])
iex> Explorer.Series.coalesce(s1, s2)
#Explorer.Series<
  integer[4]
  [1, 2, 3, 4]
>

iex> s1 = Explorer.Series.from_list(["foo", nil, "bar", nil])
iex> s2 = Explorer.Series.from_list([1, 2, nil, 4])
iex> Explorer.Series.coalesce(s1, s2)
** (ArgumentError) cannot invoke Explorer.Series.coalesce/2 with mismatched dtypes: string and integer.
@spec concat([t()]) :: t()

Concatenate one or more series.

The dtypes must match unless all are numeric, in which case all series will be downcast to float.

examples

Examples

iex> s1 = Explorer.Series.from_list([1, 2, 3])
iex> s2 = Explorer.Series.from_list([4, 5, 6])
iex> Explorer.Series.concat([s1, s2])
#Explorer.Series<
  integer[6]
  [1, 2, 3, 4, 5, 6]
>

iex> s1 = Explorer.Series.from_list([1, 2, 3])
iex> s2 = Explorer.Series.from_list([4.0, 5.0, 6.4])
iex> Explorer.Series.concat(s1, s2)
#Explorer.Series<
  float[6]
  [1.0, 2.0, 3.0, 4.0, 5.0, 6.4]
>
@spec concat(s1 :: t(), s2 :: t()) :: t()

Concatenate one or more series.

concat(s1, s2) is equivalent to concat([s1, s2]).

Returns the unique values of the series.

examples

Examples

iex> s = [1, 1, 2, 2, 3, 3] |> Explorer.Series.from_list()
iex> s |> Explorer.Series.distinct()
#Explorer.Series<
  integer[3]
  [1, 2, 3]
>
@spec fetch!(series :: t(), idx :: integer()) :: any()

Returns the value of the series at the given index.

This function will raise an error in case the index is out of bounds.

examples

Examples

iex> s = Explorer.Series.from_list(["a", "b", "c"])
iex> Explorer.Series.fetch!(s, 2)
"c"

iex> s = Explorer.Series.from_list(["a", "b", "c"])
iex> Explorer.Series.fetch!(s, 4)
** (ArgumentError) index 4 out of bounds for series of size 3
@spec first(series :: t()) :: any()

Returns the first element of the series.

examples

Examples

iex> s = 1..100 |> Enum.to_list() |> Explorer.Series.from_list()
iex> Explorer.Series.first(s)
1
Link to this function

from_list(list, opts \\ [])

View Source
@spec from_list(list :: list(), opts :: Keyword.t()) :: t()

Creates a new series from a list.

The list must consist of a single data type and nils. It is possible to have a list of only nil values. In this case, the list will have the :dtype of float.

options

Options

  • :backend - The backend to allocate the series on.
  • :dtype - Cast the series to a given :dtype. By default this is nil, which means that Explorer will infer the type from the values in the list.

examples

Examples

Explorer will infer the type from the values in the list.

iex> Explorer.Series.from_list([1, 2, 3])
#Explorer.Series<
  integer[3]
  [1, 2, 3]
>

Series are nullable, so you may also include nils.

iex> Explorer.Series.from_list([1.0, nil, 2.5, 3.1])
#Explorer.Series<
  float[4]
  [1.0, nil, 2.5, 3.1]
>

A mix of integers and floats will be downcasted to a float.

iex> Explorer.Series.from_list([1, 2.0])
#Explorer.Series<
  float[2]
  [1.0, 2.0]
>

Trying to create a "nil" series will, by default, result in a series of floats.

iex> Explorer.Series.from_list([nil, nil])
#Explorer.Series<
  float[2]
  [nil, nil]
>

You can specify the desired dtype for a series with the :dtype option.

iex> Explorer.Series.from_list([nil, nil], dtype: :integer)
#Explorer.Series<
  integer[2]
  [nil, nil]
>

iex> Explorer.Series.from_list([1, nil], dtype: :string)
#Explorer.Series<
  string[2]
  ["1", nil]
>

It is possible to create a series of :datetime from a list of microseconds since Unix Epoch.

iex> Explorer.Series.from_list([1649883642 * 1_000 * 1_000], dtype: :datetime)
#Explorer.Series<
  datetime[1]
  [2022-04-13 21:00:42.000000]
>

Mixing non-numeric data types will raise an ArgumentError.

iex> Explorer.Series.from_list([1, "a"])
** (ArgumentError) the value "a" does not match the inferred series dtype :integer
Link to this function

from_tensor(tensor, opts \\ [])

View Source
@spec from_tensor(tensor :: Nx.Tensor.t(), opts :: Keyword.t()) :: t()

Converts a t:Nx.Tensor.t/0 to a series.

Warning

Nx is an optional dependency. You will need to ensure it's installed to use this function.

examples

Examples

iex> tensor = Nx.tensor([1, 2, 3])
iex> Explorer.Series.from_tensor(tensor)
#Explorer.Series<
  integer[3]
  [1, 2, 3]
>

iex> tensor = Nx.tensor([1.0, 2.0, 3.0])
iex> Explorer.Series.from_tensor(tensor)
#Explorer.Series<
  float[3]
  [1.0, 2.0, 3.0]
>
Link to this function

head(series, n_elements \\ 10)

View Source
@spec head(series :: t(), n_elements :: integer()) :: t()

Returns the first N elements of the series.

examples

Examples

iex> s = 1..100 |> Enum.to_list() |> Explorer.Series.from_list()
iex> Explorer.Series.head(s)
#Explorer.Series<
  integer[10]
  [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
>
@spec last(series :: t()) :: any()

Returns the last element of the series.

examples

Examples

iex> s = 1..100 |> Enum.to_list() |> Explorer.Series.from_list()
iex> Explorer.Series.last(s)
100
@spec mask(series :: t(), mask :: t()) :: t()

Filters a series with a mask.

examples

Examples

iex> s1 = Explorer.Series.from_list([1,2,3])
iex> s2 = Explorer.Series.from_list([true, false, true])
iex> Explorer.Series.mask(s1, s2)
#Explorer.Series<
  integer[2]
  [1, 3]
>

Reverses the series order.

example

Example

iex> s = [1, 2, 3] |> Explorer.Series.from_list()
iex> Explorer.Series.reverse(s)
#Explorer.Series<
  integer[3]
  [3, 2, 1]
>
Link to this function

sample(series, n_or_frac, opts \\ [])

View Source
@spec sample(series :: t(), n_or_frac :: number(), opts :: Keyword.t()) :: t()

Returns a random sample of the series.

If given an integer as the second argument, it will return N samples. If given a float, it will return that proportion of the series.

Can sample with or without replacement.

options

Options

  • replacement - If set to true, each sample will be independent and therefore values may repeat. Required to be true for n greater then the number of rows in the series or frac > 1.0. (default: false)
  • seed - An integer to be used as a random seed. If nil, a random value between 1 and 1e12 will be used. (default: nil)

examples

Examples

iex> s = 1..100 |> Enum.to_list() |> Explorer.Series.from_list()
iex> Explorer.Series.sample(s, 10, seed: 100)
#Explorer.Series<
  integer[10]
  [72, 33, 15, 4, 16, 49, 23, 96, 45, 47]
>

iex> s = 1..100 |> Enum.to_list() |> Explorer.Series.from_list()
iex> Explorer.Series.sample(s, 0.05, seed: 100)
#Explorer.Series<
  integer[5]
  [68, 24, 6, 8, 36]
>
@spec slice(series :: t(), indices :: [integer()] | Range.t()) :: t()

Returns the elements at the given indices as a new series.

examples

Examples

iex> s = Explorer.Series.from_list(["a", "b", "c"])
iex> Explorer.Series.slice(s, [0, 2])
#Explorer.Series<
  string[2]
  ["a", "c"]
>

iex> s = Explorer.Series.from_list(["a", "b", "c"])
iex> Explorer.Series.slice(s, 1..2)
#Explorer.Series<
  string[2]
  ["b", "c"]
>
Link to this function

slice(series, offset, size)

View Source
@spec slice(series :: t(), offset :: integer(), size :: integer()) :: t()

Returns a slice of the series, with size elements starting at offset.

examples

Examples

iex> s = Explorer.Series.from_list([1, 2, 3, 4, 5])
iex> Explorer.Series.slice(s, 1, 2)
#Explorer.Series<
  integer[2]
  [2, 3]
>

Negative offsets count from the end of the series.

iex> s = Explorer.Series.from_list([1, 2, 3, 4, 5])
iex> Explorer.Series.slice(s, -3, 2)
#Explorer.Series<
  integer[2]
  [3, 4]
>

If the size would run past the end of the series, the result may be shorter than the size.

iex> s = Explorer.Series.from_list([1, 2, 3, 4, 5])
iex> Explorer.Series.slice(s, -3, 4)
#Explorer.Series<
  integer[3]
  [3, 4, 5]
>
Link to this function

sort(series, reverse \\ false)

View Source

Sorts the series.

examples

Examples

iex> s = Explorer.Series.from_list([9, 3, 7, 1])
iex> s |> Explorer.Series.sort()
#Explorer.Series<
  integer[4]
  [1, 3, 7, 9]
>
Link to this function

tail(series, n_elements \\ 10)

View Source
@spec tail(series :: t(), n_elements :: integer()) :: t()

Returns the last N elements of the series.

examples

Examples

iex> s = 1..100 |> Enum.to_list() |> Explorer.Series.from_list()
iex> Explorer.Series.tail(s)
#Explorer.Series<
  integer[10]
  [91, 92, 93, 94, 95, 96, 97, 98, 99, 100]
>
Link to this function

take_every(series, every_n)

View Source
@spec take_every(series :: t(), every_n :: integer()) :: t()

Takes every nth value in this series, returned as a new series.

examples

Examples

iex> s = 1..10 |> Enum.to_list() |> Explorer.Series.from_list()
iex> s |> Explorer.Series.take_every(2)
#Explorer.Series<
  integer[5]
  [1, 3, 5, 7, 9]
>

If n is bigger than the size of the series, the result is a new series with only the first value of the supplied series.

iex> s = 1..10 |> Enum.to_list() |> Explorer.Series.from_list()
iex> s |> Explorer.Series.take_every(20)
#Explorer.Series<
  integer[1]
  [1]
>
@spec to_enum(series :: t()) :: Enumerable.t()

Converts a series to an enumerable.

examples

Examples

iex> series = Explorer.Series.from_list([1, 2, 3])
iex> series |> Explorer.Series.to_enum() |> Enum.to_list()
[1, 2, 3]
@spec to_list(series :: t()) :: list()

Converts a series to a list.

examples

Examples

iex> series = Explorer.Series.from_list([1, 2, 3])
iex> Explorer.Series.to_list(series)
[1, 2, 3]
Link to this function

to_tensor(series, tensor_opts \\ [])

View Source
@spec to_tensor(series :: t(), tensor_opts :: Keyword.t()) :: Nx.Tensor.t()

Converts a series to a t:Nx.Tensor.t/0.

Options are passed directly to Nx.tensor/2.

supported-dtypes

Supported dtypes

  • :float
  • :integer

Warning

Nx is an optional dependency. You will need to ensure it's installed to use this function.

examples

Examples

iex> s = Explorer.Series.from_list([1, 2, 3])
iex> Explorer.Series.to_tensor(s)
#Nx.Tensor<
  s64[3]
  [1, 2, 3]
>

Tensor options can be passed directly to to_tensor/2.

iex> s = Explorer.Series.from_list([1, 2, 3])
iex> Explorer.Series.to_tensor(s, names: [:y], type: {:f, 64})
#Nx.Tensor<
  f64[y: 3]
  [1.0, 2.0, 3.0]
>

Returns an Explorer.Series where each element is the result of invoking fun on each corresponding element of series.

This is an expensive operation meant to enable the use of arbitrary Elixir functions against any backend. The implementation will vary by backend but in most (all?) cases will require converting to an Elixir.List, applying Enum.map/2, and then converting back to an Explorer.Series.

examples

Examples

iex> s = Explorer.Series.from_list(["this ", " is", "great   "])
iex> Explorer.Series.transform(s, &String.trim/1)
#Explorer.Series<
  string[3]
  ["this", "is", "great"]
>

iex> s = Explorer.Series.from_list(["this", "is", "great"])
iex> Explorer.Series.transform(s, &String.length/1)
#Explorer.Series<
  integer[3]
  [4, 2, 5]
>
Link to this function

unordered_distinct(series)

View Source

Returns the unique values of the series, but does not maintain order.

Faster than distinct/1.

examples

Examples

iex> s = [1, 1, 2, 2, 3, 3] |> Explorer.Series.from_list()
iex> s |> Explorer.Series.unordered_distinct()

Link to this section Functions: Window

Link to this function

cumulative_max(series, opts \\ [])

View Source
@spec cumulative_max(series :: t(), opts :: Keyword.t()) :: t()

Calculates the cumulative maximum of the series.

Optionally, can fill in reverse.

Does not fill nil values. See fill_missing/2.

supported-dtypes

Supported dtypes

  • :integer
  • :float
  • :date
  • :datetime

examples

Examples

iex> s = [1, 2, 3, 4] |> Explorer.Series.from_list()
iex> Explorer.Series.cumulative_max(s)
#Explorer.Series<
  integer[4]
  [1, 2, 3, 4]
>

iex> s = [1, 2, nil, 4] |> Explorer.Series.from_list()
iex> Explorer.Series.cumulative_max(s)
#Explorer.Series<
  integer[4]
  [1, 2, nil, 4]
>
Link to this function

cumulative_min(series, opts \\ [])

View Source
@spec cumulative_min(series :: t(), opts :: Keyword.t()) :: t()

Calculates the cumulative minimum of the series.

Optionally, can fill in reverse.

Does not fill nil values. See fill_missing/2.

supported-dtypes

Supported dtypes

  • :integer
  • :float
  • :date
  • :datetime

examples

Examples

iex> s = [1, 2, 3, 4] |> Explorer.Series.from_list()
iex> Explorer.Series.cumulative_min(s)
#Explorer.Series<
  integer[4]
  [1, 1, 1, 1]
>

iex> s = [1, 2, nil, 4] |> Explorer.Series.from_list()
iex> Explorer.Series.cumulative_min(s)
#Explorer.Series<
  integer[4]
  [1, 1, nil, 1]
>
Link to this function

cumulative_sum(series, opts \\ [])

View Source
@spec cumulative_sum(series :: t(), opts :: Keyword.t()) :: t()

Calculates the cumulative sum of the series.

Optionally, can fill in reverse.

Does not fill nil values. See fill_missing/2.

supported-dtypes

Supported dtypes

  • :integer
  • :float
  • :boolean

examples

Examples

iex> s = [1, 2, 3, 4] |> Explorer.Series.from_list()
iex> Explorer.Series.cumulative_sum(s)
#Explorer.Series<
  integer[4]
  [1, 3, 6, 10]
>

iex> s = [1, 2, nil, 4] |> Explorer.Series.from_list()
iex> Explorer.Series.cumulative_sum(s)
#Explorer.Series<
  integer[4]
  [1, 3, nil, 7]
>
Link to this function

fill_missing(series, strategy)

View Source
@spec fill_missing(
  t(),
  :forward
  | :backward
  | :max
  | :min
  | :mean
  | Explorer.Backend.Series.valid_types()
) :: t()

Fill missing values with the given strategy. If a scalar value is provided instead of a strategy atom, nil will be replaced with that value. It must be of the same dtype as the series.

strategies

Strategies

  • :forward - replace nil with the previous value
  • :backward - replace nil with the next value
  • :max - replace nil with the series maximum
  • :min - replace nil with the series minimum
  • :mean - replace nil with the series mean

examples

Examples

iex> s = Explorer.Series.from_list([1, 2, nil, 4])
iex> Explorer.Series.fill_missing(s, :forward)
#Explorer.Series<
  integer[4]
  [1, 2, 2, 4]
>

iex> s = Explorer.Series.from_list([1, 2, nil, 4])
iex> Explorer.Series.fill_missing(s, :backward)
#Explorer.Series<
  integer[4]
  [1, 2, 4, 4]
>

iex> s = Explorer.Series.from_list([1, 2, nil, 4])
iex> Explorer.Series.fill_missing(s, :max)
#Explorer.Series<
  integer[4]
  [1, 2, 4, 4]
>

iex> s = Explorer.Series.from_list([1, 2, nil, 4])
iex> Explorer.Series.fill_missing(s, :min)
#Explorer.Series<
  integer[4]
  [1, 2, 1, 4]
>

iex> s = Explorer.Series.from_list([1, 2, nil, 4])
iex> Explorer.Series.fill_missing(s, :mean)
#Explorer.Series<
  integer[4]
  [1, 2, 2, 4]
>

iex> s = Explorer.Series.from_list([1, 2, nil, 4])
iex> Explorer.Series.fill_missing(s, 3)
#Explorer.Series<
  integer[4]
  [1, 2, 3, 4]
>

iex> s = Explorer.Series.from_list([1.0, 2.0, nil, 4.0])
iex> Explorer.Series.fill_missing(s, 3.0)
#Explorer.Series<
  float[4]
  [1.0, 2.0, 3.0, 4.0]
>

iex> s = Explorer.Series.from_list(["a", "b", nil, "d"])
iex> Explorer.Series.fill_missing(s, "c")
#Explorer.Series<
  string[4]
  ["a", "b", "c", "d"]
>

iex> s = Explorer.Series.from_list([1, 2, nil, 4])
iex> Explorer.Series.fill_missing(s, "foo")
** (ArgumentError) cannot invoke Explorer.Series.fill_missing/2 with mismatched dtypes: integer and "foo".
Link to this function

window_max(series, window_size, opts \\ [])

View Source

Calculate the rolling max, given a window size and optional list of weights.

options

Options

  • :weights - An optional list of weights with the same length as the window that will be multiplied elementwise with the values in the window. Defaults to nil.

  • :min_periods - The number of values in the window that should be non-nil before computing a result. If nil, it will be set equal to window size. Defaults to 1.

  • :center - Set the labels at the center of the window. Defaults to false.

examples

Examples

iex> s = 1..10 |> Enum.to_list() |> Explorer.Series.from_list()
iex> Explorer.Series.window_max(s, 4)
#Explorer.Series<
  integer[10]
  [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
>

iex> s = 1..10 |> Enum.to_list() |> Explorer.Series.from_list()
iex> Explorer.Series.window_max(s, 2, weights: [1.0, 2.0])
#Explorer.Series<
  float[10]
  [1.0, 4.0, 6.0, 8.0, 10.0, 12.0, 14.0, 16.0, 18.0, 20.0]
>
Link to this function

window_mean(series, window_size, opts \\ [])

View Source

Calculate the rolling mean, given a window size and optional list of weights.

options

Options

  • :weights - An optional list of weights with the same length as the window that will be multiplied elementwise with the values in the window. Defaults to nil.

  • :min_periods - The number of values in the window that should be non-nil before computing a result. If nil, it will be set equal to window size. Defaults to 1.

  • :center - Set the labels at the center of the window. Defaults to false.

examples

Examples

iex> s = 1..10 |> Enum.to_list() |> Explorer.Series.from_list()
iex> Explorer.Series.window_mean(s, 4)
#Explorer.Series<
  float[10]
  [1.0, 1.5, 2.0, 2.5, 3.5, 4.5, 5.5, 6.5, 7.5, 8.5]
>

iex> s = 1..10 |> Enum.to_list() |> Explorer.Series.from_list()
iex> Explorer.Series.window_mean(s, 2, weights: [1.0, 2.0])
#Explorer.Series<
  float[10]
  [1.0, 2.5, 4.0, 5.5, 7.0, 8.5, 10.0, 11.5, 13.0, 14.5]
>
Link to this function

window_min(series, window_size, opts \\ [])

View Source

Calculate the rolling min, given a window size and optional list of weights.

options

Options

  • :weights - An optional list of weights with the same length as the window that will be multiplied elementwise with the values in the window. Defaults to nil.

  • :min_periods - The number of values in the window that should be non-nil before computing a result. If nil, it will be set equal to window size. Defaults to 1.

  • :center - Set the labels at the center of the window. Defaults to false.

examples

Examples

iex> s = 1..10 |> Enum.to_list() |> Explorer.Series.from_list()
iex> Explorer.Series.window_min(s, 4)
#Explorer.Series<
  integer[10]
  [1, 1, 1, 1, 2, 3, 4, 5, 6, 7]
>

iex> s = 1..10 |> Enum.to_list() |> Explorer.Series.from_list()
iex> Explorer.Series.window_min(s, 2, weights: [1.0, 2.0])
#Explorer.Series<
  float[10]
  [1.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0]
>
Link to this function

window_sum(series, window_size, opts \\ [])

View Source

Calculate the rolling sum, given a window size and optional list of weights.

options

Options

  • :weights - An optional list of weights with the same length as the window that will be multiplied elementwise with the values in the window. Defaults to nil.

  • :min_periods - The number of values in the window that should be non-nil before computing a result. If nil, it will be set equal to window size. Defaults to 1.

  • :center - Set the labels at the center of the window. Defaults to false.

examples

Examples

iex> s = 1..10 |> Enum.to_list() |> Explorer.Series.from_list()
iex> Explorer.Series.window_sum(s, 4)
#Explorer.Series<
  integer[10]
  [1, 3, 6, 10, 14, 18, 22, 26, 30, 34]
>

iex> s = 1..10 |> Enum.to_list() |> Explorer.Series.from_list()
iex> Explorer.Series.window_sum(s, 2, weights: [1.0, 2.0])
#Explorer.Series<
  float[10]
  [1.0, 5.0, 8.0, 11.0, 14.0, 17.0, 20.0, 23.0, 26.0, 29.0]
>