RainbowStats™ · Command reference

LOGDIFF — Logarithmic Changes

Convert positive-valued levels into changes in their natural logarithms.

LOGDIFF calculates fractional log changes for one time series or, in its one-argument form, for each series in a data list. Use it for proportional growth and return analysis, with explicit scaling and observation intervals.

Quick start: monthly production growth

growth = 100*LOGDIFF(SERIES_SINCE(INDPRO,20010101))
LINE_CHART(SET_UNITS(SET_NAME(growth,"Monthly industrial production log change"),"Percent log change"))

Run this example in RainbowStats

This charts one-observation log changes in the monthly industrial production index from January 2001 onward. Multiplication by 100 expresses the result in percent log-change units. It does not annualize the monthly rate.

LOGDIFF does not multiply by 100. A raw value of 0.01 is a log change of 0.01, or 1% when multiplied by 100. The equivalent simple percentage change is approximately 1.005%.

Syntax and supported input types

LOGDIFF(series)
LOGDIFF(series,n)
LOGDIFF(seriesList)
LOG_DIFF(series)

Form	Returns	Meaning
`LOGDIFF(series)`	Data series	One-observation log changes.
`LOGDIFF(series,n)`	Data series	Log changes over `n` observation intervals. Use a positive integer lag.
`LOGDIFF(seriesList)`	Data-series list	One-observation log changes applied separately to every series.
`LOG_DIFF(...)`	Same as LOGDIFF	Alias routed to the same command.

The two-argument form requires a single series and a numeric lag. The dispatcher does not support LOGDIFF(list,n). For an explicit lag across multiple series, transform each separately and then construct a list.

The second argument is a lag, not a differencing order. LOGDIFF(x,12) compares each value with the value 12 observations earlier. It does not apply the one-period transformation twelve times.

Calculation, scaling and interpretation

LOGDIFF(x)[t] = ln(x[t] / x[t−1])
LOGDIFF(x,n)[t] = ln(x[t] / x[t−n])

percent_log_change = 100 × LOGDIFF(x,n)
simple_percent_change = 100 × (EXP(LOGDIFF(x,n)) − 1)

For a level rising from 100 to 110, the raw log change is ln(1.10) ≈ 0.0953102. Multiplying by 100 gives approximately 9.531% log change; the simple percentage increase is exactly 10%.

Operation	Formula	Interpretation
`DIFF(x)`	`x[t] − x[t−1]`	Absolute change in the original variable’s units.
`LOGDIFF(x)`	`ln(x[t] / x[t−1])`	Fractional log change; multiply by 100 for a log change expressed in percent.
Simple percentage change	`100 × (x[t] / x[t−1] − 1)`	Ordinary percentage change; close to 100 × LOGDIFF only for small changes.

On a regular monthly series, n = 12 gives a twelve-month log change. On a regular quarterly series, n = 4 gives a four-quarter log change. These are cumulative changes over the selected interval, not automatically annualized one-period changes.

For an uninterrupted sequence of positive values, one-period log changes add to the log change over the full interval. Their sum is not the cumulative simple percentage return; convert using the exponential when that is the desired quantity.

Examples: one series, longer lags and lists

Plot raw log changes

x = SERIES_SINCE(INDPRO,20010101)
LINE_CHART(LOGDIFF(x))

Express a twelve-month CPI log change in percent

cpi = SERIES_SINCE(CPIAUCSL,20000101)
inflation = 100*LOGDIFF(cpi,12)
LINE_CHART(SET_UNITS(SET_NAME(inflation,"Twelve-month CPI log change"),"Percent log change"))

This uses twelve observations of lag on a monthly series. A level-based year-over-year CPI percentage change uses a different formula:

cpi = SERIES_SINCE(CPIAUCSL,20000101)
LINE_CHART(100*(cpi/LAG(cpi,12)-1))

Transform a list for regression

levels = LIST(SERIES_SINCE(PAYEMS,20010101),SERIES_SINCE(INDPRO,20010101))
changes = LOGDIFF(levels)
r = REGRESSION(changes)
EXTRACT(r,"slideshow")

Both variables enter as fractional one-period log changes. The first series, payroll employment, is the dependent variable. A list remains a list after transformation; displaying it directly may show series metadata rather than a chart.

Use a longer lag for each series in a list

payroll = LOGDIFF(SERIES_SINCE(PAYEMS,20000101),12)
production = LOGDIFF(SERIES_SINCE(INDPRO,20000101),12)
r = REGRESSION(LIST(payroll,production))
EXTRACT(r,"slideshow")

Log changes through EXTRACT

x = SERIES_SINCE(INDPRO,20010101)
growth = EXTRACT(x,"logdiff")
LINE_CHART(growth)

A single SeriesOperator supports the "logdiff" extract and returns a series. This named extract exposes the one-period transformation; it has no lag parameter.

DataListOperator supports direct LOGDIFF(list) but does not implement the "logdiff" extract. Use the direct command for lists.

Working with the data

Use positive levels. Natural-log changes require positive current and comparison values. Do not rely on automatic handling of zeros, negatives or nonfinite data; inspect and prepare the input.
Check observation spacing. A lag is an observation offset. With missing periods or irregular observations, it need not correspond to the intended elapsed calendar time.
Expect fewer observations. The earliest observations lack a comparison within the selected input sample. Clip after transforming when the desired first displayed date needs earlier history.
Distinguish rates from levels. A rate increasing from 4% to 5% rises by one percentage point. Its log change instead describes the proportional change in the rate; use DIFF for percentage-point changes.
Label scaling explicitly. Tested raw output uses “Log Changes” labels. After multiplying by 100 or annualizing, use SET_UNITS and a suitable name to communicate the intended interpretation.
Do not assume stationarity. Log changes can reduce level trends but do not automatically remove seasonality, serial correlation, outliers or structural changes.

DIFF: absolute changes · LAG: previous observations

Learn more

Detailed guide and examples