Troubleshooting & support
Resolve common import, order, modeling, and export problems with a short, evidence-based checklist.
Start with the last successful step
Identify whether the issue occurred during download, installation, conversion, input validation, order checking, model fitting, export, or plotting. Record the exact message and settings, rather than repeatedly changing several controls at once. Test the compact count case to distinguish an application setup issue from a larger dataset issue.
Data or map will not load
| Symptom | Check / action |
|---|---|
| Map missing or empty | Extract the ZIP; keep .shp, .shx, .dbf, .prj, and .cpg together with one base name; select all required components |
| Source workbook appears to have too many columns | It may be a wide table. Use Data Conversion before BSTVC panel modeling |
| Only 31 or 5 records appear | These are original wide case rows; after conversion expect 372 or 60 panel records |
| Spatial IDs do not match | Compare names, types, whitespace, leading zeros, and every identifier value across panel and map |
| Numeric column contains text | Review NA encoding, decimal formats, and spreadsheet cells; use Field Conversion where appropriate |
| Field missing from a selector | Check the imported headers exactly, including case and punctuation; confirm Load and Validate Input succeeded |
| Large upload fails | The source manual documents a 1 GB upload limit; confirm file size, available memory, and a complete local download |
Conversion does not match the expected panel
Count periods, selected time columns per variable, and resulting rows. The binary case uses 12 columns for each of seven variables; the count case uses 12 for each of five. Select ranges in chronological order, not alphabetical order. Keep invariant IDs separate from time-specific variables.
For binary conversion, the original outcome prefix is Covid_binary and the chosen output name is covid. For count conversion, this guide uses YEAR; if you chose Year, use that exact name throughout. Do not convert an already long ready-panel CSV again.
Data Check fails or results look geographically wrong
Verify identifier sets, unique location–time pairs, and period coverage. A neighborhood matrix also needs the map’s unit order. If the application rearranged rows, choose Checked Data during fitting. Reusing Raw Data after rearrangement defeats the correction.
The continuous map has 177 units with ISO_A3, the China map has 31 units with gb, and the US map has five units with GEOID. A model that finishes with the wrong identifier or row order may still produce invalid-looking scientific conclusions.
A model is slow, fails, or returns no table
Give a Bayesian local model time to finish; runtime grows with spatial units, time points, predictors, family, and settings. Start with six threads and the default neighborhood. Inspect CPU and memory use if progress is unclear, and preserve any log before restarting.
Reduce complexity in a separately saved test, rather than overwriting the research run. Check invalid response values, ID alignment, predictor types, missingness, and available memory. If k-nearest-neighbor settings produce an INLA error or no output, the source manual suggests reviewing the matrix construction or trying a different scientifically appropriate neighborhood. Keep the changed settings in your record.
Current BSTVC modeling assumes spatiotemporal nonstationarity for all selected predictors. The source manual describes more selective nonstationarity as future work; do not rely on it as a documented current control.
Exported tables or plots are unexpected
- Export all result tables after the model completes; do not feed a raw case workbook to the visualization script.
- Check worksheet names and field headers before plotting. Select the time and spatial names from the actual workbook.
- Check response-scale fields before log/exponential transformations. Binary predictions should be probabilities, not event labels.
- Use ID joins for geographic plots, and stop on unmatched IDs or duplicate map/spatial keys.
- Separate the six-predictor continuous tutorial from the manual’s 12-predictor prediction extension.
- For logistic/Poisson outputs, the overall STVPI explainable percentage is unavailable under the documented residual-component limitation; relative contributions are a different result.
- Historical illustration metrics will not necessarily match a fresh fit under different software, settings, or missingness treatment.
Version boundaries from the Chinese manual
The fuller Chinese manual records a 1 GB upload ceiling, the possible k-nearest-neighbor/INLA issue, nonstationarity for all selected BSTVC predictors, and the missing residual component for binary/count models. This guide includes these as documented boundaries, rather than promises about future versions. A 1 GB upload allowance is not a guarantee that a computer can fit a model of that size.
For a cross-section, use BSVC modeling; the three detailed tutorials here demonstrate BSTVC panels. The Chinese manual introduces BSVC but does not supply a complete separate BSVC case. Likewise, future selective nonstationarity and an overall binary/count explainable percentage are not taught as available controls.
The source installation pictures show an older installer. Use the English desktop release linked in this guide, and report the version you actually run when seeking support.
Get useful help
For methodological questions or model interpretation, contact Chao Song. For installation, data input, application behavior, or runtime errors, contact Xianteng Tang. Use GitHub Issues for reproducible desktop bug reports.
A useful report includes your Windows version, BSTVC version, response family, stage of failure, exact message, dimensions, selected fields, neighborhood, thread count, and a minimal non-sensitive example. Share screenshots with personal paths or private data removed. Do not upload confidential research records just to demonstrate an error.
Desktop website · English software release · BSTVC brand, research organization & development team · BSTVC-R