Functions Overview

 

1 Introduction

The ‘broadcast’ package provides 6 main functionalities:

• Broadcasted Infix Operators
• broadcasted dimensional binding of arrays
• casting functions, that cast subset-groups of an array to a new dimension, cast nested lists to dimensional lists, and vice-versa.
• broadcasted generic pair-wise functions
• 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.

 

2 Broadcasted Infix Operators

Base ‘R’ comes with relational (==, !=, etc.), arithmetic (+, -, *, /, etc.), and logical (&, |) 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 approach supports operator precedence, and for the average ‘R’ user, this is sufficient.

The second way is to use the large set ofbc. - 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.

 

2.1 Overloaded operators

The following arithmetic operators have a ‘broadcaster’ method: +, -, *, /, ^, %%, %/%.
The following relational operators have a ‘broadcaster’ method: ==, !=, <, >, <=, >=.
And finally, the & and | operators also have a ‘broadcaster’ method.

 

2.2 bc. - functions

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.rel(): General Relational operations.
  
• 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(): operations that take in arrays of type raw and return an array 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.

 

3 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.

 

3.1 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.

 

4 Casting

‘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.

The following casting functions are currently available:

• acast(): casts group-based subset of an array into a new dimension.
  Useful for, for example, computing grouped broadcasted operations.

• cast_hier2dim(): casts a nested/hierarchical list into a dimensional list (i.e. recursive array).
  Useful because one cannot broadcast through nesting, but one can broadcast along dimensions.

• cast_dim2hier(): casts a dimensional list into a nested/hierarchical list; the opposite of cast_hier2dim.

• cast_dim2flat(): casts a dimensional list into a flattened list, but with names that indicate their original dimensional positions.
  Mostly useful for printing or summarizing dimensional lists.

• dropnests(): drop redundant nesting in lists; mostly used for facilitating the above casting functions.

 

5 General Broadcasted functions

‘broadcast’ provides the bcapply() functions, which are broadcasted apply-like and ifelse-like functions, respectively.

 

6 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.

 

7 Simple linear algebra functions for statistics

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

 

8 Supported Structures

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

 

9 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).