--- name: ml-best-practices description: | CRITICAL RULE: You MUST use this skill whenever the task involves any machine learning tasks or data analysis. Use this skill if the user's prompt or requirements mention any of the following: * Clustering * Classification * Regression * Time series forecasting * Statistical testing * Model comparison * ML * Data analysis SQL/BigQuery ML HANDOFF: If the user requires a SQL solution, use this skill to dictate the ANALYSIS STEPS (e.g., markdown analysis cells, visualization logic), but defer to `bigquery` for all SQL syntax. license: Apache-2.0 metadata: version: v1 publisher: google --- # ML Best Practices I want to read a story about the data, not just run code. Ensure every code cell is followed by a markdown cell analyzing the results. End the notebook with a summary comprehensively answering the prompt. If there is a good match between the user's request and a corresponding example plan, then adapt the example plan to fully answer the user's request: ## Clustering: Identify distinct groups based on their features. - Understand the schema and field descriptions. - Visualize features referenced in the prompt (e.g., with histograms, scatterplots). - Transform dates into timestamps. - Before applying encoders, check if the dataset already contains pre-encoded features and prefer existing numerical representations. - Prefer to keep data instead of dropping it when possible. - Transform ordinal data with an ordinal encoder. - Transform nominal data with a one hot encoder. - Standardize numerical features. - Perform clustering with a range of values, and collect the silhouette score. - Choose the optimal number of clusters based on the silhouette score. - Use dimensionality reduction (e.g., PCA) to project the data into two dimensions. - Scatterplot the samples in two dimensions with cluster labels as the hue. - Scatterplot the samples in two dimensions with a discrete feature as the hue. - Describe the clusters in text by feature distributions or typical feature values. - Conclusion: comprehensively answer the prompt in a final markdown cell. ## Time Series Forecasting: Develop a predictive model to estimate future values based on historical trends. How might different modeling approaches impact the prediction accuracy? - Understand the schema and field descriptions. - Visualize the target feature over time at a reasonable granularity. - Always perform a chronological split on the data to create training, validation, and test sets. - Are there seasonal trends? - Test for stationarity. - Discuss possible modeling approaches. How might different modeling approaches impact the prediction accuracy? - Train two time series forecasting models to predict the target feature. Use previous seasonality and stationarity information as model hyperparameters. - Predict the target feature for the training and validation sets. - Optionally, hypertune models with the validation set. - Visualize the actual and predicted target feature vs time for each model on the training and validation sets. - Evaluate the validation performance with error metrics. - Select a model. - Retrain the selected model on the test and validation sets. - Predict the test values with the selected model. - Visualize the average target feature and the predicted test values. - Conclusion: comprehensively answer the prompt in a final markdown cell. ## Exploratory Data Analysis / Anomaly Detection: Identify and describe any outliers, unusual patterns, or significant trends observed in the data. Provide visualizations to support your findings. - Understand the schema and field descriptions. - Visualize the target feature distribution in a way that shows outliers. - Identify and describe any outliers in the target feature. - Visualize relationships between the target feature and other features. - Identify and describe unusual patterns or significant trends. - Visualize patterns and trends. - Conclusion: comprehensively answer the prompt in a final markdown cell. ## Classification: Given the data, can we classify by the target feature? - Understand the schema and field descriptions. - Identify rows that don't make sense. How many are there and what do they contain? - Identify rows without a target value. How many are there and what do they contain? - Drop rows that don't match the schema or don't have the target value (if it is reasonable to do so). - Split data into training, validation, and test sets. - Create features to represent when data are missing, if this is meaningful. - Handle missing data. Prefer to keep data instead of dropping it when possible. - Before applying encoders, check if the dataset already contains pre-encoded features and prefer existing numerical representations. - Transform ordinal data with an ordinal encoder. - Transform nominal data with a one hot encoder. - Standardize numerical features. - Train multiple models. - If there is evidence of overfitting, regularize and retrain the model. - If there is evidence of underfitting, consider adding or engineering features. - Evaluate the models. - Create confusion matrices. - Conclusion: comprehensively answer the prompt in a final markdown cell. ## Regression: Predict the continuous valued target feature. - Understand the schema and field descriptions. - Identify rows that don't make sense. How many are there and what do they contain? - Identify rows without a target value. How many are there and what do they contain? - Develop an understanding of the data and determine how to handle missing values. This should make sense in the business context. - Identify any potential sources of group leakage. Aggregate where appropriate to prevent this. - Visualize target feature. - Split data into training, validation, and test sets. - Handle missing data. Prefer to keep data instead of dropping it when possible. - Before applying encoders, check if the dataset already contains pre-encoded features and prefer existing numerical representations. - Transform ordinal data with an ordinal encoder. - Transform nominal data with a one hot encoder. Restrict high cardinality categorical features to a tractable size. - Standardize numerical features. - Train multiple models. - Visualize the actual vs predicted values on training and validation data. - If there is evidence of overfitting, regularize and retrain the model. - If there is evidence of underfitting, consider adding or engineering features. - Evaluate the model error. - Conclusion: comprehensively answer the prompt in a final markdown cell. ## Comparing ML Models: Evaluate and compare multiple models to determine which is most suitable for production based on predictive power, robustness, and viability. - Understand the schema and align metrics with business goals (e.g., cost of false positives vs. false negatives). - Establish baselines: define a naive baseline (majority class/mean) and a simple ML baseline (e.g., Logistic/Linear Regression). - Ensure rigorous validation: use identical, fixed data splits for all models and perform $k$-fold cross-validation. - If data is temporal, use chronological splits for validation. - Select and report metrics beyond accuracy (e.g., F1-Score, PR-AUC, MAE, RMSE) that reflect business impact. - Use bootstrapping to calculate 95% confidence intervals for key metrics to determine statistical significance. - Perform slice-based error analysis: evaluate model performance across key subpopulations and demographics to identify bias or specific failure modes. - Inspect and compare confusion matrices, residual plots, and calibration curves. - Evaluate operational trade-offs: consider inference latency, training time, compute cost, and model size. - Assess interpretability using tools like SHAP or LIME where transparency is required. - Conclusion: Recommend the optimal model for the specific use case, justifying the choice with both performance and production viability. ## No match: - Understand the schema and field descriptions. - Identify rows that don't make sense. How many are there and what do they contain? - Identify rows without a target value. How many are there and what do they contain? - Drop rows that don't match the schema or don't have the target value (if it is reasonable to do so). - Create features to represent when data are missing, if this is meaningful. - Handle missing data. Prefer to keep data instead of dropping it when possible. - Before applying encoders, check if the dataset already contains pre-encoded features and prefer existing numerical representations. - Transform ordinal data with an ordinal encoder. - Transform nominal data with a one hot encoder. - Standardize numerical features. - Conclusion: comprehensively answer the prompt in a final markdown cell. ## Essential ML Practices [!IMPORTANT] ALWAYS follow these ML practices - **Strict Featurization Ordering**: For supervised learning **ALWAYS** split the dataset into training and test data **BEFORE** fitting preprocessing pipelines (e.g. scaling, encoding). Fit the pipelines on the training data and test data independently. - **Handling Missing or NULL Values**: **ALWAYS** check for and handle missing and NULL values. First, analyze their frequency. Then, decide whether to keep them, drop them or impute them with a contextually appropriate value, and explain your reasoning.