broadcast Package Overview

Description

broadcast:
‘NumPy’-Like Broadcasted Operations for Atomic and Recursive Arrays with Minimal Dependencies.

Implements efficient broadcasted operations for atomic and recursive arrays.

Besides linking to ‘Rcpp’, ‘broadcast’ does not use any external libraries in any way; ‘broadcast’ was essentially made from scratch and can be installed out-of-the-box.

The implementations available in ‘broadcast’ include, but are not limited to, the following:

  1. Broadcasted element-wise operations on any 2 arrays; they support a large set of relational, arithmetic, Boolean, string, and bit-wise operations.

  2. A faster, more memory efficient, and broadcasted abind-like function, for binding arrays along an arbitrary dimension.

  3. Broadcasted ifelse-like, and apply-like functions.

  4. Casting functions, that cast subset-groups of an array to a new dimension, cast nested lists to dimensional lists, and vice-versa.

  5. A few linear algebra functions for statistics.

The functions in the ‘broadcast’ package strive to minimize computation time and memory usage (which is not just good for efficient computing, but also for the environment).

In the context of operations involving 2 (or more) arrays, “broadcasting” refers to recycling array dimensions without allocating additional memory, which is considerably faster and more memory-efficient than R’s regular dimensions replication mechanism.

Functions

Broadcasted Operators
Base ‘R’ comes with relational (==, !=, etc.), arithmetic (+, -, *, /, etc.), and logical/bit-wise (&, |) operators.
‘broadcast’ provides 2 ways to use these operators with broadcasting.

The first (and simple) way is to use the broadcaster class, which comes with it’s own method dispatch for the above mentioned operators.
This method support operator precedence, and for the average ‘R’ user, this is sufficient.

The second way is to use the large set of bc.- functions.
These offer much greater control and more operators than the previous method, and has less risk of running into conflicting methods.
But it does not support operator precedence.

More information about both methods can be found here:
broadcast_operators.

Binding Arrays
‘broadcast’ provides the bind_array function, to bind arrays along an arbitrary dimension, with support for broadcasting.

The API of bind_array() is inspired by the fantastic abind::abind() function by Tony Plare & Richard Heiberger (2016).
But bind_array() differs considerably from abind::abind in the following ways:

  • bind_array() allows for broadcasting, while abind::abind does not support broadcasting.

  • bind_array() is generally faster and more memory-efficient than abind::abind, as bind_array() relies heavily on ‘C’ and ‘C++’ code.

  • bind_array() differs from abind::abind in that it can handle recursive arrays properly
    (the abind::abind function would unlist everything to atomic arrays, ruining the structure).

  • unlike abind::abind, bind_array() only binds (atomic/recursive) arrays and matrices.
    bind_array()does not attempt to convert things to arrays when they are not arrays, but will give an error instead.
    This saves computation time and prevents unexpected results.

  • bind_array() has more streamlined naming options, compared to abind::abind.

See bind_array.

Casting Functions
‘broadcast’ provides several "casting" functions.
These can facility complex forms of broadcasting that would normally not be possible.
But these "casting" functions also have their own merit, beside empowering complex broadcasting.

More information about the casting functions can be found here:
broadcast_casting.

General functions
‘broadcast’ also comes with 2 general broadcasted functions:

  • bc_ifelse: Broadcasted version of ifelse.

  • bcapply: Broadcasted apply-like function.

Other functions
‘broadcast’ provides type-casting functions, which preserve names and dimensions - convenient for arrays.

‘broadcast’ also provides simple linear algebra functions for statistics.

And ‘broadcast’ comes with some helper functions:
bc_dim, ndim, lst.ndim, rep_dim.

Supported Structures

‘broadcast’ supports atomic/recursive arrays (up to 16 dimensions), and atomic/recursive vectors.
As in standard Linear Algebra Convention, dimensionless vectors are interpreted as column-vectors in broadcasted array operations.

Author(s)

Author, Maintainer: Tony Wilkes tony_a_wilkes@outlook.com (ORCID)

References

Plate T, Heiberger R (2016). abind: Combine Multidimensional Arrays. R package version 1.4-5, https://CRAN.R-project.org/package=abind.

Harris, C.R., Millman, K.J., van der Walt, S.J. et al. Array programming with NumPy. Nature 585, 357–362 (2020). doi:10.1038/s41586-020-2649-2. (Publisher link).