{"id":"1ac3f93f-3a7f-40c4-8021-46a24446a834","arxiv_id":"1908.01757","paper_version":2,"verdict":"ACCEPT","confidence":"HIGH","novelty_score":4.0,"correctness_risk":"low","formal_verification":"none","parameter_count":0,"one_line_summary":"StateSpaceModels.jl is an open-source Julia package that estimates, forecasts, and simulates Gaussian state-space time-series models, handling missing observations and user-defined linear models.","lead":"The authors present StateSpaceModels.jl, an open-source Julia package for estimating, forecasting, and simulating time series in a Gaussian state-space framework. It implements Kalman filtering, smoothing, maximum likelihood estimation, and Monte Carlo scenario simulation, including automatic missing-observation handling and user-defined linear models.","discovery_kind":"new_method","skeptic_critique":{"model":"deepseek-v4-flash","headline":"Eq. 13's seasonal recursion has the wrong sign: with the printed plus signs the structural model is explosive and does not satisfy the stated zero-sum seasonality, threatening the two structural-model applications.","rationale":"The reader's verdict accepts the paper with high confidence and identifies the ignorable-missingness assumption as the weakest point. That concern is real but secondary: missing-data handling inherits a standard MAR/ignorability caveat, and the paper's wording does not contradict any printed equation. The more load-bearing issue is internal: Eq. (13), as written, cannot define a zero-sum seasonal component. The structural model is used in two of the three application sections, so the sign error directly affects the evidence for the central claim that the package is a functional tool with the advertised predefined models. The concern is concrete and checkable in the package source: if the code has the standard minus signs, the paper needs a small but necessary correction and the package claim stands; if the code has plus signs, the structural model is broken and the examples should not be taken as validation. Because the correctness of the core seasonal recursion is unresolved from the manuscript text alone, the appropriate disposition is conditional acceptance pending the source check and, if needed, a corrected equation. The reader's missing-data comment should also be incorporated, but it does not displace the sign issue as the single most load-bearing concern.","tokens_in":8188,"tokens_out":10155,"duration_ms":105187,"concrete_test":"Inspect the `structural` model constructor in the StateSpaceModels.jl source code and read the seasonal block of the transition matrix T: if the first row is [-1 -1 ... -1] (standard Durbin-Koopman sign), then Eq. (13) is a typo and the concern is resolved; if it is [+1 +1 ... +1], run the AirPassengers example from Section 6.1 and check whether the smoothed seasonal component stays in a narrow band around zero and whether the forecast is plausible. If the source has the minus signs, the only required change is a one-line correction to Eq. (13).","verdict_should_be":"CONDITIONAL","load_bearing_attack":"The central claim is that StateSpaceModels.jl is a functional state-space toolbox, and the strongest supporting evidence is the worked applications. Two of the three applications (airline passengers and electricity consumption) use the structural model defined in Section 3.1.3. Equation (13) prints the seasonal recursion as γ_{t+1} = Σ_{j=1}^{s-1} γ_{t+1-j} + ω_t, with all plus signs. The surrounding text says this models a seasonal component whose sum over a season is zero except for noise, but the printed equation does not deliver that property. For s=3, let S_t = γ_t + γ_{t-1} + γ_{t-2}; substituting the printed recursion gives S_{t+1} = 2(γ_t + γ_{t-1}) + ω_t, not ω_t. The standard Durbin-Koopman recursion is γ_{t+1} = -γ_t - ... - γ_{t-s+2} + ω_t, which gives S_{t+1} = ω_t. With the printed plus signs, the seasonal block has explosive characteristic roots for any s>2 (for s=3, roots 1.618 and -0.618), so the seasonal component would not stay near zero and would absorb trend rather than represent seasonality. If the package implements the printed equation, the structural model is misspecified and the two application figures are not valid evidence for the central claim. If the package implements the standard minus signs, then Eq. (13) is a typo in a core equation of the paper and must be corrected.","agreement_with_reader":"partial"},"referee_report":{"model":"deepseek-v4-flash","summary":"The manuscript describes StateSpaceModels.jl, an open-source Julia package for Gaussian state-space time-series analysis. It implements the observation and state equations following Durbin and Koopman, a set of pre-defined models (local level, linear trend, basic structural model, and structural model with exogenous variables), Kalman filtering and smoothing including square-root variants, maximum likelihood estimation of noise covariances via L-BFGS with random seeds, automatic missing-data treatment, forecasting, and Monte Carlo simulation. Three applications are presented: log-airline-passenger forecasting and component extraction, electricity-consumption scenario simulation with an exogenous temperature variable, and vehicle tracking with a user-defined linear model. The central claim is that the package fills a gap as a Julia-native state-space toolbox with features such as Monte Carlo simulation and arbitrary user-defined linear models.","tokens_in":8490,"tokens_out":7098,"duration_ms":69984,"significance":"If the technical issues are resolved, this is a useful open-source contribution: it provides a unified Julia interface for model specification, estimation, filtering, smoothing, forecasting, and simulation, and it appears to offer features not found in related commercial software. The paper's strength is that it exposes the full workflow with reproducible example code and links to a public repository. However, the current evidence for correctness is visual and qualitative only; there are no tests, no benchmark comparisons against KFAS, Statsmodels, or STAMP, and no quantitative forecast or estimation metrics. The sign error in the seasonal recursion, Eq. (13), means that the structural-model examples in Sections 6.1 and 6.2 cannot currently be accepted as evidence without clarification or correction.","major_comments":[{"comment":"The seasonal recursion as printed, γ_{t+1} = Σ_{j=1}^{s-1} γ_{t+1-j} + ω_t, is not the standard zero-sum seasonal model and is explosive for s > 2. With s = 3, substituting the recursion into S_{t+1} = γ_{t+1} + γ_t + γ_{t-1} gives S_{t+1} = 2(γ_t + γ_{t-1}) + ω_t rather than ω_t, and the characteristic roots of γ_{t+1} = γ_t + γ_{t-1} are 1.618 and -0.618. The standard Durbin-Koopman recursion has minus signs: γ_{t+1} = -Σ_{j=1}^{s-1} γ_{t+1-j} + ω_t. Since two of the three applications (Sections 6.1 and 6.2) rely on the structural model, the authors must either correct Eq. (13) or, if the package code actually follows the printed plus signs, revise the implementation and rerun the examples. This is a load-bearing correctness issue, not a merely cosmetic typo.","section":"§3.1.3, Eq. (13)"},{"comment":"The observation equation is written as y_t = Z_t α_{t+1} + ε_t, which is inconsistent with Eq. (1), where y_t = Z_t α_t + ε_t, and also with the simulation loop in the same section, which evaluates y[t, :] = Z * α[t, :]. Please correct the indexing (either use α_t or explicitly define an offset state convention and relate it to Eq. (1)) and check that the filter and smoother implementation follows the stated convention.","section":"§6.3, state-space representation after Eq. (24)"},{"comment":"The automatic missing-data treatment is presented as yielding 'minimum variance linear unbiased estimates' by setting Z_t = 0 for periods containing NaN. This claim is only valid under an ignorable-missingness assumption (MCAR, or MAR when estimation is likelihood-based) for the Gaussian state-space model. The paper does not state this assumption, nor does it describe how y_t, the innovations v_t, and the log-likelihood in Eq. (21) are modified for missing periods (e.g., whether y_t is set to zero and the observation contribution is omitted). Please make the assumption explicit and describe the exact implementation, since non-ignorable missingness would bias the completed series and forecasts.","section":"§4.4"}],"minor_comments":[{"comment":"There is a phrasing error: 'Note that the we can rewrite this model' should be 'Note that we can rewrite this model'.","section":"§2"},{"comment":"The application figures are qualitative. Reporting numerical model-selection or forecast-accuracy measures (log-likelihood, AIC, RMSE, or quantile coverage) and, where possible, comparisons with KFAS or Statsmodels on the same data would substantiate the claim that the package is straightforward and functionally complete.","section":"§6.1 and §6.2"},{"comment":"The statement that the mean of the simulated scenarios is identical to the forecast is correct for a linear Gaussian model when parameters are fixed, but the paper should state explicitly that parameter uncertainty is not propagated in the simulation.","section":"§6.2"},{"comment":"The code uses variables m and q without definitions in the displayed snippet; adding dimension definitions would make the example self-contained and reproducible.","section":"§6.3"},{"comment":"Kalman.jl and StateSpace.jl are listed with GitHub links but no version tags or DOIs; for reproducibility, consider citing released versions or specific commits.","section":"References"}],"recommendation":"major_revision","confidential_remarks":"The main decisional risk is the sign of Eq. (13). Because the package is public, the authors can settle this by inspecting the repository code before revision. If the code follows the standard Durbin-Koopman recursion, the paper is close to acceptable after correcting the equation and adding a small numerical benchmark; if the code follows the printed plus signs, the structural-model examples need to be redone. I would also encourage the editor to ask for a version tag or archived DOI for the package repository."},"author_rebuttal":null,"desk_editor":{"model":"deepseek-v4-flash","letter":"Short version: this is a useful, honest software paper that probably deserves publication after one real fix. The package fills a genuine gap (no maintained state-space time-series package in Julia), and the user-defined model constructor plus Monte Carlo simulation are practical features worth having. The math is standard, the code is open-source, and the example figures look plausible.\n\nThe problem is Eq. (13). The seasonal recursion is printed with all plus signs: γ_{t+1} = Σ_{j=1}^{s-1} γ_{t+1-j} + ω_t. That does not give the zero-sum seasonal component the text claims. The standard Durbin-Koopman recursion has alternating signs (γ_{t+1} = -γ_t - ... - γ_{t-s+2} + ω_t). With the printed plus signs, the seasonal block is explosive for s>2. That means either the package implements the standard recursion and Eq. (13) is a typo in a core equation, or the package implements the printed equation and the structural model is misspecified. Both airline and electricity applications use this model, so this is a load-bearing issue, not a cosmetic one. It needs to be resolved before I'd trust the paper.\n\nOther soft spots are milder. There are no benchmarks or test suite, and no quantitative validation against known results. Section 6.3 writes the observation equation as y_t = Z_t α_{t+1} + ε_t, inconsistent with Eq. (1). The missing-data section should state the ignorability assumption behind the Z_t=0 trick. None of these are fatal if the seasonal recursion is just a typo.\n\nWhat the paper does well: it is clearly written, the package is genuinely open-source, and the claim about missing Julia tooling checks out. The examples are enough to show the package works on standard problems, assuming the recursion is fixed. This is not groundbreaking science, but it doesn't have to be.\n\nBottom line: worth sending to a referee who can check the code against Eq. (13). If the package has the correct signs, a revised paper with a corrected equation and at least one benchmark is a legitimate accept. If the package matches the printed equation, the structural model needs to be fixed or removed. Either way, it deserves peer review, not a desk reject.","headline":"Useful Julia state-space package, but the printed seasonal recursion is explosive — needs a fix before the paper can be trusted.","tokens_in":8963,"tokens_out":2687,"would_cite":false,"duration_ms":25780,"reading_group":"maybe","serious_thinker":"yes","would_accept_peer_review":true},"rs_alignment":null,"lean_confirmation":null,"pith_extraction":{"msc":["62-04","62M10","65C05"],"pacs":[],"model":"deepseek-v4-flash","headline":"StateSpaceModels.jl provides a complete state-space workflow in Julia, from user-defined linear models to forecasting and Monte Carlo simulation.","keywords":["state-space models","time series analysis","Kalman filter","forecasting","Monte Carlo simulation","maximum likelihood estimation","missing data","Julia"],"falsifier":"Simulate a state-space series, delete observations whenever the latent state crosses a threshold (a non-ignorable missingness mechanism), fit the package's local level model, and compare the smoothed states and forecasts with the full-data estimates; systematic divergence would falsify the automatic missing-data claim.","tokens_in":8012,"feed_emoji":"📈","tokens_out":5514,"duration_ms":46633,"temperature":0.7,"pith_summary":"StateSpaceModels.jl is an open-source Julia package that implements the full Gaussian state-space workflow for time-series analysis: model specification, Kalman filtering and smoothing, maximum likelihood estimation, forecasting, and Monte Carlo simulation. The paper's central claim is that the package is a straightforward, flexible tool that fills a gap in the Julia ecosystem and that it offers features not present in related commercial software, namely Monte Carlo simulation and the ability to set any user-defined linear model. A sympathetic reader would care because it means a researcher can define arbitrary linear state-space models through matrices $Z_t$, $T$, and $R$, handle missing observations automatically via $Z_t=0$, and obtain forecasts with predictive distributions all within one pure-Julia environment.","feed_headline":"StateSpaceModels.jl: filter, estimate, forecast, simulate","feed_subtitle":"Open-source Julia toolbox adds user-defined linear models, missing-data handling, and Monte Carlo scenarios.","key_machinery":"The central object is the Gaussian state-space model together with its Kalman filter recursion. The model is defined by the observation equation $y_t = Z_t\\alpha_t + \\varepsilon_t$ and the state equation $\\alpha_{t+1} = T\\alpha_t + R\\eta_t$, with covariance matrices $H_t$ and $Q_t$; the package fixes $T$, $R$, $H$, and $Q$ to be time-invariant while allowing $Z_t$ to vary. The Kalman filter produces predictive states $a_{t+1}=E[\\alpha_{t+1}|Y_t]$, filtered states $a_{t|t}=E[\\alpha_t|Y_t]$, innovations $v_t=y_t-Z_ta_t$, and innovation covariances $F_t$, which feed the log-likelihood $\\ell(Y_n)=-\\frac{np}{2}\\log 2\\pi - \\frac12 \\sum_t (\\log |F_t|+v_t^\\top F_t^{-1}v_t)$. The smoother computes $\\hat\\alpha_t=E[\\alpha_t|Y_n]$, and missing observations are treated by setting $Z_t=0$. This machinery carries the package's claims because every advertised operation—estimation, completion of missing data, forecasting, and scenario simulation—is a consequence of these recursions.","core_discovery":"The paper establishes that the package realizes a practical implementation of the Gaussian state-space framework: observations $y_t = Z_t\\alpha_t + \\varepsilon_t$ and states $\\alpha_{t+1}=T\\alpha_t+R\\eta_t$, with $\\varepsilon_t\\sim N(0,H)$ and $\\eta_t\\sim N(0,Q)$. The estimation routine runs the Kalman filter within each maximum-likelihood iteration, using the prediction-error decomposition of the log-likelihood, and then applies a smoother to reconstruct the unobserved states. Missing values marked as NaN are handled by setting $Z_t=0$ in those periods, and forecasts are produced by treating future observations as missing. The paper demonstrates the workflow on airline passenger data, electricity consumption with an exogenous temperature series, and a vehicle-tracking problem defined through a user-supplied model.","pith_inferences":["The paper's automatic missing-data completion implicitly assumes that missingness is ignorable; if missing values depend on the unobserved state, the completed series and forecasts would be biased—a testable condition the paper does not discuss.","The multi-seed L-BFGS strategy is a heuristic for nonconvex likelihood surfaces; the paper does not report diagnostics such as Hessian-based standard errors or convergence checks, so users should treat reported log-likelihoods as point estimates.","The claim of features absent from commercial software is a snapshot at publication time; the durable contribution is the user-defined linear model interface plus simulation, which other tools could copy, so the package's long-term value depends on maintenance and ecosystem integration.","Because the framework assumes time-invariant $T,R,H,Q$, the package does not cover models with time-varying state dynamics or stochastic volatility; extending it in that direction is a natural next step."],"forward_implications":["A Julia user can estimate pre-defined local level, linear trend, and structural models with a single function call, and obtain filtered, smoothed, and predicted states.","Any linear model expressible through constant or time-varying $Z_t$ and constant $T,R$ can be fitted without writing a Kalman filter or optimizer by hand.","Series with missing periods (NaN) can be estimated and completed; forecasts are obtained by treating the future as missing.","Monte Carlo simulation produces $N \\times S$ matrices of future scenarios, suitable as inputs to stochastic optimization.","The square-root Kalman filter and pluggable filter and optimization methods give users control over numerical stability and estimation."],"supporting_citations":[{"why":"Supplies the state-space notation and the Kalman filter, square-root filter, and smoothing recursions that the package implements.","marker":"[4]"},{"why":"Reference implementation in another language whose feature set motivates the package and comparison.","marker":"[5]"},{"why":"The commercial software that the package claims to match and exceed in functionality.","marker":"[7]"},{"why":"Points to the package's own repository, supporting the open-source availability claim.","marker":"[11]"},{"why":"Gives the maximum likelihood principle used for estimating the unknown covariance matrices $H$ and $Q$.","marker":"[12]"},{"why":"Provides the L-BFGS optimization algorithm used by the package's RandomSeedsLBFGS method.","marker":"[13]"},{"why":"Supplies the optimization package through which L-BFGS is run.","marker":"[14]"},{"why":"Earlier application of the package to energy demand simulation, supporting the electricity-consumption example.","marker":"[15]"}],"fun_headline_variants":["Monte Carlo simulation and custom linear models in Julia","State-space modeling in Julia with missing-data support","Kalman filtering made practical in open-source Julia","Forecast with user-defined state-space models in Julia"],"cache_read_input_tokens":3200,"weakest_assumption_plain":"The load-bearing premise is that setting $Z_t=0$ for periods with NaN yields valid estimates, which holds only when missingness does not depend on the unobserved state—an assumption the paper neither states nor tests.","fun_headline_variants_meta":{"raw":{"variants":["Monte Carlo simulation and custom linear models in Julia","State-space modeling in Julia with missing-data support","Kalman filtering made practical in open-source Julia","Forecast with user-defined state-space models in Julia"]},"model":"deepseek-v4-flash","effort":"low","cost_usd":0.000795,"raw_usage":{"total_tokens":3409,"prompt_tokens":763,"completion_tokens":2646,"prompt_tokens_details":{"cached_tokens":384},"prompt_cache_hit_tokens":384,"prompt_cache_miss_tokens":379,"completion_tokens_details":{"reasoning_tokens":2585}},"tokens_in":379,"tokens_out":2646,"duration_ms":19825,"temperature":1.0,"reasoning_tokens":2585,"cache_read_input_tokens":384,"cache_creation_input_tokens":0},"cache_creation_input_tokens":0},"created_at":"2026-08-14T15:03:16.980544+00:00","model_set":{"reader":"deepseek-v4-flash"},"falsifier":"Simulate a state-space series, delete observations whenever the latent state crosses a threshold (a non-ignorable missingness mechanism), fit the package's local level model, and compare the smoothed states and forecasts with the full-data estimates; systematic divergence would falsify the automatic missing-data claim.","supporting_citations":[{"cited_title":"Durbin and S","cited_arxiv_id":null,"evidence_quote":"Supplies the state-space notation and the Kalman filter, square-root filter, and smoothing recursions that the package implements."},{"cited_title":"KFAS: Exponential family state space models in R,","cited_arxiv_id":null,"evidence_quote":"Reference implementation in another language whose feature set motivates the package and comparison."},{"cited_title":"STAMP 6.0: Structural time series analyser, modeller and predictor,","cited_arxiv_id":null,"evidence_quote":"The commercial software that the package claims to match and exceed in functionality."},{"cited_title":"StateSpaceModels.jl,","cited_arxiv_id":null,"evidence_quote":"Points to the package's own repository, supporting the open-source availability claim."},{"cited_title":"Casella and R","cited_arxiv_id":null,"evidence_quote":"Gives the maximum likelihood principle used for estimating the unknown covariance matrices $H$ and $Q$."},{"cited_title":"On the limited memory BFGS method for large scale optimization,","cited_arxiv_id":null,"evidence_quote":"Provides the L-BFGS optimization algorithm used by the package's RandomSeedsLBFGS method."},{"cited_title":"Optim: A mathematical optimization package for Julia,","cited_arxiv_id":null,"evidence_quote":"Supplies the optimization package through which L-BFGS is run."},{"cited_title":"Simulating low and high-frequency energy demand scenarios in a unified framework–Part I: Low-frequency simulation,","cited_arxiv_id":null,"evidence_quote":"Earlier application of the package to energy demand simulation, supporting the electricity-consumption example."}],"review_version":1}