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

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:

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:

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)
  )
)

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.

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:

Selected baseline comparison:

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.