Running Predictions¶

Once you have a trained predictor, you can make predictions on new data. This guide covers single predictions, batch predictions, and how to interpret results.

Quick Start¶

from featrixsphere.api import FeatrixSphere

featrix = FeatrixSphere()
fm = featrix.foundational_model("your-session-id")
predictor = fm.list_predictors()[0]  # Get first predictor

# Make a prediction
result = predictor.predict({"age": 35, "income": 50000, "city": "NYC"})
print(f"Prediction: {result.predicted_class}")
print(f"Confidence: {result.confidence:.2%}")

Single Predictions¶

Basic Prediction¶

result = predictor.predict({
    "age": 35,
    "income": 50000,
    "city": "New York",
    "plan": "premium"
})

print(result.predicted_class)   # "churned" or "not_churned"
print(result.confidence)        # 0.87
print(result.probability)       # 0.87 (raw probability)
print(result.threshold)         # 0.5 (decision boundary)

Understanding the Result¶

The PredictionResult object contains:

Attribute	Description
`predicted_class`	The predicted class label (classification) or value (regression)
`probability`	Raw probability of the predicted class
`confidence`	Normalized confidence (0 = at boundary, 1 = maximally certain)
`probabilities`	Full probability distribution: `{"yes": 0.87, "no": 0.13}`
`threshold`	Decision boundary used (for binary classification)
`prediction_uuid`	Unique ID for tracking and feedback
`guardrails`	Per-column warnings about data quality

Confidence vs Probability¶

probability: Raw softmax output for the predicted class
confidence: Normalized distance from the decision boundary
For binary classification: how far the probability is from the threshold
0 means "right at the boundary" (uncertain)
1 means "maximally certain"

# Example: threshold=0.5, probability=0.9
# confidence = (0.9 - 0.5) / (1.0 - 0.5) = 0.8

# Example: threshold=0.5, probability=0.55
# confidence = (0.55 - 0.5) / (1.0 - 0.5) = 0.1 (low confidence)

Checkpoint Selection¶

You can choose which training checkpoint to use:

# Use the checkpoint with best ROC-AUC
result = predictor.predict(record, best_metric_preference="roc_auc")

# Use the checkpoint with best PR-AUC (better for imbalanced data)
result = predictor.predict(record, best_metric_preference="pr_auc")

Feature Importance¶

Get per-prediction feature importance via leave-one-out ablation:

result = predictor.predict(
    {"age": 35, "income": 50000, "city": "NYC"},
    feature_importance=True
)

print(result.feature_importance)
# {"income": 0.15, "age": 0.08, "city": 0.02}
# Higher values = more important for this prediction

This tells you which features most influenced this specific prediction.

Batch Predictions¶

From a List of Dictionaries¶

records = [
    {"age": 25, "income": 40000, "city": "LA"},
    {"age": 35, "income": 60000, "city": "NYC"},
    {"age": 45, "income": 80000, "city": "Chicago"}
]

results = predictor.batch_predict(records, show_progress=True)

for result in results:
    print(f"{result.predicted_class}: {result.confidence:.2%}")

From a DataFrame¶

import pandas as pd

df = pd.read_csv("new_customers.csv")
results = predictor.batch_predict(df, show_progress=True)

# Add predictions to DataFrame
df["prediction"] = [r.predicted_class for r in results]
df["confidence"] = [r.confidence for r in results]

From a CSV File¶

results = predictor.predict_csv_file("test_data.csv", show_progress=True)

Handling Guardrails and Warnings¶

Featrix includes guardrails that warn you about data quality issues:

result = predictor.predict(record)

if result.guardrails:
    print(f"Warnings: {result.guardrails}")
    # Example: {"age": "value_outside_training_range"}

if result.ignored_query_columns:
    print(f"Unknown columns (ignored): {result.ignored_query_columns}")

if result.available_query_columns:
    print(f"Expected columns: {result.available_query_columns}")

Common guardrail warnings:

value_outside_training_range: Numeric value is outside what was seen during training
unknown_category: Categorical value wasn't in training data
missing_required_column: Expected column is missing

Prediction Explanations¶

Get gradient-based attribution for a prediction:

explanation = predictor.explain({"age": 35, "income": 50000})
print(explanation)

For multiclass classification, specify which class:

explanation = predictor.explain(record, class_idx=2)  # Explain class index 2

Prediction Grid (Parameter Exploration)¶

Explore how predictions change across parameter values:

# Create a 2D grid
grid = predictor.predict_grid(degrees_of_freedom=2, grid_shape=(10, 8))
grid.set_axis_labels(["Spend ($)", "Campaign Type"])

# Queue predictions
spend_levels = [100, 250, 500, 750, 1000]
campaigns = ["search", "display", "social", "email"]

for i, spend in enumerate(spend_levels):
    for j, campaign in enumerate(campaigns):
        grid.predict(
            {"spend": spend, "campaign_type": campaign},
            grid_position=(i, j)
        )

# Process all predictions
grid.process_batch(show_progress=True)

# Visualize
grid.plot_heatmap()
optimal = grid.get_optimal_position()
print(f"Best position: {optimal}")

Regression Predictions¶

For regressors, the result contains the predicted numeric value:

regressor = fm.create_regressor(target_column="price")
regressor.wait_for_training()

result = regressor.predict({"bedrooms": 3, "sqft": 1500, "location": "downtown"})
print(f"Predicted price: ${result.predicted_class:,.2f}")

Tracking Predictions (Feedback Loop)¶

Every prediction has a unique ID for tracking:

result = predictor.predict(record)
print(f"Prediction UUID: {result.prediction_uuid}")

# Store this UUID to send feedback later
# (See 05-model-cards-publishing-monitoring.md)

Interpreting Results¶

Understanding Confidence Levels¶

Confidence	Interpretation	Action
95%+	Very high confidence	Trust the prediction
80-95%	Confident	Usually correct, some uncertainty
60-80%	Moderate	Additional review may be warranted
40-60%	Uncertain	Likely needs human review
<40%	Low (multi-class)	Definitely needs review

Featrix calibrates probabilities using Temperature, Platt, or Isotonic scaling, so an 80% confidence prediction really does correspond to roughly 80% accuracy on similar samples.

Training Metrics to Check¶

After training a predictor, verify quality:

metrics = predictor.get_training_metrics()

Metric	Good	Warning	Critical
Accuracy	>80%	60-80%	<60%
AUC-ROC	>0.85	0.7-0.85	<0.7
PR-AUC (imbalanced)	>0.5	0.3-0.5	<0.3
Per-class recall	Balanced	One class low	Any class at 0%

When Predictions Don't Make Sense¶

Check these common issues:

All predictions same class: Class imbalance or embedding collapse
All low confidence: Model didn't converge—needs more epochs
Unknown column warnings: Using columns not in training data
Unexpected values: Check if column types were detected correctly

Performance Tips¶

Batch Predictions are Faster¶

For multiple predictions, use batch_predict() instead of calling predict() in a loop:

# Slow (network round-trip per prediction)
for record in records:
    result = predictor.predict(record)

# Fast (batched)
results = predictor.batch_predict(records)

Disable Progress for Automation¶

In automated pipelines, disable progress output:

results = predictor.batch_predict(records, show_progress=False)

Complete Example¶

from featrixsphere.api import FeatrixSphere
import pandas as pd

# Initialize
featrix = FeatrixSphere()

# Load existing model and predictor
fm = featrix.foundational_model("session-id")
predictor = fm.list_predictors()[0]

# Load new data
test_df = pd.read_csv("new_customers.csv")

# Batch predict
results = predictor.batch_predict(test_df, show_progress=True)

# Process results
for i, result in enumerate(results):
    # Check for warnings
    if result.guardrails:
        print(f"Row {i}: Warnings - {result.guardrails}")

    # Store results
    test_df.loc[i, 'prediction'] = result.predicted_class
    test_df.loc[i, 'confidence'] = result.confidence
    test_df.loc[i, 'prediction_uuid'] = result.prediction_uuid

# Save results
test_df.to_csv("predictions.csv", index=False)

# Summary
print(f"\nPredictions complete: {len(results)} records")
print(f"Class distribution: {test_df['prediction'].value_counts().to_dict()}")

Next Steps¶

Check safety and quality of your predictions
Set up monitoring for production
Send prediction feedback to improve the model