# ttplot

Plot threshold transitions

Since R2021b

## Syntax

``ttplot(tt)``
``ttplot(tt,Name,Value)``
``ttplot(ax,___)``
``h = ttplot(___)``

## Description

`ttplot` plots transition functions of threshold transitions. To evaluate the transition function for observations of the threshold variable, use `ttdata`.

example

````ttplot(tt)` plots transition bands between states of the threshold transitions `tt` on the y-axis. The plot shows gradient shading of the mixing level in the transition bands.```

example

````ttplot(tt,Name,Value)` uses additional options specified by one or more name-value arguments. For example, `ttplot(tt,Type="graph")` specifies plotting a line plot of the transition function at each threshold level on the same axes.```
````ttplot(ax,___)` plots on the axes specified by `ax` instead of the current axes (`gca`) using any of the input argument combinations in the previous syntaxes.```
````h = ttplot(___)` returns a handle `h` to the threshold transitions plot. Use `h` to modify properties of the plot after you create it.```

## Examples

collapse all

Create discrete threshold transitions at 0 and 2.

```t = [0 2]; tt = threshold(t)```
```tt = threshold with properties: Type: 'discrete' Levels: [0 2] Rates: [] StateNames: ["1" "2" "3"] NumStates: 3 ```

`tt` is a `threshold` object. The specified thresholds split the space into three states.

Plot the threshold transitions.

`ttplot(tt);` `ttplot` graphs a gradient plot by default. The $\mathit{y}$-axis represents the value of the threshold variable ${\mathit{z}}_{\mathit{t}}$ (currently undefined) and the state-space:

• The system is in state 1 when ${\mathit{z}}_{\mathit{t}}<0$.

• The system is in state 2 when $0\le {\mathit{z}}_{\mathit{t}}<2$.

• The system is in state 3 when ${\mathit{z}}_{\mathit{t}}\ge 2$.

Because the transitions are discrete, `ttplot` graphs the levels as lines—the regime switches abruptly when ${\mathit{z}}_{\mathit{t}}$ crosses a threshold variable.

Because ${\mathit{z}}_{\mathit{t}}$ is undefined, the $\mathit{x}$-axis is arbitrary. When you specify threshold variable data by using the `Data` name-value argument, the $\mathit{x}$-axis is the sample index.

This example shows how to create two logistic threshold transitions with different transition rates, and then display a gradient plot of the transitions.

Load the yearly Canadian inflation and interest rates data set. Extract the inflation rate based on consumer price index (`INF_C`) from the table, and plot the series.

```load Data_Canada INF_C = DataTable.INF_C; plot(dates,INF_C); axis tight``` Assume the following characteristics of the inflation rate series:

• Rates below 2% are low.

• Rates at least 2% and below 8% are medium.

• Rates at least 8% are high.

• A logistic transition function describes the transition between states well.

• Transition between low and medium rates are faster than transitions between medium and high.

Create threshold transitions to describe the Canadian inflation rates.

```t = [2 8]; % Thresholds r = [3.5 1.5]; % Transition rates statenames = ["Low" "Med" "High"]; tt = threshold(t,Type="logistic",Rates=r,StateNames=statenames)```
```tt = threshold with properties: Type: 'logistic' Levels: [2 8] Rates: [3.5000 1.5000] StateNames: ["Low" "Med" "High"] NumStates: 3 ```

Plot the threshold transitions; show the gradient of the transition function between the states, and overlay the data.

```figure ttplot(tt,Data=INF_C)``` Create normal cdf threshold transitions at levels 0 and 5, with rates 0.5 and 1.5.

```t = [0 5]; r = [0.5 1.5]; tt = threshold(t,Type="normal",Rates=r)```
```tt = threshold with properties: Type: 'normal' Levels: [0 5] Rates: [0.5000 1.5000] StateNames: ["1" "2" "3"] NumStates: 3 ```

To compare the behavior of the transition functions, plot their graphs at the same level.

```figure ttplot(tt,Type="graph",Width=20)``` Plot the transition functions at their levels. Evaluate the transition function over a 1-D grid of values by using `ttdata`, and then plot the results.

```lower = tt.Levels(1) - 3/min(tt.Rates); upper = tt.Levels(end) + 3/min(tt.Rates); z = lower:0.1:upper; F = ttdata(tt,z,UseZeroLevels=false); figure plot(z,F,LineWidth=2) grid on xlabel("Level") legend(["Level 0, Rate 0.5" "Level 5, Rate 1.5"],Location="NorthWest")``` Create smooth threshold transitions for the Australian to US dollar exchange rate to model price parity.

Load the Australia/US purchasing power and interest rates data set. Extract the log of the exchange rate `EXCH` from the table.

```load Data_JAustralian EXCH = DataTable.EXCH; ```

Consider a two-state system where:

• State 1 occurs when the Australian dollar buys more than the US dollar (`EXCH` $\ge 0$).

• State 2 occurs when the US dollar buys more than the Australian dollar (`EXCH` $<\mathrm{0}$).

• States are weighed more highly as the system deviates from parity (`EXCH` = 0).

Create threshold transitions representing the system. To attribute a greater amount of mixing away from the threshold, specify an exponential transition function. Set the transition rate to 2.5.

`tt = threshold(0,Type="exponential",Rates=2.5)`
```tt = threshold with properties: Type: 'exponential' Levels: 0 Rates: 2.5000 StateNames: ["1" "2"] NumStates: 2 ```

Plot the threshold transitions with the threshold data.

```figure ttplot(tt,Data=EXCH);``` Try improving the display by experimenting with the transition band width (`Width` name-value argument).

```figure ttplot(tt,Data=EXCH,Width=2);``` Plot the transition function.

```figure ttplot(tt,Type="graph");``` ## Input Arguments

collapse all

Threshold transitions, with `NumStates` states, specified as a `threshold` object. `tt` must be fully specified (no `NaN` entries).

Axes on which to plot, specified as an `Axes` object.

By default, `ttplot` plots to the current axes (`gca`).

### Name-Value Arguments

Specify optional pairs of arguments as `Name1=Value1,...,NameN=ValueN`, where `Name` is the argument name and `Value` is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose `Name` in quotes.

Example: `Type="graph"` specifies plotting a line plot of the transition function at each threshold level on the same axes.

Plot type, specified as a value in this table.

ValueDescription
`"gradient"`Gradient shading of the mixing level in each transition band.
`"graph"`

Graphs of transition functions at each level.

`ttplot` plots graphs with levels set to zero.

Example: `Type="graph"`

Data Types: `char` | `string`

Data on a threshold variable zt to include in the plot, specified as a numeric vector.

`ttplot` plots `Data` with gradient shading of transition bands (`Type="gradient"`). If `Type="graph"`, `ttplot` ignores `Data`.

Data Types: `double`

Width of transition bands, specified as a positive numeric scalar.

• For gradient plots (`Type="gradient"`), `ttplot` truncates transition function data outside of the bands.

• For transition function graphs (`Type="graph"`), `ttplot` sets the x-axis limits to `[-Width/2 Width/2]`.

By default, `ttplot` selects the band width automatically.

Example: `Width=10`

Data Types: `double`

## Output Arguments

collapse all

Plot handle, returned as a graphics object. `h` contains a unique plot identifier, which you can use to query or modify properties of the plot.

collapse all

### Mixing Level

The mixing level is the degree to which adjacent states contribute to a response.

Transition functions F vary between 0 and 1; adjacent states are assigned weights F and 1 – F. The mixing level between adjacent states is the minimum weight min(F, 1 – F).

The following characteristics define the mixing behavior of each transition type:

• Discrete transitions have no mixing.

• Normal and logistic transitions achieve maximum mixing at threshold levels.

• Exponential transitions achieve maximum mixing on either side of threshold levels.

For more details, see `threshold`.

## Tips

• Use the `Width` name-value argument to adjust the display of transition function graph (`Type="graph"`) plots with varying rates. In multilevel gradient plots (`Type="gradient"`), a large enough width results in overlapping transition bands that can misrepresent data. By default, `ttplot` chooses an appropriate width for displaying all transitions.

## Version History

Introduced in R2021b