Documentation/Calc Functions/FOURIER

From The Document Foundation Wiki
Jump to navigation Jump to search
Other languages:
English • ‎Nederlands

Function name:

FOURIER

Category:

Array

Summary:

Performs Fourier analysis of a data set by computing the Discrete Fourier Transform (DFT) of an input array of complex numbers, using Fast Fourier Transform (FFT) algorithms.

Note pin.svg

Note:
Calc includes a tool that may provide you with a more user-friendly method for setting up your Fourier analysis, compared to direct creation of formulas via the Input line or the Function Wizard. The Fourier Analysis tool utilizes calls to the FOURIER function and is accessed by selecting Data ▸ Statistics ▸ Fourier Analysis on the Menu bar. More information about the tool can be found on the Fourier Analysis page in the Help system.

Syntax:

FOURIER(Array; Grouped By Columns [; Inverse [; Polar [; Minimum Magnitude]]])

Returns:

Returns an array containing a sequence of complex numbers that are the transformed values. The output array is a 2 × N or N × 2 cell range, where N is the number of complex numbers contained in the input array.

Arguments:

Array is a 2 × N or N × 2 cell range, containing an array of complex numbers to be transformed, where N is the length of the array. Array may be a specific cell range (for example, "$SourceData.A3:B12"), the name of a named or database range, or an inline array. If your input array comprises only real numbers, then a 1 × N or N × 1 cell range is accepted.

Grouped By Columns is a logical value (TRUE or FALSE), or a reference to a cell containing a logical value, that indicates whether Array is grouped by columns or rows. When TRUE (or any non-zero value), the array is grouped by columns where the first column contains the real parts of the complex numbers and the second column contains their imaginary parts. When FALSE (or 0), the first row contains the real parts of the complex numbers and the second row contains their imaginary parts. If there is only one column or row, the input sequence is treated as purely real.

Inverse is a logical value (TRUE or FALSE), or a reference to a cell containing a logical value, that controls whether DFT or inverse DFT processing is required. When TRUE (or any non-zero value), FOURIER calculates the inverse DFT for the input array. When FALSE (or 0). FOURIER calculates the DFT. If Inverse is omitted, the default value is FALSE.

Polar is a logical value (TRUE or FALSE), or a reference to a cell containing a logical value, that controls whether the final output is in polar coordinates (magnitude and phase). When TRUE (or any non-zero value), FOURIER outputs data using polar coordinates. When FALSE (or 0), FOURIER outputs data using Cartesian coordinates. If Polar is omitted, the default value is FALSE.

Minimum Magnitude is a real number, or a reference to a cell containing a real number, that is only used if the Polar argument is set to TRUE. All frequency components with magnitude less than Minimum Magnitude will be suppressed with a zero magnitude-phase entry. This is very useful when looking at the magnitude-phase spectrum of a signal because there is always some very tiny amount of rounding error when doing FFT algorithms and results in incorrect non-zero phase for non-existent frequencies. By providing a suitable value to this parameter, these non-existent frequency components can be suppressed. If Minimum Magnitude is omitted, the default value is 0.0, so that no suppression is performed.

The following conditions may arise:

  • If Array encompasses more than one cell range, then FOURIER reports an invalid argument error (Err:502).
  • If Array includes any cells containing non-numeric data, then FOURIER reports a #VALUE! error.
  • If Grouped By Columns is non-numeric, then FOURIER reports a #VALUE! error.
  • If Grouped By Columns is TRUE (or a non-zero value) and Array contains more than two columns, then FOURIER reports an invalid argument error (Err:502).
  • If Grouped By Columns is FALSE (or 0) and Array contains more than two rows, then FOURIER reports an invalid argument error (Err:502).

Additional details:

Details specific to FOURIER function

  • The mathematics behind this function is beyond the scope of this wiki but more background information can be found at Wikipedia's Fourier analysis page and in the sources that it references.
  • For those with a technical interest in the algorithms used by the FOURIER function, a radix-2 decimation-in-time FFT is used when the length of the input sequence is an even power of 2, while Bluestein’s FFT algorithm is used when the length of the input sequence is not an even power of 2.


General information about Calc's array functions

Note pin.svg

Note:
For convenience, the information in this subsection is repeated on all pages describing Calc's array functions.

To avoid repetition within the subsequent text, only Windows/Linux key combinations are specified. The following table shows the mapping between these key combinations and their macOS equivalents.


Mapping between relevant Windows/Linux and macOS key combinations
Windows/Linux key combination macOS equivalent Comments
Ctrl + ⇧ Shift + ↵ Enter ⌘ Cmd + ⇧ Shift + ↵ Enter Create an array formula.
Ctrl + / ⌘ Cmd + / Select all cells in an array formula range. "/" is the division key on the numeric keypad.
Ctrl + C ⌘ Cmd + C Copy.
Ctrl + V ⌘ Cmd + V Paste.


  • An array is a rectangular range of cells containing data. For example, a square range of three rows by three columns is a 3 x 3 array. The smallest possible array is a 1 x 2 or 2 x 1 array, with two adjacent cells.
  • A formula in which the individual values in a cell range are evaluated is referred to as an array formula. The difference between an array formula and other formulas is that the array formula deals with several values simultaneously instead of just one.
  • If you create an array formula using the Function Wizard, you must mark the Array check box so that the results are returned in an array. Otherwise, only the value in the upper-left cell of the array being calculated is returned.
  • If you enter the array formula directly into the cell, you must use the key combination Ctrl + ⇧ Shift + ↵ Enter instead of just the ↵ Enter key. Only then does the formula become an array formula.
  • An array formula is displayed inside curly brackets or braces ("{" and "}"). It is not possible to create an array formula by manually entering these braces.
  • Some array functions take parameters that are forced to evaluate as an array formula, even when the formula is entered normally. These are MDETERM, MINVERSE, MMULT, SUMPRODUCT, SUMX2MY2, SUMX2PY2, and SUMXMY2.
  • Calc supports constant inline arrays in formulas. An inline array is enclosed within curly brackets or braces ("{" and "}"). Individual elements can be numbers (including negatives), logical constants (TRUE, FALSE), or literal strings. Non-constant expressions are not allowed. Arrays can be entered with one or more rows, and one or more columns. All rows must comprise the same number of elements; similarly, all columns must comprise the same number of elements.
  • Editing array formulas. Select the cell range containing the array formula. To select the whole range, position the cursor inside the range and press Ctrl + /. Then press F2 or position the cursor in the Input line, edit the formula as required, and use the key combination Ctrl + ⇧ Shift + ↵ Enter.
  • Deleting array formulas. Select the cell range containing the array formula. To select the whole range, position the cursor inside the range and press Ctrl + /. Press Delete to delete the array contents, including the array formula. Alternatively, press ← Backspace to bring up the Delete Contents dialog box, select Formulas or Delete all, and click OK.
  • Copying array formulas. Select the cell range containing the array formula. To select the whole range, position the cursor inside the range and press Ctrl + /. Then press F2 or position the cursor in the Input line. Copy the formula by pressing Ctrl + C. Select a range of cells where you want to insert the array formula and either press F2 or position the cursor in the Input line. Paste the formula by pressing Ctrl + V in the selected space and confirm it using the key combination Ctrl + ⇧ Shift + ↵ Enter. The selected range now contains the array formula.
  • Adjusting an array range. Select the cell range containing the array formula. To select the whole range, position the cursor inside the range and press Ctrl + /. Below the selection, to the right, you will see a small icon with which you can zoom in or out on the range using your mouse. When you adjust the array range, the array formula will not be adjusted automatically - you are only changing the range in which the results will appear.


Examples:

The help page for the Fourier function provides a complex example. The following simple examples are intended to help understand the mechanics of using the function and do not represent real-world scenarios. The input data is assumed to be as shown in the following table.

Sample input data for FOURIER function
A B C D E F
1 1 0.2 1 2 3
2 2 0.4 0.2 0.4 0.6
3 3 0.6

The following examples are based on the above sample data.

Formula Description Returns
{=FOURIER(A1:B3, TRUE())} entered as an array formula after selecting cell A5. Here the function calculates a DFT for the input data in cells A1:B3. Cells A5:B7 are populated with the following output values: 6 (cell A5), 1.2 (B5), -1.67320508075689 (A6), 0.566025403784438 (B6), -1.32679491924311 (A7), -1.16602540378444 (B7). See Description
{=FOURIER(D1:F2, FALSE())} entered as an array formula after selecting cell A5. Here the function calculates a DFT for the input data in cells D1:F2. Cells A5:B7 are populated with exactly the same output values as those in the previous example: 6 (cell A5), 1.2 (B5), -1.67320508075689 (A6), 0.566025403784438 (B6), -1.32679491924311 (A7), -1.16602540378444 (B7). See Description
{=FOURIER(input_data; D5; D6)} entered as an array formula after selecting cell A5. input_data is a named range defined to cover the cell range A1:B3, while cells D5 and D6 both contain the logical value TRUE. Here the function calculates an inverse DFT for the input data in cells A1:B3. Cells A5:B7 are populated with the following output values: 2 (cell A5), 0.4 (B5), -0.442264973081038 (A6), -0.388675134594813 (B6), -0.557735026918962 (A7), 0.188675134594813 (B7). See Description
{=FOURIER(input_data; D5; D6; D7; D8)} entered as an array formula after selecting cell A5. input_data is a named range defined to cover the cell range A1:B3, while cells D5: D8 contain the values TRUE, FALSE, TRUE, and 0.0 respectively. Here the function calculates a DFT for the input data in cells A1:B3. However, in contrast to previous examples, the results are output in polar coordinates. Cells A5:B7 are populated with the following output values: 6.11882341631134 (cell A5), 0.197395559849881 (B5), 1.76635217326557 (A6), 2.81538943784138 (B6), 1.76635217326557 (A7), -2.42059831814161 (B7). See Description
{=FOURIER(input_data; D5; D6; D7; D8)} entered as an array formula after selecting cell A5. input_data is a named range defined to cover the cell range A1:B3, while cells D5: D8 contain the values TRUE, FALSE, TRUE, and 2.0 respectively. Here the function calculates a DFT for the input data in cells A1:B3. The results are output in polar coordinates but the Minimum Magnitude argument is set to 2.0 rather than 0.0 (as in the previous example). Cells A5:B7 are populated with the following output values: 6.11882341631134 (cell A5), 0.197395559849881 (B5), 0 (A6), 0 (B6), 0 (A7), 0 (B7). See Description
{=FOURIER(A1:A3, TRUE())} entered as an array formula after selecting cell A5. Here the function calculates a DFT for the input data in cells A1:A3. Thus the input values are real, with no imaginary component. Cells A5:B7 are populated with the following output values: 6 (cell A5), 2.57305788658456E-16 (B5), -1.5 (A6), 0.866025403784438 (B6), -1.5 (A7), -0.866025403784441 (B7). See Description

Related LibreOffice functions:

None.

ODF standard:

None.

Equivalent Excel functions:

None.