Written and maintained by CASRAI Editorial Board
Published
On this page
The sklearn classification report is produced by sklearn.metrics.classification_report(y_true, y_pred). It summarizes precision, recall, F1-score and support for each class, followed by applicable averages. For a research workflow, keep the class order explicit and export the unrounded dictionary separately from the formatted text: these are different representations of the same evaluation.
What it is used for in research
A classification report connects predicted categories with observed categories. It is useful when an overall accuracy number leaves an unanswered question about individual classes: a classifier may recover one category reliably while missing observations from another. The report puts each category’s precision, recall and support beside its F1-score so those differences are visible.
The function evaluates predictions already made; it does not fit a model. Supply the observed labels as y_true and the corresponding predicted labels as y_pred, preserving observation order. The official classification_report API accepts one-dimensional labels and multilabel indicator arrays. A probability matrix from predict_proba() is a different kind of output from the discrete predictions used here.
This guide uses the bundled wine dataset to demonstrate a complete evaluation and export task. It is an illustrative analysis of a real example dataset, not a performance claim for a new scientific study. The scikit-learn dataset interfaces explain the distinction between bundled datasets, external fetchers and generated data when adapting the workflow.
Install or access
Install the distribution named scikit-learn and import the Python module named sklearn. The project’s installation instructions recommend an isolated environment to reduce conflicts with other installed packages. For Linux or macOS, the documented pip route is:
python -m venv sklearn-env
source sklearn-env/bin/activate
pip install -U scikit-learn
python -m pip show scikit-learn
python -c "import sklearn; sklearn.show_versions()"
On Windows, activate the environment with sklearn-envScriptsactivate instead. Run the installation check in the same environment that runs the analysis. A successful installation in one environment does not describe the packages loaded by another interpreter; retain the version output with the analysis files. The wider scikit-learn research workflow covers fitting, preprocessing and evaluation together.
Step-by-step task
Classification report sklearn syntax and arguments
The documented call is classification_report(y_true, y_pred, *, labels=None, target_names=None, sample_weight=None, digits=2, output_dict=False, zero_division='warn'). Arguments after the asterisk are keyword-only. Keep their roles distinct: labels selects and orders categories, while target_names supplies display names in that same order.
The following task fixes the reporting schema independently of which labels happen to appear in predictions. It also specifies an undefined-value policy. Setting zero_division=0 makes undefined values zero without the default warning; it does not change the predictions or correct a failure to recover a class.
- Load the research example.
load_wine()provides 178 observations, 13 features and three target classes, with full-dataset class counts of 59, 71 and 48. Use itsdata,targetandtarget_namestogether rather than inventing a class-name mapping. - Split paired inputs. Pass the feature array and target array to the same
train_test_split()call. Heretest_size=0.30allocates a test fraction,stratify=wine.targetrequests a stratified split, andrandom_state=17fixes the shuffling for repeated calls. - Fit on the training partition and predict the test partition. The depth-two
DecisionTreeClassifieris an illustrative estimator choice. Its depth and random state are explicit; neither setting is presented as optimal. - Generate the report and a companion count matrix. Pass identical observed and predicted labels into both metrics, with
labels=[0, 1, 2]. This makes the row order of the report and the row/column order of the matrix comparable.
import sklearn
from sklearn.datasets import load_wine
from sklearn.metrics import classification_report, confusion_matrix
from sklearn.model_selection import train_test_split
from sklearn.tree import DecisionTreeClassifier
wine = load_wine()
X_train, X_test, y_train, y_test = train_test_split(
wine.data, wine.target, test_size=0.30,
random_state=17, stratify=wine.target
)
model = DecisionTreeClassifier(max_depth=2, random_state=17)
model.fit(X_train, y_train)
y_pred = model.predict(X_test)
labels = [0, 1, 2]
names = list(wine.target_names)
print('scikit-learn:', sklearn.__version__)
print('training/test rows:', len(y_train), len(y_test))
print(classification_report(
y_test, y_pred, labels=labels, target_names=names,
digits=3, zero_division=0
))
print(confusion_matrix(y_test, y_pred, labels=labels))
The dataset, split and estimator calls follow the official load_wine, train_test_split and DecisionTreeClassifier references. This demonstration produced 124 training rows and 54 test rows with scikit-learn 1.9.1.
Output and how to read it
The example’s three-decimal display is shown below. Read support before comparing scores: it records how many observed examples belong to each class. The summary rows use the same test observations, but aggregate class-level results differently.
precision recall f1-score support
class_0 0.818 1.000 0.900 18
class_1 1.000 0.667 0.800 21
class_2 0.833 1.000 0.909 15
accuracy 0.870 54
macro avg 0.884 0.889 0.870 54
weighted avg 0.893 0.870 0.864 54
The companion confusion matrix has rows for observed classes and columns for predicted classes, following the convention in scikit-learn’s model-evaluation guide:
[[18 0 0]
[ 4 14 3]
[ 0 0 15]]
For class_1, 14 of the 21 observed examples were recovered, giving recall 14/21 = 0.667 after rounding. Every prediction assigned to class_1 was correct, giving precision 14/14 = 1.000. Its F1-score is 2 × precision × recall / (precision + recall) = 0.800. The seven missed class_1 observations went to class_0 and class_2, information the report alone does not identify.
The definitions follow precision_recall_fscore_support: precision counts correct assignments among predicted members, recall counts recovered members among observed members, and support counts observed members. The precision and recall formulas develop these denominators in more detail.
Macro, weighted and micro summaries
Macro averages give every included label equal weight. Weighted averages use the observed support of each included label. In this example the weighted F1 is about 0.864 while macro F1 is about 0.870; they answer different aggregation questions. Neither is obtained by taking the harmonic mean of the displayed macro or weighted precision and recall: scikit-learn averages the per-class F1 values.
A full-label, single-label classification report normally shows accuracy rather than a redundant micro-average row. If a multiclass report includes only a subset of labels, a micro row can appear because its pooled counts no longer describe the complete classification task. A samples-average row belongs to multilabel evaluation, where an observation can carry more than one label. Record which situation applies before comparing reports. For separate scalar calculations, see scikit-learn F1-score averaging options.
Export unrounded results to CSV
Use output_dict=True for downstream analysis. The API explicitly ignores digits in this mode, so dictionary values retain their numerical precision. Round only in the final presentation if that is the chosen reporting convention. Avoid copying three-decimal screen output back into an analysis as though it were the full result.
import csv
report = classification_report(
y_test, y_pred, labels=labels, target_names=names,
output_dict=True, zero_division=0
)
with open('classification-report.csv', 'w', newline='') as handle:
writer = csv.writer(handle)
writer.writerow(['row', 'precision', 'recall', 'f1-score', 'support'])
for name in names + ['macro avg', 'weighted avg']:
row = report[name]
writer.writerow([name, row['precision'], row['recall'],
row['f1-score'], row['support']])
print('accuracy:', report['accuracy'])
This continuation uses the variables from the first example. It exports the three class rows and two average rows. For this full-label task, report['accuracy'] is a scalar, so it is printed separately rather than treated as another nested metric dictionary. The calculated accuracy is 47/54 = 0.8703703703703703. Keeping that distinction explicit avoids an export routine that assumes every dictionary entry has identical structure.
The downloadable data table below compiles reporting controls and their consequences from the report, metric-definition and splitting references. It complements the worked results by identifying the settings that need to remain attached to an exported analysis.
Troubleshooting
UndefinedMetricWarning and absent categories
Inspect the class counts before suppressing warnings. Precision is undefined when there are no predicted positives for a class; recall is undefined when there are no observed positives. F1 is undefined when true positives, false negatives and false positives are all zero. These conditions are different, even though the default policy assigns zero and emits a warning.
The default zero_division='warn' exposes that problem. Explicit alternatives are 0, 1 and np.nan. The NaN option was added in version 1.3; the metric reference says undefined values are then excluded from averages. Consequently, switching from zero to NaN can change an aggregate without changing any predictions. Preserve the policy with the result, and do not describe a missing class as equivalent to a well-measured class with poor performance.
Labels and target names do not match
Make the lengths and order of labels and target_names agree. Names change displayed labels; they do not recode the observations. If a class is absent from one test partition, supply the intended label list explicitly rather than assuming the inferred labels still match a full list of names.
The underlying metric API permits labels absent from the data, assigning them zero support. That can keep a reporting layout stable across partitions, but the undefined-value and averaging rules still apply. Selecting labels=[1] in a multiclass task is a restricted evaluation, not a way to rename the whole report.
Continuous predictions or inconsistent observation counts
For the single-label example, use model.predict(X_test) with y_test. Do not pair test predictions with training targets, reverse observed and predicted arguments, or substitute a probability array into a label-based report. Reversing arguments changes the meanings of precision, recall and support even when array lengths agree.
Split related arrays together and check their first dimension. The split API requires consistent observation counts; its shuffle=False setting also requires stratify=None. If the study needs a different split design, establish that design before interpreting the report. A correctly formatted summary cannot establish that the underlying evaluation design is appropriate.
Weighted support is mistaken for a raw count
The function accepts one sample_weight value per observation. When weights are used, support represents weighted contributions rather than simply the unweighted number of records. Keep the weight definition with the report and apply the same evaluation weights to any companion metric calculation. The worked example uses no sample weights, so its supports sum to the 54 test observations.
Free alternatives
The following functions provide other ways to summarize the same kind of evaluation. They are alternatives to the report interface, with different output structures and coverage. The R function is not a drop-in replacement for scikit-learn’s per-class precision/recall/F1 display.
| Interface | Documented output | Difference to preserve |
|---|---|---|
| scikit-learn precision_recall_fscore_support | Precision, recall, F-score and support arrays with average=None. | Returns metric arrays instead of a formatted report; set labels to preserve the desired order. Source: metric API. |
| scikit-learn confusion_matrix | Counts for observed/predicted class pairs. | Exposes which categories were confused; precision, recall and F1 are separate summaries. Source: evaluation guide. |
| R yardstick metrics | A three-column tibble; factor targets produce accuracy and kappa by default. | Uses truth and estimate columns; its documentation points to metric_set for changing the metric collection. Source: yardstick reference. |
Choose an interface according to the output needed by the analysis: separate arrays, a class-pair matrix, or a tidy summary. Compare results only after aligning labels, included classes and weighting. A change of table format should remain distinguishable from a change of metric definition.
Sources
- Scikit-learn: classification_report API. Checked 2026-11-16.
- Scikit-learn: Metrics and scoring user guide. Checked 2026-11-16.
- Scikit-learn: Installing scikit-learn. Checked 2026-11-16.
- Scikit-learn: load_wine API. Checked 2026-11-16.
- Scikit-learn: train_test_split API. Checked 2026-11-16.
- Scikit-learn: DecisionTreeClassifier API. Checked 2026-11-16.
- Scikit-learn: precision_recall_fscore_support API. Checked 2026-11-16.
- Tidymodels yardstick: General Function to Estimate Performance. Checked 2026-11-16.
Data: Classification report controls and research-record checks
Original crosswalk compiled from the official scikit-learn classification_report, precision_recall_fscore_support and train_test_split references. It pairs documented controls with their effects on report interpretation and the corresponding documented behavior to check; it contains no estimated model performance.
| Control | Documented behavior | Interpretation check | Primary reference |
|---|---|---|---|
| labels and target_names | Labels select report categories; names match their order. | Keep the category subset and display-name order explicit. | https://scikit-learn.org/stable/modules/generated/sklearn.metrics.classification_report.html |
| digits and output_dict | digits formats the text report; dictionary values are not rounded. | Distinguish display precision from exported numerical values. | https://scikit-learn.org/stable/modules/generated/sklearn.metrics.classification_report.html |
| Macro and weighted averages | Macro is an unweighted per-label mean; weighted uses label support. | Different label supports produce different aggregation weights. | https://scikit-learn.org/stable/modules/generated/sklearn.metrics.precision_recall_fscore_support.html |
| zero_division=np.nan | Undefined values are excluded from averaging. | An average can use fewer defined label values than a zero-filled average. | https://scikit-learn.org/stable/modules/generated/sklearn.metrics.precision_recall_fscore_support.html |
| stratify and random_state | stratify supplies class labels for splitting; an integer random_state makes repeated split calls reproducible. | Keep split settings alongside the test-report output. | https://scikit-learn.org/stable/modules/generated/sklearn.model_selection.train_test_split.html |
| Absent labels | Explicit labels can include categories absent from the data, with zero support. | A zero-support row is not evidence from observed examples of that class. | https://scikit-learn.org/stable/modules/generated/sklearn.metrics.precision_recall_fscore_support.html |
Sources
- scikit-learn classification_report API (accessed 2026-11-16)
- scikit-learn precision_recall_fscore_support API (accessed 2026-11-16)
- scikit-learn train_test_split API (accessed 2026-11-16)
Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.







