is an object whose elements will automatically be threaded into the lowest level of an array when used in a listable operation such as Plus.

adds elements of an array b to elements of an array a at the lowest possible level.

adds elements at level alev of a.

adds elements at level alev in a to level blev in b.

combines elements for a function f with the attribute Listable.

# Details  • In a+Threaded[b], the lowest-level dimensions of a must match the dimensions of b.
• For a function f with the Listable attribute, f[a,b] effectively applies f to the elements in arrays a and b, working from the uppermost level down. Using Threaded gives control over how the elements are combined in a.
• • If a has dimensions {adim1,,adimj} and b has dimensions {bdim1,,bdimi}, then the levels correspond to dimensions as follows:
• • In f[a,Threaded[b]], a and b should be rectangular arrays with ArrayDepth[a]ArrayDepth[b].
• f[a,Threaded[b,alev]] with alev>0 is equivalent to Map[f[#,b]&,a,{alev-1}] .

# Examples

open allclose all

## Basic Examples(1)

Add the pair {x,y} to each element in a list of pairs:

Without Threaded, adding a list of scalars to the list of pairs would add a scalar value to each pair:

## Scope(7)

Create a rank-three array with dimensions {2,3,4}:

Add a 3×4 matrix to each of the two matrices in the array:

Create a rank-four array with dimensions {2,3,4,2}:

Adding a 3×4 matrix at the deepest threading level will fail because 3×4 differs from 4×2: The matrix can be added at level 2 because the dimensions match:

Since the deepest array has rank 4, this is the same as threading at level -3:

This preserves associativity:

When all of the arguments are Threaded objects, then the result is a single Threaded object:

Compare using Threaded with different positive levels for an array with depth 4:

Compare using Threaded with different negative levels for an array with depth 4:

Use Threaded with an arbitrary listable function:

Threaded arguments can appear in any order:

## Applications(2)

Add a vector to each row of a matrix:

Add a vector to each column of a matrix:

Zero the red channel and double the blue channel in 3D image data:

The same construct works for 2D image data:

## Properties & Relations(8)

Threaded[y,] stays unevaluated unless inside a wrapping head with the Listable attribute:

If the operation cannot be performed, a message will be emitted and Threaded will stay unevaluated: Default threading behavior of a listable function f with arrays a and b corresponds to Threaded[b,1]:

Thread the first level of b at the first level of a:

By default, Threaded[b] threads b at the lowest possible level that does not change the depth of a:

These two threading behaviors are different:

An array threaded at the lowest level is duplicated as a whole to create a sufficiently deep array for an operation:

When it is threaded at a higher level, individual entries are duplicated to fill out the array:

This can also be expressed as Threaded[b,1-ArrayDepth[b]]:

For a listable function f, an array a and a vector v, the use of Threaded can be reproduced with Inner:

A transposition is needed for nondefault threading level:

Compare threading the first level of b at the first level of a, using both Threaded and an explicit Table:

Threading at nondefault levels can be also achieved by using two transpositions:

This permutation moves levels 3 and 4 of a to levels 1 and 2, leaving level 5 unchanged: