*! version 1.0.0 11jul2026

Title

hpcm -- Hosoya (2001) partial measures of causality by one-way-effect elimination

Syntax

hpcm xvar yvar zvar [if] [in] [, options]

hpcm (xvars) (yvars) (zvars) [if] [in] [, options]

where the three groups are the pair of processes of interest, x and y,
and the conditioning ("third") process z. Each group may be a single series
or, in parentheses, a vector of series. The data must be tsset as a single
time series (no gaps).

Model
var(#) order p of the VAR fitted to (x,y,z); if omitted it is
chosen by an information criterion

maxvar(#) maximum order searched when var() is omitted; default maxvar(8)

ic(string) selection criterion: aic (default), bic, or hqic

difference(#) difference each series # times first (Section 5 reduction for I(1) data)

Spectral computation
grid(#) number of frequency points on [0,{&pi}]; default grid(300)

mlag(#) order m of the auxiliary VAR used for the canonical
factorization of the cleaned pair; default mlag(20)

matrunc(#) MA truncation used for the autocovariances; default matrunc(1200)

band(lo hi) frequency band (radians, 0{&le}lo<hi{&le}{&pi}) for the band
measures and Wald tests; default is the full band band(0 pi)

Inference
nowald suppress the Wald non-causality tests (Section 6)

breps(#) parametric-bootstrap replications for CIs of the band measures

seed(string) random-number seed for the bootstrap

level(#) confidence level for the bootstrap CIs; default level(95)

Reporting
nodecompose report only the two directional measures

plot draw the frequency-domain measure curves

name(string) name for the graph(s); default hpcm

nodraw build but do not display the graph

noheader suppress the header block

Description

hpcm implements the partial measures of causality of Hosoya (2001) for a
pair of (vector) time series x and y observed together with a third
(vector) series z. Ordinary conditioning on the whole history of z
(as in Granger's partial cross-spectrum or Geweke's conditional measures) distorts
the feedback between x and y and can manufacture the spurious causality of
Hsiao (1982). Instead, Hosoya eliminates from x and y only the
one-way-effect component of z -- the part of z that drives (x,y)
without suffering feedback from them -- and defines the partial causal relations
between x and y as the simple one-way-effect measures between the two
cleaned series u and v.

Four measures are reported, each as a frequency-wise curve M({&lambda}) and as an
overall value (the integral (1/2{&pi}){&int}M({&lambda})d{&lambda}, Theorem 4.1):

PM(y{&rarr}x:z) one-way effect from y to x given z (eq 4.4, 4.5)

PM(x{&rarr}y:z) one-way effect from x to y given z

PM(x:y:z) reciprocity / instantaneous feedback (eq 4.7)

PM(x,y:z) association (total interdependence) (eq 4.6)

These satisfy the exact decomposition (Theorem 4.2)

PM(x,y:z) = PM(x{&rarr}y:z) + PM(x:y:z) + PM(y{&rarr}x:z)

which hpcm uses internally: the reciprocity term is obtained from this
identity, so association always equals the sum of the other three. All four
measures are non-negative; a directional measure is zero if and only if there is no
partial causality in that direction (Theorem 4.3). The full equation-by-equation
derivation is in help hpcm methods.

Options

Model

var(#) sets the order p of the VAR fitted to the joint process
(x,y,z). With a finite VAR the canonical (Wold) factorization needed by the
measures is available in closed form, which is what makes the computation feasible
(the Yao-Hosoya 1998 route). If var() is omitted the order is chosen by the
ic() criterion over 1..maxvar().

difference(#) differences every series # times before fitting the
VAR. This is the Section-5 reduction for reproducible (e.g. I(1)) processes: the
partial measures of the differenced-stationary generating process equal those of the
original nonstationary process. Use difference(1) for I(1) series.

Spectral computation

grid(#) controls the frequency resolution. mlag(#) is the order
of the long auxiliary VAR that reproduces the canonical factor of the cleaned pair
(u,v); increase it if the (x,y,z) VAR order is large. band(lo hi) restricts
the overall measures and the Wald tests to a frequency window (e.g. low frequencies
for long-run causality).

Inference

nowald turns off the Section-6 Wald tests of partial non-causality.
By default hpcm tests H0: PM(y{&rarr}x:z)=0, H0: PM(x{&rarr}y:z)=0 and the
joint null, using the band measure(s) as G({&theta}), a numerical Jacobian
D{&theta}G, and the VAR parameter covariance; the statistic is
G'(D{&theta}G V D{&theta}G')^-1 G ~ {&chi}².

breps(#) adds percentile bootstrap CIs for the two directional band
measures by parametric resampling of the fitted VAR.

Interpreting the output

What the numbers mean. Every measure is a log prediction-error variance
ratio in nats (natural-log units), so it is {&ge}0 and unbounded above, and it
is 0 exactly when the effect it measures is absent. A measure M converts to an
easily read effect size:

exp(M) = factor by which the source improves prediction of the
target;

1 - exp(-M) = fraction of the target's one-step-ahead prediction-error variance
attributable to the source's one-way effect.

Rough guide (single-equation targets):

M (nats) variance share 1 - e^-M

0.01 1% (negligible)

0.05 5%

0.10 10% (modest)

0.22 20%

0.49 39% (strong)

0.69 50%

1.00 63% (dominant)

Overall measures table -- decode each row. Columns give the measure integrated
over the full band [0,{&pi}] and over the requested band() (equal when no
band() is set).

PM(y{&rarr}x:z) Strength of the one-way (Granger-type) effect running from
y to x, after removing the one-way effect of z. Large value =
y's own past helps predict x beyond x's past and beyond z.

PM(x{&rarr}y:z) The reverse one-way effect, x to y given z.

PM(x:y:z) Reciprocity / instantaneous feedback -- the directionless
contemporaneous association between x and y that survives the z-cleaning.

PM(x,y:z) Association: the total partial interdependence, and by
Theorem 4.2 exactly the sum of the three rows above.

Reading the pattern. A large PM(y{&rarr}x:z) with a near-zero
PM(x{&rarr}y:z) is clean one-way partial causality y=>x. Two comparable
directional values indicate partial feedback (both directions). A large
PM(x:y:z) with small directional terms means the link is essentially
contemporaneous, not lead-lag. Compare directions by their magnitudes, not by their
p-values.

Full band vs band. The band() column integrates only over the chosen
frequencies; dividing it by the band width and comparing with the full-band value
tells you where in the spectrum the effect concentrates. A low-frequency band
(small {&lambda}) isolates persistent / long-run causality; higher frequencies capture
short-run co-movement.

Wald table. chi2, df and p-value for each non-causality null,
starred */**/*** at 10/5/1%. The statistic tests
whether the band measure is zero. Because every measure is {&ge}0, the null sits
on the boundary of the parameter space, so the {&chi}² approximation is
conservative (true size below nominal, verified by Monte Carlo). Practical rule:
a starred result is trustworthy evidence of causality; a non-rejection means "no
evidence", not "proven absence". The statistic grows with the sample size under a true
effect, so with several thousand observations a genuine effect can produce a very
large chi2 -- read the effect size from the measure, and the evidence
from the p-value.

Bootstrap CIs (breps()). A percentile interval for each directional band
measure. An interval clearly above 0 corroborates the Wald rejection; an interval whose
lower limit is essentially 0 signals a weak or absent effect (and reflects the boundary
at 0).

Frequency plot (plot). The directional panel plots M({&lambda}) for both
directions against frequency {&omega}/2{&pi} in cycles (0 = long run, 0.5 = highest
frequency); the band() limits are marked. Peaks locate the frequencies
(business-cycle, seasonal, ...) at which the partial causality operates. The second
panel overlays association and reciprocity. The area under a curve (over [0,{&pi}],
scaled by 1/{&pi}) equals the corresponding overall measure.

Worked reading (Example 2.2, y=>x by construction):
PM(y{&rarr}x:z)=0.493 means y's one-way effect cuts the prediction-error
variance of x by 1-exp(-0.493), about 40%, a strong effect; the Wald rejects at 1%.
PM(x{&rarr}y:z)=0.000 with p=0.79 confirms no reverse causality. The tiny
PM(x:y:z) shows the link is lead-lag, not contemporaneous.

Remarks and practical guidance

o Sample and order. Fit the smallest VAR order that whitens the
residuals (varlmar); an over-short order leaves structure in z that the
one-way elimination cannot remove. Several hundred observations are advisable for
reliable band measures.

o Vector blocks. x, y, z may each be multivariate; use the
parenthesized form. Determinants of the block spectra are then compared, exactly as
in the scalar case.

o Nonstationary data. For I(1) series use difference(1). Full
Johansen/cointegrated-ARMA inference in levels (Yao and Hosoya 1998) is beyond the
scope of this version and is documented as a limitation, following the paper, which
itself only sketches it.

o Reproducibility. Results depend on var(), grid() and
mlag(); report them. The measures are invariant to the ordering within the
(x,y,z) system and to the choice of innovation square root.

Examples

Basic use, VAR order chosen by AIC:

. hpcm gdp inflation moneysupply

Fixed order, low-frequency band, with the frequency plot:

. hpcm x y z, var(3) band(0 0.5) plot

I(1) series, differenced once, no Wald tests:

. hpcm lgdp lcons linv, difference(1) nowald

Vector x-block, bootstrap CIs:

. hpcm (y1 y2) (c) (r), var(2) breps(499) seed(101)

A full self-test on the paper's examples ships with the package:

. do hpcm_example.do

Stored results

hpcm stores the following in r():

Scalars

r(N) number of observations used

r(p) VAR order fitted

r(m) auxiliary factorization VAR order

r(grid) frequency grid size

r(stable) 1 if the fitted VAR is stable

r(PM_yx) overall PM(y{&rarr}x:z)

r(PM_xy) overall PM(x{&rarr}y:z)

r(PM_recip) overall reciprocity

r(PM_assoc) overall association

r(PM_yx_band), r(PM_xy_band) band-restricted directional measures

r(chi2_yx), r(p_yx) Wald statistic and p-value, H0: PM(y{&rarr}x:z)=0

r(chi2_xy), r(p_xy) Wald statistic and p-value, H0: PM(x{&rarr}y:z)=0

r(chi2_joint), r(p_joint) joint Wald statistic and p-value

Macros

r(cmd) hpcm

r(xvars), r(yvars), r(zvars) the three groups

r(ic) selection criterion used

Matrices

r(overall) 2x4 overall measures (rows: full band, band)

r(curve) frequency-domain measures: {&lambda}, PM(y{&rarr}x), PM(x{&rarr}y), recip, assoc

r(wald) 3x3 Wald table (chi2, df, p)

References

Geweke, J. 1984. Measures of conditional linear dependence and feedback
between time series. Journal of the American Statistical Association 79: 907-915.

Granger, C. W. J. 1969. Investigating causal relations by cross-spectrum
methods. Econometrica 37: 424-438.

Hosoya, Y. 1991. The decomposition and measurement of the interdependency
between second-order stationary processes. Probability Theory and Related
Fields 88: 429-444.

Hosoya, Y. 2001. Elimination of third-series effect and defining partial
measures of causality. Journal of Time Series Analysis 22: 537-554.

Hsiao, C. 1982. Time series modelling and causal ordering of Canadian money,
income and interest rates. In Time Series Analysis: Theory and Practice I,
ed. O. D. Anderson, 671-698. Amsterdam: North-Holland.

Yao, F., and Y. Hosoya. 1998. Inference on one-way effect and evidence in
Japanese macroeconomic data. Journal of Econometrics 98: 225-255.

Author

Dr Merwan Roudane

merwanroudane920@gmail.com

github.com/merwanroudane