, Ravel

One-argument form  See also two-argument form Catenate, Laminate

Ravel

Ravel converts data into a vector. If applied to a scalar, it produces a one- element vector. If applied to a matrix or higher dimensional array, it produces a vector made from the elements in the array.

             NUM ← ,34               (34 is converted to a 1-element vector)
             ⍴ NUM                   (An enquiry about the size of NUM
       1                              produces the answer, 1)
             TABLE                   (TABLE contains 2 5-row columns)
       1 3 7 3 8
       3 6 2 8 1
             ,TABLE                  (TABLE is converted to a 10-element
       1 3 7 3 8 3 6 2 8 1            vector)
             TWIG←2 4⍴'ABC' 1 2 (⍳3) (2 2⍴⍳4) 'DEF' (2 2⍴'CART') 102.2
             TWIG                    (Nested matrix, shape 2 4)
        ABC    1   2 1 2 3

        1 2  DEF  CA 102.2
        3 4       RT
             ⍴TWIG
       2 4
             ,TWIG                   (Ravel produces a nested vector)
        ABC  1  2   1 2 3    1 2 DEF    CA 102.2
                             3 4        RT
             ⍴,TWIG
       8

See also the function ∊ (enlist) which entirely removes nesting.

Ravel with axis

When used in conjunction with an axis specification, ravel can either increase or decrease the rank of its argument. Fractional axis specifications will increase the rank, whilst integer axis specifications will decrease the rank.

A fractional axis specification must be not more than one less than the first dimension or not greater than one more than the last axis. A new axis of length 1 is added in a position governed by the value of the axis specification. As with other axis operations this is affected by the value of ⎕IO. With ⎕IO set to 1, the default:

             ⎕IO
       1
             MAT←2 2⍴⍳4
             MAT
       1 2
       3 4
             ,[.1]MAT                (Add a length 1 axis before the first
       1 2                           axis)
       3 4
             ⍴,[.1]MAT               (Shape of result)
       1 2 2
             ,[1.1]MAT               (Add a length 1 axis between axes 1 and 2)
       1 2

       3 4
             ⍴,[1.1]MAT              (Shape of result)
       2 1 2
             ,[2.8]MAT               (Add a length 1 axis after the second axis)
       1
       2

       3
       4
             ⍴,[2.8]MAT              (Shape of result)
       2 2 1

When used with an integer axis specification ravel will reduce the rank. The axes must be contiguous and in ascending order.

             SAT←2 3 2⍴⍳12
             SAT
       1  2
       3  4
       5  6

       7  8
       9 10
      11 12
             ⍴SAT
      2 3 2
             ,[2 1]SAT               (Axes not in ascending order)
      AXIS ERROR
             ,[2 1]SAT
             ^

With a correctly formed set of axes, the rank of the result is one more than the difference between the rank of the right argument and the number of axes in the axis specification. The shape may be predicted by adding the lengths of the axes specified and combining the result with those axes left unspecified.

             ,[1 2]SAT               (SAT is rank 3, two axes in the
         1  2                         axis specification.)
         3  4
         5  6
         7  8
         9 10
        11 12
             ,[2 3]SAT               (Rank of result is 1+3-2 or 2, a matrix)
         1  2  3  4  5  6
         7  8  9 10 11 12
             ,[1 2 3]SAT             (Three axes in the specification)
       1 2 3 4 5 6 7 8 9 10 11 12    (Rank of result is 1+3-3 or 1, a vector)
             ⍴,[1 2]SAT              (Shape of result from adding lengths of
       6 2                            axes 1 and 2, plus length of axis 3)

If the axis specification contains an empty vector, the result will have a dimension of length one added after the last dimension of the argument.

             ⍴,[⍳0]SAT               (Empty vector axis specification)
       2 3 2 1                       (Dimension added at the end)

Ravel with axis can be used for selective specification:

             ⍴(,[1 2]SAT)            (The variable SAT as used above)
       6 2
             (,[1 2]SAT)←6 2⍴'ABCDEFGHIJKL'
             SAT
       AB
       CD
       EF

       GH
       IJ
       KL