1The **-w** option
2^^^^^^^^^^^^^^^^^
3
4**Syntax**
5
6**-wy**\|\ **a**\|\ **w**\|\ **d**\|\ **h**\|\ **m**\|\ **s**\|\ **c**\ *period*\ [/*phase*][**+c**\ *col*]
7    Convert input records to a cyclical coordinate.
8
9**Description**
10
11The **-w** option converts the input *x*-coordinate to a cyclical coordinate, or a different input column if selected
12via the **+c** modifier. Temporal data (i.e., regular time series) can be analyzed for periods via standard spectral
13analysis, such as offered by :doc:`/spectrum1d` and :doc:`/grdfft`.  However, it is often of interest to examine aspects
14of such periodicities in the time domain.  To enable such analyses we need to convert our monotonically increasing time
15coordinates to periodic or *cyclic* coordinates so that data from many cycles can be stacked, binned, displayed in
16histograms, etc. The conversion from input *x*, *y*, or *z* coordinates to wrapped, periodic coordinates follows the
17simple equation
18
19.. math::
20
21    t' = (t - \tau) \;\mathrm{mod}\; T,
22
23where *t* is the input coordinate, :math:`\tau` is a phase-shift [Default is zero], and *T* is the desired period for the
24modulus operator, yielding cyclic coordinates :math:`t'`. GMT offers many standard time cycles in prescribed units plus
25a custom cycle for other types of Cartesian coordinates. The table below shows the values for units, phase and period
26that are prescribed and only requires the user to specify the corresponding wrapping code (**y**\|\ **a**\|\ **w**\|\
27**d**\|\ **h**\|\ **m**\|\ **s**\|\ **c**\ *period*\ [/*phase*]\):
28
29+------------+---------------------------+------------+--------------+-----------+
30| **Code**   | **Purpose** (**unit**)    | **Period** |  **Phase**   | **Range** |
31+============+===========================+============+==============+===========+
32| **y**      | Yearly cycle (normalized) |  1 year    | 0            |   0–1     |
33+------------+---------------------------+------------+--------------+-----------+
34| **a**      | Annual cycle (month)      |  1 year    | 0            |   0–12    |
35+------------+---------------------------+------------+--------------+-----------+
36| **w**      | Weekly cycle (day)        |  1 week    | 0            |   0–7     |
37+------------+---------------------------+------------+--------------+-----------+
38| **d**      | Daily cycle (hour)        |  1 day     | 0            |   0–24    |
39+------------+---------------------------+------------+--------------+-----------+
40| **h**      | Hourly cycle (minute)     |  1 hour    | 0            |   0–60    |
41+------------+---------------------------+------------+--------------+-----------+
42| **m**      | Minute cycle (second)     |  1 minute  | 0            |   0–60    |
43+------------+---------------------------+------------+--------------+-----------+
44| **s**      | Second cycle (second)     |  1 second  | 0            |   0–1     |
45+------------+---------------------------+------------+--------------+-----------+
46| **c**      | Custom cycle (normalized) |  :math:`T` | :math:`\tau` |   0–1     |
47+------------+---------------------------+------------+--------------+-----------+
48
49Optionally, append **+c**\ *col* to select the input column with the coordinates to be wrapped, [default *col* is 0,
50i.e., the first column]. If the custom cycle **c** is chosen then you must also supply the *period* and optionally
51any *phase* [default is 0] in the same units of your data (i.e., no units should be appended to **-w**).
52
53**Note**: Coordinates for **w** in the range 0-1 correspond to the first day of the week [Monday] but can be changed
54via :term:`TIME_WEEK_START`. **Note**: If a temporal cycle is indicated then we implicitly set **-f** to indicate
55absolute time (unless already set separately). See the cookbook section :ref:`Examining data cycles: The -w option
56<option_-w>` for examples.
57