Skip to main content
v2026.11,986 entries · CC-BY 4.0

Sklearn Classification Report: Syntax, Output and Export

Generate and interpret a scikit-learn classification report with a tested wine-data example, explicit class labels and an unrounded CSV export.

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.

  1. 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 its data, target and target_names together rather than inventing a class-name mapping.
  2. Split paired inputs. Pass the feature array and target array to the same train_test_split() call. Here test_size=0.30 allocates a test fraction, stratify=wine.target requests a stratified split, and random_state=17 fixes the shuffling for repeated calls.
  3. Fit on the training partition and predict the test partition. The depth-two DecisionTreeClassifier is an illustrative estimator choice. Its depth and random state are explicit; neither setting is presented as optimal.
  4. 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

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.

Classification report controls and research-record checks
ControlDocumented behaviorInterpretation checkPrimary reference
labels and target_namesLabels 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_dictdigits 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 averagesMacro 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.nanUndefined 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_statestratify 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 labelsExplicit 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

Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.

Follow CASRAI

Research-administration guidance, standards updates and independent tool reviews.

Ask CASRAI · free to try

Ask about Sklearn Classification Report: Syntax, Output and Export

2 free questions a day, no account.

An AI assistant for research: funder rules, compliance, methods and publishing. It links the sources behind its answers and labels answers that come from a web search.

Answers draw on CASRAI's guides and dictionary plus the federal and funder documents we index: Federal Register, Grants.gov, Regulations.gov and UKRI.

Works on this site and inside Claude, Cursor and the AI tools you already use.

Everything CASRAI publishes — this page, the dictionary, the guides and the news — stays open to read, with no account and no card.

Referenced across the research world

University of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logoUniversity of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logo
  • University of Cambridge logo
  • Columbia University logo
  • Crossref logo
  • University of Edinburgh logo
  • Harvard University logo
  • University of Oxford logo
  • Princeton University logo
  • Stanford School of Medicine logo
  • University College London logo
  • ORCID logo

View CASRAI adoption →