octave: Rearranging Matrices
16.2 Rearranging Matrices
=========================
-- : fliplr (X)
Flip array left to right.
Return a copy of X with the order of the columns reversed. In
other words, X is flipped left-to-right about a vertical axis. For
example:
fliplr ([1, 2; 3, 4])
⇒ 2 1
4 3
DONTPRINTYET See also: 
flipud XREFflipud, flip XREFflip, *noteDONTPRINTYET See also: flipud XREFflipud, flip XREFflip,
rot90 XREFrot90, rotdim XREFrotdim.
-- : flipud (X)
Flip array upside down.
Return a copy of X with the order of the rows reversed. In other
words, X is flipped upside-down about a horizontal axis. For
example:
flipud ([1, 2; 3, 4])
⇒ 3 4
1 2
DONTPRINTYET See also: fliplr XREFfliplr, flip XREFflip, *noteDONTPRINTYET See also: fliplr XREFfliplr, flip XREFflip,
rot90 XREFrot90, rotdim XREFrotdim.
-- : flip (X)
-- : flip (X, DIM)
Flip array across dimension DIM.
Return a copy of X flipped about the dimension DIM. DIM defaults
to the first non-singleton dimension. For example:
flip ([1 2 3 4])
⇒ 4 3 2 1
flip ([1; 2; 3; 4])
⇒ 4
3
2
1
flip ([1 2; 3 4])
⇒ 3 4
1 2
flip ([1 2; 3 4], 2)
⇒ 2 1
4 3
DONTPRINTYET See also: fliplr XREFfliplr, flipud XREFflipud, *noteDONTPRINTYET DONTPRINTYET See also: fliplr XREFfliplr, flipud XREFflipud,
rot90 XREFrot90, rotdim XREFrotdim, *notepermute:
DONTPRINTYET DONTPRINTYET See also: fliplr XREFfliplr, flipud XREFflipud,
rot90 XREFrot90, rotdim XREFrotdim, permute
XREFpermute, transpose XREFtranspose.
-- : rot90 (A)
-- : rot90 (A, K)
Rotate array by 90 degree increments.
Return a copy of A with the elements rotated counterclockwise in
90-degree increments.
The second argument is optional, and specifies how many 90-degree
rotations are to be applied (the default value is 1). Negative
values of K rotate the matrix in a clockwise direction. For
example,
rot90 ([1, 2; 3, 4], -1)
⇒ 3 1
4 2
rotates the given matrix clockwise by 90 degrees. The following
are all equivalent statements:
rot90 ([1, 2; 3, 4], -1)
rot90 ([1, 2; 3, 4], 3)
rot90 ([1, 2; 3, 4], 7)
The rotation is always performed on the plane of the first two
dimensions, i.e., rows and columns. To perform a rotation on any
other plane, use ‘rotdim’.
DONTPRINTYET See also: rotdim XREFrotdim, fliplr XREFfliplr, *noteDONTPRINTYET See also: rotdim XREFrotdim, fliplr XREFfliplr,
flipud XREFflipud, flip XREFflip.
-- : rotdim (X)
-- : rotdim (X, N)
-- : rotdim (X, N, PLANE)
Return a copy of X with the elements rotated counterclockwise in
90-degree increments.
The second argument N is optional, and specifies how many 90-degree
rotations are to be applied (the default value is 1). Negative
values of N rotate the matrix in a clockwise direction.
The third argument is also optional and defines the plane of the
rotation. If present, PLANE is a two element vector containing two
different valid dimensions of the matrix. When PLANE is not given
the first two non-singleton dimensions are used.
For example,
rotdim ([1, 2; 3, 4], -1, [1, 2])
⇒ 3 1
4 2
rotates the given matrix clockwise by 90 degrees. The following
are all equivalent statements:
rotdim ([1, 2; 3, 4], -1, [1, 2])
rotdim ([1, 2; 3, 4], 3, [1, 2])
rotdim ([1, 2; 3, 4], 7, [1, 2])
DONTPRINTYET See also: rot90 XREFrot90, fliplr XREFfliplr, *noteDONTPRINTYET See also: rot90 XREFrot90, fliplr XREFfliplr,
flipud XREFflipud, flip XREFflip.
-- : cat (DIM, ARRAY1, ARRAY2, ..., ARRAYN)
Return the concatenation of N-D array objects, ARRAY1, ARRAY2, ...,
ARRAYN along dimension DIM.
A = ones (2, 2);
B = zeros (2, 2);
cat (2, A, B)
⇒ 1 1 0 0
1 1 0 0
Alternatively, we can concatenate A and B along the second
dimension in the following way:
[A, B]
DIM can be larger than the dimensions of the N-D array objects and
the result will thus have DIM dimensions as the following example
shows:
cat (4, ones (2, 2), zeros (2, 2))
⇒ ans(:,:,1,1) =
1 1
1 1
ans(:,:,1,2) =
0 0
0 0
See also: horzcat XREFhorzcat, vertcat XREFvertcat.
-- : horzcat (ARRAY1, ARRAY2, ..., ARRAYN)
Return the horizontal concatenation of N-D array objects, ARRAY1,
ARRAY2, ..., ARRAYN along dimension 2.
Arrays may also be concatenated horizontally using the syntax for
creating new matrices. For example:
HCAT = [ ARRAY1, ARRAY2, ... ]
See also: cat XREFcat, vertcat XREFvertcat.
-- : vertcat (ARRAY1, ARRAY2, ..., ARRAYN)
Return the vertical concatenation of N-D array objects, ARRAY1,
ARRAY2, ..., ARRAYN along dimension 1.
Arrays may also be concatenated vertically using the syntax for
creating new matrices. For example:
VCAT = [ ARRAY1; ARRAY2; ... ]
See also: cat XREFcat, horzcat XREFhorzcat.
-- : permute (A, PERM)
Return the generalized transpose for an N-D array object A.
The permutation vector PERM must contain the elements ‘1:ndims (A)’
(in any order, but each element must appear only once). The Nth
dimension of A gets remapped to dimension ‘PERM(N)’. For example:
X = zeros ([2, 3, 5, 7]);
size (X)
⇒ 2 3 5 7
size (permute (X, [2, 1, 3, 4]))
⇒ 3 2 5 7
size (permute (X, [1, 3, 4, 2]))
⇒ 2 5 7 3
## The identity permutation
size (permute (X, [1, 2, 3, 4]))
⇒ 2 3 5 7
See also: ipermute XREFipermute.
-- : ipermute (A, IPERM)
The inverse of the ‘permute’ function.
The expression
ipermute (permute (A, perm), perm)
returns the original array A.
See also: permute XREFpermute.
-- : reshape (A, M, N, ...)
-- : reshape (A, [M N ...])
-- : reshape (A, ..., [], ...)
-- : reshape (A, SIZE)
Return a matrix with the specified dimensions (M, N, ...) whose
elements are taken from the matrix A.
The elements of the matrix are accessed in column-major order (like
Fortran arrays are stored).
The following code demonstrates reshaping a 1x4 row vector into a
2x2 square matrix.
reshape ([1, 2, 3, 4], 2, 2)
⇒ 1 3
2 4
Note that the total number of elements in the original matrix
(‘prod (size (A))’) must match the total number of elements in the
new matrix (‘prod ([M N ...])’).
A single dimension of the return matrix may be left unspecified and
Octave will determine its size automatically. An empty matrix ([])
is used to flag the unspecified dimension.
DONTPRINTYET See also: resize XREFresize, vec XREFvec, *noteDONTPRINTYET DONTPRINTYET See also: resize XREFresize, vec XREFvec,
postpad XREFpostpad, cat XREFcat, *notesqueeze:
DONTPRINTYET DONTPRINTYET See also: resize XREFresize, vec XREFvec,
postpad XREFpostpad, cat XREFcat, squeeze
XREFsqueeze.
-- : resize (X, M)
-- : resize (X, M, N, ...)
-- : resize (X, [M N ...])
Resize X cutting off elements as necessary.
In the result, element with certain indices is equal to the
corresponding element of X if the indices are within the bounds of
X; otherwise, the element is set to zero.
In other words, the statement
y = resize (x, dv)
is equivalent to the following code:
y = zeros (dv, class (x));
sz = min (dv, size (x));
for i = 1:length (sz)
idx{i} = 1:sz(i);
endfor
y(idx{:}) = x(idx{:});
but is performed more efficiently.
If only M is supplied, and it is a scalar, the dimension of the
result is M-by-M. If M, N, ... are all scalars, then the
dimensions of the result are M-by-N-by-.... If given a vector as
input, then the dimensions of the result are given by the elements
of that vector.
An object can be resized to more dimensions than it has; in such
case the missing dimensions are assumed to be 1. Resizing an
object to fewer dimensions is not possible.
See also: reshape XREFreshape, postpad XREFpostpad,
prepad XREFprepad, cat XREFcat.
-- : Y = circshift (X, N)
-- : Y = circshift (X, N, DIM)
Circularly shift the values of the array X.
N must be a vector of integers no longer than the number of
dimensions in X. The values of N can be either positive or
negative, which determines the direction in which the values of X
are shifted. If an element of N is zero, then the corresponding
dimension of X will not be shifted.
If a scalar DIM is given then operate along the specified
dimension. In this case N must be a scalar as well.
Examples:
x = [1, 2, 3; 4, 5, 6; 7, 8, 9];
circshift (x, 1)
⇒ 7, 8, 9
1, 2, 3
4, 5, 6
circshift (x, -2)
⇒ 7, 8, 9
1, 2, 3
4, 5, 6
circshift (x, [0,1])
⇒ 3, 1, 2
6, 4, 5
9, 7, 8
See also: permute XREFpermute, ipermute XREFipermute,
shiftdim XREFshiftdim.
-- : shift (X, B)
-- : shift (X, B, DIM)
If X is a vector, perform a circular shift of length B of the
elements of X.
If X is a matrix, do the same for each column of X.
If the optional DIM argument is given, operate along this
dimension.
-- : Y = shiftdim (X, N)
-- : [Y, NS] = shiftdim (X)
Shift the dimensions of X by N, where N must be an integer scalar.
When N is positive, the dimensions of X are shifted to the left,
with the leading dimensions circulated to the end. If N is
negative, then the dimensions of X are shifted to the right, with N
leading singleton dimensions added.
Called with a single argument, ‘shiftdim’, removes the leading
singleton dimensions, returning the number of dimensions removed in
the second output argument NS.
For example:
x = ones (1, 2, 3);
size (shiftdim (x, -1))
⇒ [1, 1, 2, 3]
size (shiftdim (x, 1))
⇒ [2, 3]
[b, ns] = shiftdim (x)
⇒ b = [1, 1, 1; 1, 1, 1]
⇒ ns = 1
See also: reshape XREFreshape, permute XREFpermute,
DONTPRINTYET ipermute XREFipermute, circshift XREFcircshift, *noteDONTPRINTYET ipermute XREFipermute, circshift XREFcircshift,
squeeze XREFsqueeze.
-- : [S, I] = sort (X)
-- : [S, I] = sort (X, DIM)
-- : [S, I] = sort (X, MODE)
-- : [S, I] = sort (X, DIM, MODE)
Return a copy of X with the elements arranged in increasing order.
For matrices, ‘sort’ orders the elements within columns
For example:
sort ([1, 2; 2, 3; 3, 1])
⇒ 1 1
2 2
3 3
If the optional argument DIM is given, then the matrix is sorted
along the dimension defined by DIM. The optional argument ‘mode’
defines the order in which the values will be sorted. Valid values
of ‘mode’ are "ascend" or "descend".
The ‘sort’ function may also be used to produce a matrix containing
the original row indices of the elements in the sorted matrix. For
example:
[s, i] = sort ([1, 2; 2, 3; 3, 1])
⇒ s = 1 1
2 2
3 3
⇒ i = 1 3
2 1
3 2
For equal elements, the indices are such that equal elements are
listed in the order in which they appeared in the original list.
Sorting of complex entries is done first by magnitude (‘abs (Z)’)
and for any ties by phase angle (‘angle (z)’). For example:
sort ([1+i; 1; 1-i])
⇒ 1 + 0i
1 - 1i
1 + 1i
NaN values are treated as being greater than any other value and
are sorted to the end of the list.
The ‘sort’ function may also be used to sort strings and cell
arrays of strings, in which case ASCII dictionary order (uppercase
’A’ precedes lowercase ’a’) of the strings is used.
The algorithm used in ‘sort’ is optimized for the sorting of
partially ordered lists.
DONTPRINTYET See also: sortrows XREFsortrows, *noteissorted:
DONTPRINTYET See also: sortrows XREFsortrows, issorted
XREFissorted.
-- : [S, I] = sortrows (A)
-- : [S, I] = sortrows (A, C)
Sort the rows of the matrix A according to the order of the columns
specified in C.
By default (C omitted, or a particular column unspecified in C) an
ascending sort order is used. However, if elements of C are
negative then the corresponding column is sorted in descending
order. If the elements of A are strings then a lexicographical
sort is used.
Example: sort by column 2 in descending order, then 3 in ascending
order
x = [ 7, 1, 4;
8, 3, 5;
9, 3, 6 ];
sortrows (x, [-2, 3])
⇒ 8 3 5
9 3 6
7 1 4
See also: sort XREFsort.
-- : issorted (A)
-- : issorted (A, MODE)
-- : issorted (A, "rows", MODE)
Return true if the array is sorted according to MODE, which may be
either "ascending", "descending", or "either".
By default, MODE is "ascending". NaNs are treated in the same
manner as ‘sort’.
If the optional argument "rows" is supplied, check whether the
array is sorted by rows as output by the function ‘sortrows’ (with
no options).
This function does not support sparse matrices.
See also: sort XREFsort, sortrows XREFsortrows.
-- : nth_element (X, N)
-- : nth_element (X, N, DIM)
Select the n-th smallest element of a vector, using the ordering
defined by ‘sort’.
The result is equivalent to ‘sort(X)(N)’.
N can also be a contiguous range, either ascending ‘l:u’ or
descending ‘u:-1:l’, in which case a range of elements is returned.
If X is an array, ‘nth_element’ operates along the dimension
defined by DIM, or the first non-singleton dimension if DIM is not
given.
Programming Note: nth_element encapsulates the C++ standard library
algorithms nth_element and partial_sort. On average, the
complexity of the operation is O(M*log(K)), where
‘M = size (X, DIM)’ and ‘K = length (N)’. This function is
intended for cases where the ratio K/M is small; otherwise, it may
be better to use ‘sort’.
DONTPRINTYET See also: sort XREFsort, min XREFmin, *notemax:
DONTPRINTYET See also: sort XREFsort, min XREFmin, max
XREFmax.
-- : tril (A)
-- : tril (A, K)
-- : tril (A, K, PACK)
-- : triu (A)
-- : triu (A, K)
-- : triu (A, K, PACK)
Return a new matrix formed by extracting the lower (‘tril’) or
upper (‘triu’) triangular part of the matrix A, and setting all
other elements to zero.
The second argument is optional, and specifies how many diagonals
above or below the main diagonal should also be set to zero.
The default value of K is zero, so that ‘triu’ and ‘tril’ normally
include the main diagonal as part of the result.
If the value of K is nonzero integer, the selection of elements
starts at an offset of K diagonals above or below the main
diagonal; above for positive K and below for negative K.
The absolute value of K must not be greater than the number of
subdiagonals or superdiagonals.
For example:
tril (ones (3), -1)
⇒ 0 0 0
1 0 0
1 1 0
and
tril (ones (3), 1)
⇒ 1 1 0
1 1 1
1 1 1
If the option "pack" is given as third argument, the extracted
elements are not inserted into a matrix, but rather stacked
column-wise one above other.
See also: diag XREFdiag.
-- : V = vec (X)
-- : V = vec (X, DIM)
Return the vector obtained by stacking the columns of the matrix X
one above the other.
Without DIM this is equivalent to ‘X(:)’.
If DIM is supplied, the dimensions of V are set to DIM with all
elements along the last dimension. This is equivalent to ‘shiftdim
(X(:), 1-DIM)’.
DONTPRINTYET See also: vech XREFvech, resize XREFresize, *noteDONTPRINTYET See also: vech XREFvech, resize XREFresize,
cat XREFcat.
-- : vech (X)
Return the vector obtained by eliminating all superdiagonal
elements of the square matrix X and stacking the result one column
above the other.
This has uses in matrix calculus where the underlying matrix is
symmetric and it would be pointless to keep values above the main
diagonal.
See also: vec XREFvec.
-- : prepad (X, L)
-- : prepad (X, L, C)
-- : prepad (X, L, C, DIM)
Prepend the scalar value C to the vector X until it is of length L.
If C is not given, a value of 0 is used.
If ‘length (X) > L’, elements from the beginning of X are removed
until a vector of length L is obtained.
If X is a matrix, elements are prepended or removed from each row.
If the optional argument DIM is given, operate along this
dimension.
If DIM is larger than the dimensions of X, the result will have DIM
dimensions.
DONTPRINTYET See also: postpad XREFpostpad, cat XREFcat, *noteDONTPRINTYET See also: postpad XREFpostpad, cat XREFcat,
resize XREFresize.
-- : postpad (X, L)
-- : postpad (X, L, C)
-- : postpad (X, L, C, DIM)
Append the scalar value C to the vector X until it is of length L.
If C is not given, a value of 0 is used.
If ‘length (X) > L’, elements from the end of X are removed until a
vector of length L is obtained.
If X is a matrix, elements are appended or removed from each row.
If the optional argument DIM is given, operate along this
dimension.
If DIM is larger than the dimensions of X, the result will have DIM
dimensions.
DONTPRINTYET See also: prepad XREFprepad, cat XREFcat, *noteDONTPRINTYET See also: prepad XREFprepad, cat XREFcat,
resize XREFresize.
-- : M = diag (V)
-- : M = diag (V, K)
-- : M = diag (V, M, N)
-- : V = diag (M)
-- : V = diag (M, K)
Return a diagonal matrix with vector V on diagonal K.
The second argument is optional. If it is positive, the vector is
placed on the K-th superdiagonal. If it is negative, it is placed
on the -K-th subdiagonal. The default value of K is 0, and the
vector is placed on the main diagonal. For example:
diag ([1, 2, 3], 1)
⇒ 0 1 0 0
0 0 2 0
0 0 0 3
0 0 0 0
The 3-input form returns a diagonal matrix with vector V on the
main diagonal and the resulting matrix being of size M rows x N
columns.
Given a matrix argument, instead of a vector, ‘diag’ extracts the
K-th diagonal of the matrix.
-- : blkdiag (A, B, C, ...)
Build a block diagonal matrix from A, B, C, ...
All arguments must be numeric and either two-dimensional matrices
or scalars. If any argument is of type sparse, the output will
also be sparse.
DONTPRINTYET See also: diag XREFdiag, horzcat XREFhorzcat, *noteDONTPRINTYET See also: diag XREFdiag, horzcat XREFhorzcat,
vertcat XREFvertcat, sparse XREFsparse.
Info Catalog
octave: Finding Elements and Checking Conditions
octave: Matrix Manipulation
octave: Special Utility Matrices