o 0GfZ@srddlmZddlmZddlZddlZddlZddlm Z ddl m Z ddl m Z ddlmZddlmZmZdd lmZdd lmZdd lmZmZmZmZgd ZdLddZdMddZdNddZ   dOdPd$d%Z dQd&d'Z!d(d)Z"d*d+Z#d,d-Z$d.d/Z%d0d1Z&d2d3Z'd4d5Z(d6d7Z)d8d9Z*d:d;Z+dd?Z-d@dAZ.dBdCZ/dDdEZ0dFdGZ1dRdJdKZ2dS)S) annotations)lrangeN) DataFrame)offsets) to_offset)Literal) _is_recarray_is_using_pandas) ValueWarning)NDArray) array_like bool_likeint_like string_like) lagmat lagmat2ds add_trendduplication_matrixelimination_matrixcommutation_matrixvecvechunvecunvechfreq_to_periodcFskipcCst|d}t|ddd}t|ddd}gd}|dkr|S|d kr,|d d }d }n!|d ks4|dkrG|d d}|dkrD|d d}d }n|dkrMd}t|r[d dlm}t|t|d }|rst|t j rnt |}n |}nt |}t|}t t jd |d t jd|d } t | } |dkr| d d d f} d |vr|rdd} || d } nt jt |d d} | d k} | |d d k@}|} t | r|dkr |jd krd}n#t |jd | }t|t j r|j}ddd|D}d|d}|d|d}t||dkr|d d }| d d d d f} |r$d nd }|rDt j | |j|d!} | |g}t j|d d |d d}|S| |g}t |d d |}|S)"a Add a trend and/or constant to an array. Parameters ---------- x : array_like Original array of data. trend : str {'n', 'c', 't', 'ct', 'ctt'} The trend to add. * 'n' add no trend. * 'c' add constant only. * 't' add trend only. * 'ct' add constant and linear trend. * 'ctt' add constant and linear and quadratic trend. prepend : bool If True, prepends the new data to the columns of X. has_constant : str {'raise', 'add', 'skip'} Controls what happens when trend is 'c' and a constant column already exists in x. 'raise' will raise an error. 'add' will add a column of 1s. 'skip' will return the data without change. 'skip' is the default. Returns ------- array_like The original data with the additional trend columns. If x is a pandas Series or DataFrame, then the trend column names are 'const', 'trend' and 'trend_squared'. See Also -------- statsmodels.tools.tools.add_constant Add a constant column to an array. Notes ----- Returns columns as ['ctt','ct','c'] whenever applicable. There is currently no checking for an existing trend. prependtrend)nrtctcttoptions has_constant)raiseaddr)constrZ trend_squaredrrNrr!r r")recarray_exception)dtypecSs,zt|dkot|dkWSYdS)NgF)npptpany)sr18lib/python3.10/site-packages/statsmodels/tsa/tsatools.py safe_is_const~sz add_trend..safe_is_constaxisr&zx is constant.z, cSg|]}t|qSr1str.0rr1r1r2 zadd_trend..z3x contains one or more constant columns. Column(s) z are constant.z Adding a constant with trend='z' is not allowed.rindexcolumns)r rcopyrstatsmodels.tools.sm_exceptionsr+NotImplementedErrorr isinstancepdZSeriesrr- asanyarraylenvanderarangeZfloat64ZfliplrZapplyr.r/ndimshaper@join ValueErrorr?concat column_stack)xrrr%r@Z trendorderr+ is_pandasnobsZtrendarrr3Z col_constZptp0Z col_is_constZnz_constZbase_errZ const_colsmsgorderr1r1r2r's (                 rr)Tc CsRt|d}t|d}t|ddd}|durd}|dkr"|jd|}|jdkr/|dddf}|dd|f}|d ur@|d}n+|d urJ|jd}n!|dkrW|jd|d}||jdkri|jd}td t|}t||d d }t |}t ||jd} |r||vr| | |n| | |t ||d|f|||d| ffS)a Returns an array with lags included given an array. Parameters ---------- x : array_like An array or NumPy ndarray subclass. Can be either a 1d or 2d array with observations in columns. col : int or None `col` can be an int of the zero-based column index. If it's a 1d array `col` can be None. lags : int The number of lags desired. drop : bool Whether to keep the contemporaneous variable for the data. insert : bool or int If True, inserts the lagged values after `col`. If False, appends the data. If int inserts the lags at int. Returns ------- array : ndarray Array with lags Examples -------- >>> import statsmodels.api as sm >>> data = sm.datasets.macrodata.load() >>> data = data.data[['year','quarter','realgdp','cpi']] >>> data = sm.tsa.add_lag(data, 'realgdp', lags=2) Notes ----- Trims the array both forward and backward, so that the array returned so that the length of the returned array is len(`X`) - lags. The lags are returned in increasing order, ie., t-1,t-2,...,t-lags lagsdroprPr*)rJNrr)TFz number of variables, inserting at the last positionZBoth)trim)rr r rKrJwarningswarnr rrpopr?r-rO) rPcolrUrVinsertZcontempZins_idxZndlagsZ first_colsZ last_colsr1r1r2add_lags> '     (r]cCst|d}t|d}|jdkrt|dkr|j}n |jdkr"td|jd}|dkr4||jdd}ntjt t ||dd}tj | |}|t ||}|jdkrat|dkra|j}|S) a Detrend an array with a trend of given order along axis 0 or 1. Parameters ---------- x : array_like, 1d or 2d Data, if 2d, then each row or column is independently detrended with the same trendorder, but independent trend estimates. order : int The polynomial order of the trend, zero is constant, one is linear trend, two is quadratic trend. axis : int Axis can be either 0, observations by rows, or 1, observations by columns. Returns ------- ndarray The detrended series is the residual of the linear regression of the data on the trend of given order. rTr5r*r)z0x.ndim > 2 is not implemented until it is neededrr4)N)rrJintTrCrKZmeanr-rHrIfloatZlinalgZpinvdot)rPrTr5rRZresidZtrendsZbetar1r1r2detrends"    rcforwardexmaxlagr_rW.Literal['forward', 'backward', 'both', 'none']originalLiteral['ex', 'sep', 'in'] use_pandasboolreturnKNDArray | DataFrame | tuple[NDArray, NDArray] | tuple[DataFrame, DataFrame]csjt|d}t|d}t|dddd}t|ddd }|}t|d d d d }t|d o)|}|d ur0dn|}|}|r@|dvr@tdd}|j\}} |dvrM| }||krUtdt ||| |df} t dt |dD]} || || ||| | || | || df<qk|dvrd} n |dvr|} ntd|dvrt | } n|} |r|}t |trdd|jD}t t||jdkrtdnt|jg}dd|D}t |D]}t|d|fdd|Dqt| d | |j|d} | j| d }|dvr||}|j|dd}n| | | |d f}|d kr*| | | d |f}|d kr3||fS|S)!a, Create 2d array of lags. Parameters ---------- x : array_like Data; if 2d, observation in rows and variables in columns. maxlag : int All lags from zero to maxlag are included. trim : {'forward', 'backward', 'both', 'none', None} The trimming method to use. * 'forward' : trim invalid observations in front. * 'backward' : trim invalid initial observations. * 'both' : trim invalid observations on both sides. * 'none', None : no trimming of observations. original : {'ex','sep','in'} How the original is treated. * 'ex' : drops the original array returning only the lagged values. * 'in' : returns the original array and the lagged values as a single array. * 'sep' : returns a tuple (original array, lagged values). The original array is truncated to have the same number of rows as the returned lagmat. use_pandas : bool If true, returns a DataFrame when the input is a pandas Series or DataFrame. If false, return numpy ndarrays. Returns ------- lagmat : ndarray The array with lagged observations. y : ndarray, optional Only returned if original == 'sep'. Notes ----- When using a pandas DataFrame or Series with use_pandas=True, trim can only be 'forward' or 'both' since it is not possible to consistently extend index values. Examples -------- >>> from statsmodels.tsa.tsatools import lagmat >>> import numpy as np >>> X = np.arange(1,7).reshape(-1,2) >>> lagmat(X, maxlag=2, trim="forward", original='in') array([[ 1., 2., 0., 0., 0., 0.], [ 3., 4., 1., 2., 0., 0.], [ 5., 6., 3., 4., 1., 2.]]) >>> lagmat(X, maxlag=2, trim="backward", original='in') array([[ 5., 6., 3., 4., 1., 2.], [ 0., 0., 5., 6., 3., 4.], [ 0., 0., 0., 0., 5., 6.]]) >>> lagmat(X, maxlag=2, trim="both", original='in') array([[ 5., 6., 3., 4., 1., 2.]]) >>> lagmat(X, maxlag=2, trim="none", original='in') array([[ 1., 2., 0., 0., 0., 0.], [ 3., 4., 1., 2., 0., 0.], [ 5., 6., 3., 4., 1., 2.], [ 0., 0., 5., 6., 3., 4.], [ 0., 0., 0., 0., 5., 6.]]) rfrjrWTrdbackwardbothnoneoptionalr$rh)resepinr#rPr*N)rJr,rq)rqrozEtrim cannot be 'none' or 'backward' when used on Series or DataFramesr)rertzmaxlag should be < nobsr))rqrd)rorpztrim option not validcSr6r1r7r9r1r1r2r;r<zlagmat..zSColumns names must be distinct after conversion to string (if not already strings).cSr6r1r7r:r[r1r1r2r;r<csg|] }t|dqS)z.L.r7rvZlag_strr1r2r;sr>)rtrer4rt)rr rr r lowerrMrKr-zerosranger_rGrDrr@setr8nameextendr?ilocrV)rPrfrWrhrjZorigrQZdropidxrRnvarZlmkZstartobsZstopobsZ x_columnsr@ZlagrUZleadsr1rwr2r)s I           rc Cst|d}t|ddd}t|dddd}|dur|}t||}t|d}|jd kr:|r1t|}n|dddf}n|jd ksD|jd krHtd |j\}} |r|rt |j ddd f||d dd} | j ddd|d fg} t d | D]"} t |j dd| f||d dd} | | j dd||d fqttj | d dS|rt|}t |ddd f||d dddd|d fg} t d | D]} | t |dd| f||d ddd||d fqt| S)a Generate lagmatrix for 2d array, columns arranged by variables. Parameters ---------- x : array_like Data, 2d. Observations in rows and variables in columns. maxlag0 : int The first variable all lags from zero to maxlag are included. maxlagex : {None, int} The max lag for all other variables all lags from zero to maxlag are included. dropex : int Exclude first dropex lags from other variables. For all variables, except the first, lags from dropex to maxlagex are included. trim : str The trimming method to use. * 'forward' : trim invalid observations in front. * 'backward' : trim invalid initial observations. * 'both' : trim invalid observations on both sides. * 'none' : no trimming of observations. use_pandas : bool If true, returns a DataFrame when the input is a pandas Series or DataFrame. If false, return numpy ndarrays. Returns ------- ndarray The array with lagged observations, columns ordered by variable. Notes ----- Inefficient implementation for unequal lags, implemented for convenience. maxlag0maxlagexT)rsrWrnrrNr)rr*z'Only supports 1 and 2-dimensional data.ru)rWrhrjr4)rWrh)rrmaxr rJrErrMrKrr~rzappendrNr-rFrO) rPrrZdropexrWrjrfrQrRrrUZlagslirr1r1r2rsR &     " . rcCs |dS)NF)ravelZmatr1r1r2rs rcCs|jtt|SN)r`take _triu_indicesrGrr1r1r2rsrcCt|\}}|||Sr)r-Z tril_indicesrrowsZcolsr1r1r2 _tril_indices# rcCrr)r- triu_indicesrr1r1r2r(rrcCrr)r- diag_indicesrr1r1r2 _diag_indices-rrcCs8ttt|}||t|ksJ|j||fddS)NrrT)r_r-sqrtrGreshape)vrr1r1r2r2srcCslddtddt|}tt|}t||f}||t|<||j}|t|d<|S)Ng?r=r)r*) r-rrGr_roundryrr`r)rrresultr1r1r2r8s rcCs6t|d}t||dd}tdd|DjS)z Create duplication matrix D_n which satisfies vec(S) = D_n vech(S) for symmetric matrix S Returns ------- D_n : ndarray rr)r*cSsg|]}t|qSr1)rr)r:rPr1r1r2r;Rsz&duplication_matrix..)rr-eyeZarrayr`)rtmpr1r1r2rGs rcCs8t|d}ttt||f}t|||dkS)z Create the elimination matrix L_n which satisfies vech(M) = L_n vec(M) for any matrix M Parameters ---------- Returns ------- rr)rrr-ZtrilZonesr)rZ vech_indicesr1r1r2rUs rcCsPt|d}t|d}t||}t||j||fdd}|j|ddS)z Create the commutation matrix K_{p,q} satisfying vec(A') = K_{p,q} vec(A) Parameters ---------- p : int q : int Returns ------- K : ndarray (pq x pq) pqrrrr4)rr-rrIrrr)rrKindicesr1r1r2res rc Cs~t|d}t|d}tdt|D]'}||}t|D]}||||||d8<q|d||d|<q|S)z Transforms params to induce stationarity/invertability. Parameters ---------- params : array_like The AR coefficients Reference --------- Jones(1980) r*r)N)r-ZtanhrzrG)params newparamsrjakiterr1r1r2_ar_transparamszs  "rcCs|}|}tt|dddD]-}||}t|D]}||||||dd|d||<q|d||d|<qdt|}|S)z Inverse of the Jones reparameterization Parameters ---------- params : array_like The transformed AR coefficients r)rr=r*N)rArzrGr-Zarctanh)rrrrrZ invarcoefsr1r1r2_ar_invtransparamss    rc Csdt| dt| }dt| dt| }tdt|D]'}||}t|D]}||||||d7<q5|d||d|<q+|S)z Transforms params to induce stationarity/invertability. Parameters ---------- params : ndarray The ma coeffecients of an (AR)MA model. Reference --------- Jones(1980) r)N)r-ZexprArzrG)rrrrbrr1r1r2_ma_transparamss$ $ "rcCs|}tt|dddD]-}||}t|D]}||||||dd|d||<q|d||d|<qtd|d| }|S)z Inverse of the Jones reparameterization Parameters ---------- params : ndarray The transformed MA coefficients r)rr=r*N)rArzrGr-log)ZmacoefsrrrrZ invmacoefsr1r1r2_ma_invtransparamss    rcs8tddtfddtddDS)a Returns the successive differences needed to unintegrate the series. Parameters ---------- x : array_like The original series d : int The number of differences of the differenced series. Returns ------- y : array_like The increasing differences from 0 to d-1 of the first d elements of x. See Also -------- unintegrate dNcs g|] }t|dqS)r)r-Zdiff)r:irrPr1r2r;s z&unintegrate_levels..rr=)rr-Zasarrayrz)rPrr1rr2unintegrate_levelss  "rcCs\t|dd}t|dkr |d}tttj||f|S|d}ttj||fS)ay After taking n-differences of a series, return the original series Parameters ---------- x : array_like The n-th differenced series levels : list A list of the first-value in each differenced series, for [first-difference, second-difference, ..., n-th difference] Returns ------- y : array_like The original series de-differenced Examples -------- >>> x = np.array([1, 3, 9., 19, 8.]) >>> levels = unintegrate_levels(x, 2) >>> levels array([ 1., 2.]) >>> unintegrate(np.diff(x, 2), levels) array([ 1., 3., 9., 19., 8.]) Nr)r=r)listrGrZ unintegrater-ZcumsumZr_)rPZlevelsZx0r1r1r2rs   rfreqstr | offsets.DateOffsetcCst|tjs t|}t|tjsJ|j}d}|dvs"||r$dS|dks-|dr/dS|dks8|dr:d S|d ksC|d rEd S|d krKdS|dkrQdS|dkrWdStd|)a$ Convert a pandas frequency to a periodicity Parameters ---------- freq : str or offset Frequency to convert Returns ------- int Periodicity of freq Notes ----- Annual maps to 1, quarterly maps to 4, monthly to 12, weekly to 52. )zA-zAS-zY-zYS-zYE-)AYr)Q)zQ-ZQSZQEM)zM-ZMSZME WzW-4DBHzDfreq {} not understood. Please report if you think this is in error.) rDrZ DateOffsetrZ rule_codeupper startswithrMformat)rZ yearly_freqsr1r1r2rs.  r)rFr)Nr)FT)r)r)rdreF) rfr_rWrgrhrirjrkrlrm)NrrdF)rrrlr_)3Z __future__rZstatsmodels.compat.pythonrrXZnumpyr-ZpandasrErZpandas.tseriesrZpandas.tseries.frequenciesrtypingrZstatsmodels.tools.datarr rBr Zstatsmodels.tools.typingr Zstatsmodels.tools.validationr r rr__all__rr]rcrrrrrrrrrrrrrrrrrrrr1r1r1r2sT          P1  W"