wextend

Extend vector or matrix

Syntax

YEXT= wextend(TYPE,MODE,X,LEN)

YEXT = wextend(___,LOC)

Description

YEXT= wextend(TYPE,MODE,X,LEN) extends real-valued input vector or matrix X by length LEN, using the TYPE method and MODE extension. The TYPE specifies the dimension of the extension. The MODE specifies the rule to apply to fill in values in the extension.

YEXT = wextend(___,LOC) also specifies the location of the extension.

Examples

Extending Vectors and Matrices

Extend Vector

Extend a vector using a number of different methods.

Create a vector and set the extension length to 2.

len = 2;
x = [1 2 3]

x = 1×3

     1     2     3

Perform a zero-pad extension. To verify that different forms of the input arguments are possible, perform this extension twice. The result is the same both times.

xextzpd1 = wextend('1','zpd',x,len)

xextzpd1 = 1×7

     0     0     1     2     3     0     0

xextzpd2 = wextend('1D','zpd',x,len,'b')

xextzpd2 = 1×7

     0     0     1     2     3     0     0

Perform a half-point symmetric extension.

xextsym = wextend('1D','sym',x,len)

xextsym = 1×7

     2     1     1     2     3     3     2

Perform a periodic extension. Since the input vector is of odd length, wextend appends an extra example to the end before extending using the 'ppd' mode. This sample is equal to the last value on the right.

xextper = wextend('1D','per',x,len)

xextper = 1×8

     3     3     1     2     3     3     1     2

Extend Matrix

Extend a small matrix using a number of different methods.

Create a matrix and set the extension length to 2.

len = 2;
X = [1 2 3; 4 5 6]

X = 2×3

     1     2     3
     4     5     6

Perform a zero-pad extension of the array.

Xextzpd = wextend(2,'zpd',X,len)

Xextzpd = 6×7

     0     0     0     0     0     0     0
     0     0     0     0     0     0     0
     0     0     1     2     3     0     0
     0     0     4     5     6     0     0
     0     0     0     0     0     0     0
     0     0     0     0     0     0     0

Perform a half-point symmetric extension of the array.

Xextsym = wextend('2D','sym',X,len)

Xextsym = 6×7

     5     4     4     5     6     6     5
     2     1     1     2     3     3     2
     2     1     1     2     3     3     2
     5     4     4     5     6     6     5
     5     4     4     5     6     6     5
     2     1     1     2     3     3     2

Extend uint8 Data Beyond Range Limits

Observe the effects of symmetric, antisymmetric, and smooth extensions on a uint8 vector when values are at or near the limits of the data type's range.

Symmetric Extensions

The smallest uint8 integer is 0, and the largest is 255. Create a vector of uint8 integers that includes those limits.

dataVector = uint8([0 1 2 253 254 255])

dataVector = 1x6 uint8 row vector

     0     1     2   253   254   255

Obtain whole-point and half-point symmetric extensions of the vector. Extend the vector by two values on the left and right.

wholePointSym = wextend('1','symw',dataVector,2)

wholePointSym = 1x10 uint8 row vector

     2     1     0     1     2   253   254   255   254   253

halfPointSym = wextend('1','symh',dataVector,2)

halfPointSym = 1x10 uint8 row vector

     1     0     0     1     2   253   254   255   255   254

Extending symmetrically never results in values outside the uint8 range.

Antisymmetric Extensions

Create a type double copy of the vector, and then obtain a whole-point antisymmetric extension of the copy. The extension includes negative values and values greater than 255.

dataVectorDouble = double(dataVector);
wholePointAsymDouble = wextend('1','asymw',dataVectorDouble,2)

wholePointAsymDouble = 1×10

    -2    -1     0     1     2   253   254   255   256   257

Obtain a whole-point antisymmetric extension of the original uint8 vector. Values outside the uint8 range are mapped to the closest uint8 integer, which is 0 for negative values and 255 for values greater than 255.

wholePointAsym = wextend('1','asymw',dataVector,2)

wholePointAsym = 1x10 uint8 row vector

     0     0     0     1     2   253   254   255   255   255

Now obtain half-point antisymmetric extensions of the double copy and the original uint8 vector.

halfPointAsymDouble = wextend('1','asymh',dataVectorDouble,2)

halfPointAsymDouble = 1×10

    -1     0     0     1     2   253   254   255  -255  -254

halfPointAsym = wextend('1','asymh',dataVector,2)

halfPointAsym = 1x10 uint8 row vector

     0     0     0     1     2   253   254   255     0     0

As with the whole-point antisymmetric extension, negative values in the extended uint8 data are mapped to 0.

Smooth Extensions

Obtain order-0 smooth extensions of the double copy and the original uint8 vector.

smooth0Double = wextend('1','sp0',dataVectorDouble,2)

smooth0Double = 1×10

     0     0     0     1     2   253   254   255   255   255

smooth0 = wextend('1','sp0',dataVector,2)

smooth0 = 1x10 uint8 row vector

     0     0     0     1     2   253   254   255   255   255

Results are identical. Next, obtain an order-1 smooth extension of each vector.

smooth1Double = wextend('1','sp1',dataVectorDouble,2)

smooth1Double = 1×10

    -2    -1     0     1     2   253   254   255   256   257

smooth1 = wextend('1','sp1',dataVector,2)

smooth1 = 1x10 uint8 row vector

     0     0     0     1     2   253   254   255   255   255

The values in the double result that are outside the uint8 range are mapped to the closest uint8 values in the uint8 extension.

Extend int8 Data Beyond Range Limits

Observe the effects of symmetric, antisymmetric, and smooth extensions of int8 data when values are at or near the limits of the data type's range.

Symmetric Extensions

The smallest int8 integer is $-128$, and the largest is 127. Create a vector of int8 integers that includes those limits.

dataVector = int8([-128 -127 -126 125 126 127])

dataVector = 1x6 int8 row vector

   -128   -127   -126    125    126    127

Obtain whole-point and half-point symmetric extensions of the data. Extend the vector by two values on the left and right.

wholePointSym = wextend('1','symw',dataVector,2)

wholePointSym = 1x10 int8 row vector

   -126   -127   -128   -127   -126    125    126    127    126    125

halfPointSym = wextend('1','symh',dataVector,2)

halfPointSym = 1x10 int8 row vector

   -127   -128   -128   -127   -126    125    126    127    127    126

Extending symmetrically never results in values outside the int8 range.

Antisymmetric Extensions

Create a type double copy of the vector, and then obtain a whole-point antisymmetric extension of the copy. The extension includes negative values less than $-128$ and values greater than 127.

dataVectorDouble = double(dataVector);
wholePointsAsymDouble = wextend('1','asymw',dataVectorDouble,2)

wholePointsAsymDouble = 1×10

  -130  -129  -128  -127  -126   125   126   127   128   129

Obtain a whole-point antisymmetric extension of the original int8 vector. Values outside the int8 range are mapped to the closest int8 integer, which is $-128$ for values less than $-128$ and 127 for values greater than 127.

wholePointAsym = wextend('1','asymw',dataVector,2)

wholePointAsym = 1x10 int8 row vector

   -128   -128   -128   -127   -126    125    126    127    127    127

Now obtain half-point antisymmetric extensions of the double copy and the original int8 vector.

halfPointAsymDouble = wextend('1','asymh',dataVectorDouble,2)

halfPointAsymDouble = 1×10

   127   128  -128  -127  -126   125   126   127  -127  -126

halfPointAsym = wextend('1','asymh',dataVector,2)

halfPointAsym = 1x10 int8 row vector

    127    127   -128   -127   -126    125    126    127   -127   -126

In the double result, the first value is 127, which can be represented as an int8 integer. The second value is 128, which cannot be represented as an int8 integer. Therefore, in the int8 result, it is being mapped to 127. The remaining values in the type double result can all be represented as int8 integers.

Smooth Extensions

Obtain order-0 smooth extensions of the double copy and the original int8 vector.

smooth0Double = wextend('1','sp0',dataVectorDouble,2)

smooth0Double = 1×10

  -128  -128  -128  -127  -126   125   126   127   127   127

smooth0 = wextend('1','sp0',dataVector,2)

smooth0 = 1x10 int8 row vector

   -128   -128   -128   -127   -126    125    126    127    127    127

The results are identical. Now obtain an order-1 smooth extension of each vector.

smooth1Double = wextend('1','sp1',dataVectorDouble,2)

smooth1Double = 1×10

  -130  -129  -128  -127  -126   125   126   127   128   129

smooth1 = wextend('1','sp1',dataVector,2)

smooth1 = 1x10 int8 row vector

   -128   -128   -128   -127   -126    125    126    127    127    127

The values in the double result outside the int8 range are mapped to the closest int8 values in the int8 extension.

Input Arguments

TYPE — Extension method

1 | '1' | '1d' | '1D' | 2 | '2' | '2d' | '2D' | 'ar' | 'addrow' | 'ac' | 'addcol'

Extension method used on the input, specified as one of the values listed here.

TYPE	Description
1, '1', '1d', or '1D'	1-D extension
2, '2', '2d', or '2D'	2-D extension
'ar' or 'addrow'	Add rows
'ac' or 'addcol'	Add columns

Data Types: double | char

MODE — Specific extension

'zpd' | 'sp0' | 'spd' | 'sp1' | 'sym' | 'symh' | 'symw' | 'asym' | 'asymh' | 'asymw' | 'ppd' | 'per'

Specific extension method to use to extend the input, specified as one of the values listed here. For more information, see dwtmode.

MODE	Description
'zpd'	Zero extension
'sp0'	Smooth extension of order 0
'spd' (or 'sp1')	Smooth extension of order 1
'sym' or 'symh'	Symmetric padding (half point): boundary value symmetric replication
'symw'	Symmetric padding (whole point): boundary value symmetric replication
'asym' or 'asymh'	Antisymmetric padding (half point): boundary value antisymmetric replication
'asymw'	Antisymmetric padding (whole point): boundary value antisymmetric replication
'ppd'	Periodized extension (1)
'per'	Periodized extension (2) If the signal length is odd, wextend appends on the right a copy of the last value, and performs the extension using the 'ppd' mode. Otherwise, 'per' reduces to 'ppd'. This rule also applies to images.

For more information on symmetric extension modes, see [1].

Note

The extension modes 'sp0' and 'spd' (or 'sp1') cast the data internally to double precision before performing the extension. For integer data types, wextend warns if one of the following occurs.

• The conversion to double causes a loss of precision.

• The requested extension results in integers beyond the range where double precision numbers can represent consecutive integers exactly.

Data Types: char

X — Input data

real-valued vector or matrix

Input data, specified as a real-valued vector or matrix.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

LEN — Length of extension

nonnegative integer | two-element vector of nonnegative integers

Length of extension, specified as a nonnegative integer or two-element vector of nonnegative integers. You can extend a matrix by expressing LEN as [LROW,LCOL], where LROW is the number of rows to add and LCOL is the number of columns to add. You can perform a 2-D extension of a matrix by the same amount in both directions by specifying LEN as single integer.

An extension of length 0 is equivalent to the null extension.

Example: wextend('2D','sym',[1 2 3 4;5 6 7 8],[2 0]) extends only two rows up and two rows down.

LOC — Location of extension

'l' | 'u' | 'r' | 'd' | 'b' | 'n' | two-character array

Location of extension, specified as one or a pair of the following:

• 'l' — Extension left

• 'u' — Extension up

• 'r' — Extension right

• 'd' — Extension down

• 'b' — Extension on both sides

• 'n' — Null extension

The valid and default values for LOC, and the behavior of LEN, depend on the specified TYPE.

TYPE	LOC
1, '1', 1d' or '1D'	'l', 'u', 'r', 'd', 'b', or 'n' Example: wextend('1D','zpd',X,3,'r') extends input vector X three elements to the right. Default: 'b' LEN is the length of the extension.
2, '2', '2d' or '2D'	[LOCROW,LOCCOL], where LOCROW and LOCCOL are 1-D extension locations or 'n' (none). Example: wextend('2D','zpd',X,[2 3],'ub') extends input vector or matrix X two rows up and three columns on both sides. Default: 'bb' LEN, specified as [LROW,LCOL], is the number of rows and columns to add.
'ar' or 'addrow'	'l', 'u', 'r', 'd', 'b', or 'n' Example: wextend('addrow','zpd',X,4,'d') extends input vector or matrix X four rows down. Default: 'b' LEN is the number of rows to add.
'ac' or 'addcol'	'l', 'u', 'r', 'd', 'b', or 'n' Example: wextend('addcol','zpd',X,1,'l') extends input vector or matrix X one column to the left. Default: 'b' LEN is the number of columns to add.

Tips

For most wavelet applications, either a periodic extension or symmetric extension works fine.

Algorithms

When a value is outside the input data type's range, wextend maps it to the closest value of the input data type. For examples of data being extended beyond a data type's range, see Extend uint8 Data Beyond Range Limits and Extend int8 Data Beyond Range Limits.

References

[1] Strang, G., and T. Nguyen. Wavelets and Filter Banks. Wellesley, MA: Wellesley-Cambridge Press, 1996.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• The generated code can return a column vector when MATLAB^® returns a row vector if all of the following conditions are true:

  • TYPE specifies a 1-D extension.

  • Input X is a variable-size vector.

  • Input X is not a variable-length row vector (1-by-:).

  Code generation does not produce a warning or error message about the shape mismatch. In the output vector that the generated code returns, the values match the values in the output vector that MATLAB returns.

  In this case, to generate code that returns a row vector, pass X(:).' instead of X.

• Input X must be of type double.

GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

The wextend function supports GPU array input with these usage notes and limitations:

• wextend supports only the 'sym' and 'per' extension modes.

• The only syntax supported is YEXT = wextend(TYPE,MODE,X,LEN).

  • The LOC input argument is not supported.

  • For one-dimensional extensions, the default location 'b' is used. For two-dimensional extensions, the default location 'bb' is used.

• Only extensions in one dimension are supported.

  • The LEN input argument must have length equal to one.

  • For one-dimensional extensions, the only supported extension methods are: 1, '1', '1d', and '1D'.

  • For two-dimensional extensions, the only supported extension methods are: 'addrow', and 'addcol'.

For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Version History

Introduced before R2006a