Prepare your data

What Spavik expects, and what it refuses.

The minimumCopy Anchor Link

The libraries check training row counts and target constraints locally. A file that is too short therefore costs neither a credit nor a round trip.

Accepted formatsCopy Anchor Link

Both SDKs accept CSV files, JSON files, arrays of row objects and raw CSV text. Python also accepts pandas DataFrames. REST accepts a multipart CSV file or a JSON body with a data array. Use the sample dataset to follow this example, after configuring your client.

model = spavik.train("churn.csv", target="churn")
print(model.id)

The separator is detected (comma, semicolon, tab, pipe), quotes are handled, and numbers get their type back along the way: a "12" read from a CSV becomes an integer.

Calling the API directly, you can send JSON in data, or a file as multipart/form-data on POST /v1/models, POST /v1/forecast and POST /v1/models/{id}/predict. The latter avoids serialising a large dataset into a JSON body.

Check before trainingCopy Anchor Link

Use POST /v1/datasets/evaluate, or the SDK's evaluate method. The operation is free and returns structural validation, a trial and an assessment.

report = spavik.evaluate("churn.csv", target="churn")
print(report["assessment"])
print(report.get("validation"))

Read the evaluation guide before choosing the next step. The trial splits rows randomly and does not provide time or group split controls. A high score is not proof of leakage, and an unimproved score is not proof that no signal exists. Avoid repeatedly optimizing fields against the same test score.

Prepare for the prediction momentCopy Anchor Link

Define what one row represents, the observed target, when a prediction will be requested and which fields are available then. Keep matching-only identifiers outside the feature table. Exclude fields filled in after the outcome; construct joins, aggregates and lags using only information known at each historical cutoff. Do not invent missing labels. Preserve a recipe and use it for later predictions. Learn preprocessing only on training partitions, then apply it to held-out data.

Missing valuesCopy Anchor Link

An empty cell becomes null, and the engine copes. A row whose target is empty, however, teaches nothing: if too many of your rows are in that state, the library says so rather than letting training run on almost nothing.

NaN values from a pandas DataFrame are converted to null automatically.

Column namesCopy Anchor Link

The columns you send to predict must carry the same names as at training, minus the target. A mismatch gives COLUMN_MISMATCH or SCHEMA_MISMATCH. A model remembers them: feature_columns on GET /v1/models/{id}, model.features in the libraries.

If you get the target name wrong, the library suggests the closest column:

SpavikDataError: the target column 'churn_90d' is missing from the data.
                 Columns found: plan, seats, tickets_90d, churn. Did you mean 'churn'?

Size limitsCopy Anchor Link

The API refuses beyond certain thresholds, with an explicit code:

These thresholds depend on the plan and the deployment. Rather than guessing them, send and read the code: the message states the limit reached.

For a time seriesCopy Anchor Link

forecast additionally needs:

• a value column (target), numeric;
• a timestamp column (timestamp), optional but recommended;
• a series identifier column (item_id) if your file holds several series, one per store or per product for instance.

Your series must have at least as many points as the requested horizon, and preferably several times more. Three points for a horizon of fourteen produces nothing usable, and the library refuses it before the call.

Cost is the requested horizon per call, regardless of the number of series or the length of the history: five series with a horizon of 7 cost 7 credits.

Sort timestamps within each series and use one observed value per timestamp. Resolve duplicates and gaps according to the data's meaning; missing is not necessarily zero. Do not fabricate history or append blank future rows.

Monthly series must use month-start or month-end timestamps. Other fixed days, including dates clamped to the end of a short month, are unsupported. All series must share the same frequency and calendar anchor, evaluated in UTC. Do not silently move dates to satisfy these requirements.

Before paying, POST /v1/forecast/backtest validates and replays history. Match the intended forecast's horizon, point estimate, quantiles and column roles. For multiple series, use long format and assess history separately for each one. The required references are the naive forecast and a historical-median constant. Read the evaluation guide for MASE weighting and exclusions.