mskayacioglu/nyc-crime-intelligence-weekly-forecast

NYC Crime Intelligence Weekly Forecast

A deterministic weekly aggregate forecasting model for historical NYPD reported-complaint data.

Source code and the complete analytical pipeline are available in the mskayacioglu/nyc-crime-intelligence GitHub repository.

The model estimates the next weekly aggregate complaint count for segments defined by borough, precinct, offense type, and law category. It uses four prior-only lag and rolling features. It does not use complaint identifiers, names, addresses, exact event coordinates, victim/suspect demographics, or person-level attributes.

This is a custom formula model rather than a Transformers checkpoint. It has no neural-network weights or pickle-based estimator.

Model details

Field	Value
Hugging Face repository	nyc-crime-intelligence-weekly-forecast
Technical identity	duckdb_lag_ensemble_regressor
Model version	1
Artifact version	1
Task	Weekly aggregate time-series forecasting
Output	Nonnegative next-week aggregate point estimate
Canonical build implementation	Python standard library plus DuckDB 1.5.4
Standalone inference	Python 3.10+ standard library
Training-data window	2005-12-26 through 2025-12-29
Validation window	2024-01-01 through 2024-12-23
Backtest window	2024-12-30 through 2025-12-22
Fixed forecast week	2026-01-05
Artifact generated	2026-07-05T12:40:05.068774+00:00
Independent training-completion time	Not recorded
License	MIT for original model code, configuration, and documentation

Intended use

The model is intended for:

• reproducible research on aggregate reported-complaint trends;
• demonstrating leakage-safe, time-based validation;
• comparing a deterministic lag ensemble with transparent historical baselines;
• educational analysis of aggregate weekly forecasting; and
• reproducing the fixed forecast used by the NYC Crime Intelligence dashboard.

Predictions should be interpreted only with the documented time horizon, historical error, source-data limitations, and aggregate-only boundary.

Out-of-scope and prohibited uses

This model must not be used for:

• predicting individual behavior;
• person-level or demographic risk scoring;
• identifying a specific future incident location;
• labeling a neighborhood as dangerous, safe, worthy, or blameworthy;
• patrol, enforcement, deployment, intervention, or resource-allocation recommendations;
• automated adverse decisions;
• real-time public-safety monitoring or dispatch;
• causal claims based on complaint counts; or
• treating a point estimate as a guarantee.

The model predicts aggregate reported-complaint volume. It does not predict crime risk, personal risk, harm, or offense seriousness.

Data source

The analytical source is the official NYC Open Data NYPD Complaint Data Historic dataset, identifier qgea-i56i, attributed to the Police Department (NYPD).

The source dataset is not included in this model repository.

The reviewed local snapshot contained:

Population	Count
Source rows evaluated	10,071,507
Rows included in aggregate outputs	10,049,687
Rows excluded by the date-eligibility rule	21,820
Aggregate segments	8,466

Rows with eligible dates but missing borough, precinct, or offense values are retained in aggregate output as literal UNKNOWN categories. Quality flags can overlap and must not be summed or equated with excluded rows.

The source represents reported complaints and recording practices. Reporting delay, revision, under-reporting, classification changes, and policy changes can affect observed counts. NYC Open Data source terms and disclaimers remain applicable. The project MIT License does not relicense the source dataset.

Target and segment definition

The prediction target is the next weekly crime_count for an aggregate segment defined by:

borough × precinct × offense_type × law_category

Weekly buckets begin on Monday. The output is a nonnegative floating-point point estimate, not a probability, confidence score, or prediction interval.

Model inputs

The final formula uses four prior-only aggregate features:

Feature	Meaning
lag_1_week_count	Complaint count one week before the target
lag_52_week_count	Complaint count 52 weeks before the target
trailing_4_week_mean	Arithmetic mean of the four weeks before the target
trailing_8_week_mean	Arithmetic mean of the eight weeks before the target

Borough, precinct, offense type, and law category define the segment but are not direct numeric terms in the formula. Every feature must be computed without including the target week.

Formula and parameters

max(
  0,
  shrinkage * (
    trailing_8_week_mean
    + alpha * (trailing_4_week_mean - trailing_8_week_mean)
    + beta * (lag_1_week_count - trailing_4_week_mean)
    + gamma * (lag_52_week_count - trailing_8_week_mean)
  )
)

Parameter	Value
alpha	0.25
beta	0.10
gamma	0.05
shrinkage	1.00

The trailing-eight-week mean supplies the central estimate. The formula applies small adjustments for recent four-week movement, the latest observed week, and the same week one year earlier. The result is clamped at zero.

Missing-week and fallback policy

The canonical feature pipeline applies these rules:

• Missing segment-weeks are filled with zero only after the segment first appears.
• History before a segment's first appearance is not invented.
• Lag and rolling features end before the target week.
• Missing lag or rolling inputs fall back to established prior segment history and then to zero.
• Random train/test splits are not used.

The lightweight inference.py entry point expects the four final numeric features to have already been prepared. It does not reproduce source cleaning, weekly panel construction, or fallback feature generation.

Usage

Clone or download this model repository, then call the standalone inference function:

from inference import predict_next_week

prediction = predict_next_week(
    lag_1_week_count=12.0,
    lag_52_week_count=10.0,
    trailing_4_week_mean=11.0,
    trailing_8_week_mean=9.0,
)

print(prediction)
# 9.65

The repository also includes a synthetic command-line example:

python inference.py --input examples/example_input.json

The example does not contain an actual complaint record.

Training and selection procedure

Parameters were selected using time-ordered validation RMSE.

Stage	Window
Parameter validation	2024-01-01 through 2024-12-23
Held-out backtest	2024-12-30 through 2025-12-22
Fixed forecast target	Week beginning 2026-01-05

Leakage controls:

• validation precedes the backtest;
• the target week is excluded from every feature;
• rolling windows use prior weeks only;
• no random split is used;
• the final partial source week is excluded from backtest scoring; and
• next-week forecast rows are excluded from historical evaluation.

Evaluation

Overall held-out backtest results:

Metric	Result
Predictions	437,144
Coverage	100.00%
Actual aggregate events	567,306
MAE	0.4894
RMSE	1.3943
Actual-count-weighted MAE	3.6555

Selected baseline comparison:

Model	Predictions	Coverage	MAE	RMSE	Weighted MAE
Trailing eight-week mean	435,942	99.73%	0.4929	1.4128	3.7023
Lag ensemble	437,144	100.00%	0.4894	1.3943	3.6555
Descriptive difference	—	—	-0.0035	-0.0185	-0.0468

The lag ensemble recorded slightly lower errors than the selected baseline. However, this is not a matched-row evaluation: the baseline covers 435,942 rows while the model covers 437,144 rows. The differences are descriptive and must not be presented as a clean like-for-like improvement. Overall metrics are not filter-specific guarantees.

Limitations

• Improvement over the selected baseline is small.
• Evaluation uses one historical time split.
• The model produces point estimates without prediction intervals.
• No calibration analysis or filter-specific error estimate is available.
• The final source week contains only Monday through Wednesday but contributes to lag features for the fixed forecast.
• Features omit holidays, special events, reporting-delay correction, exogenous variables, spatial spillover, and structural-break handling.
• No formal drift monitor, general retraining cadence, or model-age service threshold is defined.
• Zero-filling cannot distinguish a true zero from an upstream reporting absence.
• Sparse or newly appearing segments can have limited historical support.
• Results depend on the reviewed source snapshot and cleaning horizon.
• The fixed 2026-01-05 forecast is retrospective and must not be presented as a current or real-time forecast.

Bias, risks, and ethical considerations

Reported-complaint data is affected by who reports, what is recorded, reporting delay, under-reporting, classification practices, enforcement patterns, policy changes, and later revisions. These processes can differ across geography and category.

A higher predicted aggregate count does not establish greater underlying harm, causal risk, neighborhood danger, individual behavior, offense seriousness, or a need for enforcement action.

The model must be used with source coverage, historical error, missing-data semantics, and the responsible-use boundary visible.

Privacy

The model operates on weekly aggregate counts and aggregate segment keys. This repository contains no complaint identifiers, source event rows, names, exact addresses, exact event coordinates, or person-level attributes.

The following demographic fields were explicitly excluded from modeling:

SUSP_AGE_GROUP
SUSP_RACE
SUSP_SEX
VIC_AGE_GROUP
VIC_RACE
VIC_SEX

Reproducibility

The standalone formula is reproduced by config.json and inference.py. model_manifest.json, baseline_manifest.json, and evaluation.json record the reviewed analytical identity and metrics.

Full cleaning, aggregation, feature construction, validation, backtest, and dashboard-artifact generation are maintained in the nyc-crime-intelligence GitHub repository.

Canonical full-pipeline runtime:

• Python 3.11.15;
• DuckDB 1.5.4;
• no scikit-learn dependency; and
• deterministic formula with a time-based split.

Exact analytical reproduction additionally requires source bytes matching the checksum documented by the GitHub project. A newer NYC Open Data export is a different source snapshot.

Hosted inference

This is a custom deterministic model, not a standard Transformers checkpoint. A Hugging Face hosted inference widget may be unavailable unless a compatible custom serving integration is added. The formula remains reproducible through the included standalone implementation.

License

The original model implementation, configuration, and documentation are provided under the MIT License.

The NYPD Complaint Data Historic dataset is not included and is not relicensed under MIT. It remains subject to NYC Open Data source terms and disclaimers.

Citation

@software{kayacioglu_2026_nyc_weekly_forecast,
  author = {Mert Samet Kayacıoğlu},
  title = {NYC Crime Intelligence Weekly Forecast},
  year = {2026},
  url = {https://github.com/mskayacioglu/nyc-crime-intelligence}
}

Contact

Use the GitHub issue tracker for implementation, reproducibility, or responsible-use questions.