Functions Overview

 

Introduction

The ‘broadcast’ package provides 6 main functionalities:

  • functions to perform broadcasted element-wise binary operations
  • broadcasted dimensional binding of arrays
  • broadcasted generic pair-wise functions
  • casting/pivoting an array into a new dimension
  • array typecasting with dimensions and names preserved
  • simple linear algebra functions for statistics

This guide gives a brief overview of the functions provided by the ‘broadcast’ - package.

 

Functions for broadcasted element-wise binary operations

The ‘broadcast’ package provides functions that perform broadcasted element-wise binary operations. These functions use an API similar to the outer() function.

The functions are the following:

  • bc.b(): Broadcasted Boolean operations.
    Includes the &, |, xor, nand, operations, and logical relational operations.
  • bc.i() Broadcasted Integer Numeric operations.
    Includes integer relational operations, basic arithmetic, and the GCD (greatest common divisor) operation.
  • bc.d(): Broadcasted Decimal Numeric operations.
    Includes decimal relational operations, relational operations with Machine precision specification, and arithmetic operations.
  • bc.cplx(): Broadcasted Complex Numeric operations.
    Includes (in)equality operations, and basic arithmetic operations.
  • bc.str(): Broadcasted String operations.
    Includes operations for (in)equality, concatenation, and string distance (Levenshtein) calculation.
  • bc.raw(): Broadcasted operations on arrays of type raw.
  • bc.bit(): Broadcasted bit-wise operations. Supports vectors/arrays of types raw and integer.
  • bc.list(): Broadcasted operations on Recursive arrays.

These are all pair-wise functions; i.e. they operate on 2 arrays at a time.
This is intentional, as it is quite difficult to reason about broadcasting when it involves more than a pair of arrays.

 

Note
  • bc.i(x, y "+") is faster and more memory efficient than bc.d(trunc(x), trunc(y), "+"), as the latter results in producing unnecessary copies of both x and y.

 

Overloaded operators

Sometimes broadcasting is needed in a large mathematical expression, involving multiple variables, where precedence is of importance. For example in an expression like this:

x / (y + z) + a

Using the bc.* functions for that, while possible, may be inconvenient. It may be more convenient to use the base operators directly, whilst still keeping the broadcasting property.

To this end, the ‘broadcast’ package provides the broadcaster class, which comes with its own method dispatch for the base operators.

 

Binding arrays

‘broadcast’ provides the bind_array() function. This binds arrays (including matrices) along any arbitrary dimension. It allows for dimensional broadcasting, and returns an array.

 

Why another array binding function

There is already a famous, battle-tested function for binding arrays, namely the abind() function from the fantastic package of the same name. So why does ‘broadcast’ provide another array binding function?

Well, as great as abind::abind() is, there are some issues with it, and the bind_array() function from ’broadcast` attempts (and in my humble opinion succeeds) to provide a better alternative:

  • bind_array() is faster and more memory efficient.
  • abind() does not support broadcasting. bind_array() does support broadcasting.
  • abind() does not support recursive arrays (i.e. arrays of type list). When binding recursive arrays, abind() will attempt to unlist it, even when it does not make sense, ruining the structure of the array. bind_array() fully supports recursive arrays, as well as arrays of all atomic types.
  • abind() has somewhat confusing mechanisms for giving dimension names to the output. bind_array() has more streamlined naming arguments.

bind_array() uses a similar API to that of abind::abind(), and provides similar features like binding arrays before the first dimension (using along = 0) or after the last dimension.

 

General Broadcasted functions

‘broadcast’ provides bcapply(), which is a broadcasted apply-like function, and bc_ifelse(), which is a broadcasted version of ifelse().

 

Acast

The acast() function casts an array into a new dimension.
Roughly speaking, it is somewhat analogous to data.table::dcast(), except that acast() works on arrays (instead of data.tables) and casts into a entirely new dimension (instead of into more columns).

 

Type-casting

‘broadcast’ offers type-casting functions. Unlike base R’s type-casting functions (as.logical(), as.integer(), etc.), the type-casting functions from ‘broadcast’ preserve names and dimensions. See typecast.

 

Simple linear algebra functions for statistics

‘broadcast’ provides a small set of simple linear algebra functions for usage in statistics. See linear_algebra_stats.

 

Supported Structures

The functions in the ‘broadcast’ package only support S3 structures. S4 structures, Reference Classes, and so on are not supported.

 

Writing Methods for Custom Classes

Almost all functions provided by ‘broadcast’ are S3 or S4 generics.
Users and package authors can write methods for these generics to support custom classes (like custom handling of class-related attributes).