Threaded

Threaded[list]

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.

a+Threaded[b]

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

a+Threaded[b,alev]

adds elements at level alev of a.

a+Threaded[b,blevalev]

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

f[a,Threaded[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].
  • Threaded[b] is equivalent to Threaded[b,1-ArrayDepth[b]] or to Threaded[b,-1-1]. »
  • Threaded[b,alev] is equivalent to Threaded[b,1alev].
  • f[a,Threaded[b,alev]] with alev<0 is equivalent to f[a,Threaded[b,ArrayDepth[a]+alev+1].
  • f[a,Threaded[b,alev]] with alev>0 is equivalent to Map[f[#,b]&,a,{alev-1}] .
  • f[Threaded[a,alev], Threaded[b,blev]] gives a result with head Threaded if alev and blev have the same sign.

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:

Combining a scalar with a Threaded argument gives a Threaded result:

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:

Use Threaded with SparseArray objects:

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:

Threaded[b] is equivalent to Threaded[b,-1-1]:

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:

QuantityArray[mags,units] would correspond to Quantity[mags,Threaded[units]] if Quantity had the Listable attribute:

Wolfram Research (2022), Threaded, Wolfram Language function, https://reference.wolfram.com/language/ref/Threaded.html.

Text

Wolfram Research (2022), Threaded, Wolfram Language function, https://reference.wolfram.com/language/ref/Threaded.html.

CMS

Wolfram Language. 2022. "Threaded." Wolfram Language & System Documentation Center. Wolfram Research. https://reference.wolfram.com/language/ref/Threaded.html.

APA

Wolfram Language. (2022). Threaded. Wolfram Language & System Documentation Center. Retrieved from https://reference.wolfram.com/language/ref/Threaded.html

BibTeX

@misc{reference.wolfram_2022_threaded, author="Wolfram Research", title="{Threaded}", year="2022", howpublished="\url{https://reference.wolfram.com/language/ref/Threaded.html}", note=[Accessed: 15-August-2022 ]}

BibLaTeX

@online{reference.wolfram_2022_threaded, organization={Wolfram Research}, title={Threaded}, year={2022}, url={https://reference.wolfram.com/language/ref/Threaded.html}, note=[Accessed: 15-August-2022 ]}