class_docstr: The final result of a ML training run or a Tune trial.
  
  This is the output produced by ``Trainer.fit``.
  ``Tuner.fit`` outputs a :class:`~ray.tune.ResultGrid` that is a collection
  of ``Result`` objects.
  
  This API is the recommended way to access the outputs such as:
  - checkpoints (``Result.checkpoint``)
  - the history of reported metrics (``Result.metrics_dataframe``, ``Result.metrics``)
  - errors encountered during a training run (``Result.error``)
  
  The constructor is a private API -- use ``Result.from_path`` to create a result
  object from a directory.
  
  Attributes:
      metrics: The latest set of reported metrics.
      checkpoint: The latest checkpoint.
      error: The execution error of the Trainable run, if the trial finishes in error.
      path: Path pointing to the result directory on persistent storage. This can
          point to a remote storage location (e.g. S3) or to a local location (path
          on the head node). The path is accessible via the result's associated
          `filesystem`. For instance, for a result stored in S3 at
          ``s3://bucket/location``, ``path`` will have the value ``bucket/location``.
      metrics_dataframe: The full result dataframe of the Trainable.
          The dataframe is indexed by iterations and contains reported
          metrics. Note that the dataframe columns are indexed with the
          *flattened* keys of reported metrics, so the format of this dataframe
          may be slightly different than ``Result.metrics``, which is an unflattened
          dict of the latest set of reported metrics.
      best_checkpoints: A list of tuples of the best checkpoints and
          their associated metrics. The number of
          saved checkpoints is determined by :class:`~ray.train.CheckpointConfig`
          (by default, all checkpoints will be saved).
class_docstr_tok: ["The","final","result","of","a","ML","training","run","or","a","Tune","trial",".","This","is","the","output","produced","by","``","Trainer.fit","``",".","``","Tuner.fit","``","outputs","a",":","class",":","`","~ray.tune.ResultGrid","`","that","is","a","collection","of","``","Result","``","objects",".","This","API","is","the","recommended","way","to","access","the","outputs","such","as",":","-","checkpoints","(","``","Result.checkpoint","``",")","-","the","history","of","reported","metrics","(","``","Result.metrics_dataframe","``",",","``","Result.metrics","``",")","-","errors","encountered","during","a","training","run","(","``","Result.error","``",")","The","constructor","is","a","private","API","--","use","``","Result.from_path","``","to","create","a","result","object","from","a","directory",".","Attributes",":","metrics",":","The","latest","set","of","reported","metrics",".","checkpoint",":","The","latest","checkpoint",".","error",":","The","execution","error","of","the","Trainable","run",",","if","the","trial","finishes","in","error",".","path",":","Path","pointing","to","the","result","directory","on","persistent","storage",".","This","can","point","to","a","remote","storage","location","(","e.g",".","S3",")","or","to","a","local","location","(","path","on","the","head","node",")",".","The","path","is","accessible","via","the","result","'s","associated","`","filesystem","`",".","For","instance",",","for","a","result","stored","in","S3","at","``","s3",":","\/\/bucket\/location","``",",","``","path","``","will","have","the","value","``","bucket\/location","``",".","metrics_dataframe",":","The","full","result","dataframe","of","the","Trainable",".","The","dataframe","is","indexed","by","iterations","and","contains","reported","metrics",".","Note","that","the","dataframe","columns","are","indexed","with","the","*","flattened","*","keys","of","reported","metrics",",","so","the","format","of","this","dataframe","may","be","slightly","different","than","``","Result.metrics","``",",","which","is","an","unflattened","dict","of","the","latest","set","of","reported","metrics",".","best_checkpoints",":","A","list","of","tuples","of","the","best","checkpoints","and","their","associated","metrics",".","The","number","of","saved","checkpoints","is","determined","by",":","class",":","`","~ray.train.CheckpointConfig","`","(","by","default",",","all","checkpoints","will","be","saved",")","."]
docstr: Get the best checkpoint from this trial based on a specific metric.
  
  Any checkpoints without an associated metric value will be filtered out.
  
  Args:
      metric: The key for checkpoints to order on.
      mode: One of ["min", "max"].
  
  Returns:
      :class:`Checkpoint <ray.train.Checkpoint>` object, or None if there is
      no valid checkpoint associated with the metric.
docstr_tok: ["Get","the","best","checkpoint","from","this","trial","based","on","a","specific","metric",".","Any","checkpoints","without","an","associated","metric","value","will","be","filtered","out",".","Args",":","metric",":","The","key","for","checkpoints","to","order","on",".","mode",":","One","of","[","``","min","''",",","``","max","''","]",".","Returns",":",":","class",":","`","Checkpoint","<","ray.train.Checkpoint",">","`","object",",","or","None","if","there","is","no","valid","checkpoint","associated","with","the","metric","."]
code: def get_best_checkpoint(
      self, metric: str, mode: str
  ) -> Optional["Checkpoint"]:
      """Get the best checkpoint from this trial based on a specific metric.
  
      Any checkpoints without an associated metric value will be filtered out.
  
      Args:
          metric: The key for checkpoints to order on.
          mode: One of ["min", "max"].
  
      Returns:
          :class:`Checkpoint <ray.train.Checkpoint>` object, or None if there is
          no valid checkpoint associated with the metric.
      """
      if not self.best_checkpoints:
          raise RuntimeError(
              "No checkpoint exists in the trial directory!"
          )
  
      if mode not in ["max", "min"]:
          raise ValueError(
              f'Unsupported mode: {mode}. Please choose from ["min", "max"]!'
          )
  
      op = max if mode == "max" else min
      valid_checkpoints = [
          ckpt_info
          for ckpt_info in self.best_checkpoints
          if metric in ckpt_info[1]
      ]
  
      if not valid_checkpoints:
          raise RuntimeError(
              f"Invalid metric name {metric}! "
              f"You may choose from the following metrics: {self.metrics.keys()}."
          )
  
      return op(valid_checkpoints, key=lambda x: x[1][metric])[0]
  
file_path: ray/python/ray/air/result.py
imports: import os
  import io
  import json
  import pandas
  import pyarrow
  from dataclasses import dataclass
  from pathlib import Path
  from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple, Union
  import ray
  from ray.air.constants import EXPR_RESULT_FILE, EXPR_PROGRESS_FILE, EXPR_ERROR_PICKLE_FILE
  from ray.util.annotations import PublicAPI
  import logging
label_desc: Use image node_id 7 for calling the Result obj's underlying member method code with example usage: obj.get_best_checkpoint(metric, mode) and returns: op