diff --git a/src/awkward/operations/ak_full_like.py b/src/awkward/operations/ak_full_like.py index 82fb207c35..5929a9ed0b 100644 --- a/src/awkward/operations/ak_full_like.py +++ b/src/awkward/operations/ak_full_like.py @@ -27,7 +27,30 @@ def full_like( behavior=None, attrs=None, ): - """ + """Returns an array with the same structure as the input, filled with a given value. + + This is the equivalent of NumPy's `np.full_like` for Awkward Arrays. + + Although it's possible to produce an array of `fill_value` with the + structure of an `array` using #ak.broadcast_arrays: + + >>> array = ak.Array([[1, 2, 3], [], [4, 5]]) + >>> ak.broadcast_arrays(array, 1) + [, + ] + >>> ak.broadcast_arrays(array, 1.0) + [, + ] + + Such a technique takes its type from the scalar (`1` or `1.0`), rather than + the array. This function gets all types from the array, which might not be + the same in all parts of the structure. + + (There is no equivalent of NumPy's `np.empty_like` because Awkward Arrays + are immutable.) + + See also #ak.zeros_like and #ak.ones_like. + Args: array: Array-like data (anything #ak.to_layout recognizes). fill_value: Value to fill the new array with. @@ -42,24 +65,12 @@ def full_like( attrs (None or dict): Custom attributes for the output array, if high-level. - This is the equivalent of NumPy's `np.full_like` for Awkward Arrays. - - Although it's possible to produce an array of `fill_value` with the - structure of an `array` using #ak.broadcast_arrays: + Returns: + An array with the same structure as `array`, with every value replaced + by `fill_value`. - >>> array = ak.Array([[1, 2, 3], [], [4, 5]]) - >>> ak.broadcast_arrays(array, 1) - [, - ] - >>> ak.broadcast_arrays(array, 1.0) - [, - ] - - Such a technique takes its type from the scalar (`1` or `1.0`), rather than - the array. This function gets all types from the array, which might not be - the same in all parts of the structure. - - Here is an extreme example: + Examples: + Here is an extreme example: >>> array = ak.Array([ ... [{"x": 0.0, "y": []}, @@ -76,16 +87,11 @@ def full_like( [], [{x: 12.3, y: [12, 12, None, 12]}, True, ..., True, {x: 12.3, y: [12, ...]}]] - The `"x"` values get filled in with `12.3` because they retain their type - (`float64`) and the `"y"` list items get filled in with `12` because they - retain their type (`int64`). Booleans get filled with True because `12.3` - is not zero. Missing values remain in the same positions as in the original - `array`. (To fill them in, use #ak.fill_none.) - - See also #ak.zeros_like and #ak.ones_like. - - (There is no equivalent of NumPy's `np.empty_like` because Awkward Arrays - are immutable.) + The `"x"` values get filled in with `12.3` because they retain their type + (`float64`) and the `"y"` list items get filled in with `12` because they + retain their type (`int64`). Booleans get filled with True because `12.3` + is not zero. Missing values remain in the same positions as in the original + `array`. (To fill them in, use #ak.fill_none.) """ # Dispatch yield array, fill_value diff --git a/src/awkward/operations/ak_ones_like.py b/src/awkward/operations/ak_ones_like.py index 27b46a7e00..be1ce36ca3 100644 --- a/src/awkward/operations/ak_ones_like.py +++ b/src/awkward/operations/ak_ones_like.py @@ -22,7 +22,15 @@ def ones_like( behavior=None, attrs=None, ): - """ + """Returns an array with the same structure as the input, filled with ones. + + This is the equivalent of NumPy's `np.ones_like` for Awkward Arrays. + + (There is no equivalent of NumPy's `np.empty_like` because Awkward Arrays + are immutable.) + + See #ak.full_like for details, and see also #ak.zeros_like. + Args: array: Array-like data (anything #ak.to_layout recognizes). dtype (None or NumPy dtype): Overrides the data type of the result. @@ -36,12 +44,9 @@ def ones_like( attrs (None or dict): Custom attributes for the output array, if high-level. - This is the equivalent of NumPy's `np.ones_like` for Awkward Arrays. - - See #ak.full_like for details, and see also #ak.zeros_like. - - (There is no equivalent of NumPy's `np.empty_like` because Awkward Arrays - are immutable.) + Returns: + An array with the same structure as `array`, with every value replaced + by one. """ # Dispatch yield (array,) diff --git a/src/awkward/operations/ak_zeros_like.py b/src/awkward/operations/ak_zeros_like.py index 7db5fd88df..5152f21021 100644 --- a/src/awkward/operations/ak_zeros_like.py +++ b/src/awkward/operations/ak_zeros_like.py @@ -24,7 +24,15 @@ def zeros_like( behavior=None, attrs=None, ): - """ + """Returns an array with the same structure as the input, filled with zeros. + + This is the equivalent of NumPy's `np.zeros_like` for Awkward Arrays. + + (There is no equivalent of NumPy's `np.empty_like` because Awkward Arrays + are immutable.) + + See #ak.full_like for details, and see also #ak.ones_like. + Args: array: Array-like data (anything #ak.to_layout recognizes). dtype (None or NumPy dtype): Overrides the data type of the result. @@ -38,12 +46,9 @@ def zeros_like( attrs (None or dict): Custom attributes for the output array, if high-level. - This is the equivalent of NumPy's `np.zeros_like` for Awkward Arrays. - - See #ak.full_like for details, and see also #ak.ones_like. - - (There is no equivalent of NumPy's `np.empty_like` because Awkward Arrays - are immutable.) + Returns: + An array with the same structure as `array`, with every value replaced + by zero. """ # Dispatch yield (array,)