ultralytics 8.0.81 single-line docstring updates (#2061)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

ultralytics/yolo/utils/callbacks/base.py

@@ -2,111 +2,144 @@
 """
 Base callbacks
 """
+
 from collections import defaultdict
 from copy import deepcopy
 
-
 # Trainer callbacks ----------------------------------------------------------------------------------------------------
+
+
 def on_pretrain_routine_start(trainer):
+    """Called before the pretraining routine starts."""
     pass
 
 
 def on_pretrain_routine_end(trainer):
+    """Called after the pretraining routine ends."""
     pass
 
 
 def on_train_start(trainer):
+    """Called when the training starts."""
     pass
 
 
 def on_train_epoch_start(trainer):
+    """Called at the start of each training epoch."""
     pass
 
 
 def on_train_batch_start(trainer):
+    """Called at the start of each training batch."""
     pass
 
 
 def optimizer_step(trainer):
+    """Called when the optimizer takes a step."""
     pass
 
 
 def on_before_zero_grad(trainer):
+    """Called before the gradients are set to zero."""
     pass
 
 
 def on_train_batch_end(trainer):
+    """Called at the end of each training batch."""
     pass
 
 
 def on_train_epoch_end(trainer):
+    """Called at the end of each training epoch."""
     pass
 
 
 def on_fit_epoch_end(trainer):
+    """Called at the end of each fit epoch (train + val)."""
     pass
 
 
 def on_model_save(trainer):
+    """Called when the model is saved."""
     pass
 
 
 def on_train_end(trainer):
+    """Called when the training ends."""
     pass
 
 
 def on_params_update(trainer):
+    """Called when the model parameters are updated."""
     pass
 
 
 def teardown(trainer):
+    """Called during the teardown of the training process."""
     pass
 
 
 # Validator callbacks --------------------------------------------------------------------------------------------------
+
+
 def on_val_start(validator):
+    """Called when the validation starts."""
     pass
 
 
 def on_val_batch_start(validator):
+    """Called at the start of each validation batch."""
     pass
 
 
 def on_val_batch_end(validator):
+    """Called at the end of each validation batch."""
     pass
 
 
 def on_val_end(validator):
+    """Called when the validation ends."""
     pass
 
 
 # Predictor callbacks --------------------------------------------------------------------------------------------------
+
+
 def on_predict_start(predictor):
+    """Called when the prediction starts."""
     pass
 
 
 def on_predict_batch_start(predictor):
+    """Called at the start of each prediction batch."""
     pass
 
 
 def on_predict_batch_end(predictor):
+    """Called at the end of each prediction batch."""
     pass
 
 
 def on_predict_postprocess_end(predictor):
+    """Called after the post-processing of the prediction ends."""
     pass
 
 
 def on_predict_end(predictor):
+    """Called when the prediction ends."""
     pass
 
 
 # Exporter callbacks ---------------------------------------------------------------------------------------------------
+
+
 def on_export_start(exporter):
+    """Called when the model export starts."""
     pass
 
 
 def on_export_end(exporter):
+    """Called when the model export ends."""
     pass
 
 
@@ -146,10 +179,23 @@ default_callbacks = {
 
 
 def get_default_callbacks():
+    """
+    Return a copy of the default_callbacks dictionary with lists as default values.
+
+    Returns:
+        (defaultdict): A defaultdict with keys from default_callbacks and empty lists as default values.
+    """
     return defaultdict(list, deepcopy(default_callbacks))
 
 
 def add_integration_callbacks(instance):
+    """
+    Add integration callbacks from various sources to the instance's callbacks.
+
+    Args:
+        instance (Trainer, Predictor, Validator, Exporter): An object with a 'callbacks' attribute that is a dictionary
+            of callback lists.
+    """
     from .clearml import callbacks as clearml_callbacks
     from .comet import callbacks as comet_callbacks
     from .hub import callbacks as hub_callbacks

ultralytics/yolo/utils/callbacks/clearml.py

@@ -59,6 +59,7 @@ def _log_plot(title, plot_path) -> None:
 
 
 def on_pretrain_routine_start(trainer):
+    """Runs at start of pretraining routine; initializes and connects/ logs task to ClearML."""
     try:
         task = Task.current_task()
         if task:
@@ -83,11 +84,13 @@ def on_pretrain_routine_start(trainer):
 
 
 def on_train_epoch_end(trainer):
+    """Logs debug samples for the first epoch of YOLO training."""
     if trainer.epoch == 1 and Task.current_task():
         _log_debug_samples(sorted(trainer.save_dir.glob('train_batch*.jpg')), 'Mosaic')
 
 
 def on_fit_epoch_end(trainer):
+    """Reports model information to logger at the end of an epoch."""
     task = Task.current_task()
     if task:
         # You should have access to the validation bboxes under jdict
@@ -105,12 +108,14 @@ def on_fit_epoch_end(trainer):
 
 
 def on_val_end(validator):
+    """Logs validation results including labels and predictions."""
     if Task.current_task():
         # Log val_labels and val_pred
         _log_debug_samples(sorted(validator.save_dir.glob('val*.jpg')), 'Validation')
 
 
 def on_train_end(trainer):
+    """Logs final model and its name on training completion."""
     task = Task.current_task()
     if task:
         # Log final results, CM matrix + PR plots

ultralytics/yolo/utils/callbacks/comet.py

@@ -36,6 +36,7 @@ _comet_image_prediction_count = 0
 
 
 def _get_experiment_type(mode, project_name):
+    """Return an experiment based on mode and project name."""
     if mode == 'offline':
         return comet_ml.OfflineExperiment(project_name=project_name)
 
@@ -61,6 +62,7 @@ def _create_experiment(args):
 
 
 def _fetch_trainer_metadata(trainer):
+    """Returns metadata for YOLO training including epoch and asset saving status."""
     curr_epoch = trainer.epoch + 1
 
     train_num_steps_per_epoch = len(trainer.train_loader.dataset) // trainer.batch_size
@@ -97,6 +99,7 @@ def _scale_bounding_box_to_original_image_shape(box, resized_image_shape, origin
 
 
 def _format_ground_truth_annotations_for_detection(img_idx, image_path, batch, class_name_map=None):
+    """Format ground truth annotations for detection."""
     indices = batch['batch_idx'] == img_idx
     bboxes = batch['bboxes'][indices]
     if len(bboxes) == 0:
@@ -120,6 +123,7 @@ def _format_ground_truth_annotations_for_detection(img_idx, image_path, batch, c
 
 
 def _format_prediction_annotations_for_detection(image_path, metadata, class_label_map=None):
+    """Format YOLO predictions for object detection visualization."""
     stem = image_path.stem
     image_id = int(stem) if stem.isnumeric() else stem
 
@@ -142,6 +146,7 @@ def _format_prediction_annotations_for_detection(image_path, metadata, class_lab
 
 
 def _fetch_annotations(img_idx, image_path, batch, prediction_metadata_map, class_label_map):
+    """Join the ground truth and prediction annotations if they exist."""
     ground_truth_annotations = _format_ground_truth_annotations_for_detection(img_idx, image_path, batch,
                                                                               class_label_map)
     prediction_annotations = _format_prediction_annotations_for_detection(image_path, prediction_metadata_map,
@@ -153,6 +158,7 @@ def _fetch_annotations(img_idx, image_path, batch, prediction_metadata_map, clas
 
 
 def _create_prediction_metadata_map(model_predictions):
+    """Create metadata map for model predictions by groupings them based on image ID."""
     pred_metadata_map = {}
     for prediction in model_predictions:
         pred_metadata_map.setdefault(prediction['image_id'], [])
@@ -162,6 +168,7 @@ def _create_prediction_metadata_map(model_predictions):
 
 
 def _log_confusion_matrix(experiment, trainer, curr_step, curr_epoch):
+    """Log the confusion matrix to Weights and Biases experiment."""
     conf_mat = trainer.validator.confusion_matrix.matrix
     names = list(trainer.data['names'].values()) + ['background']
     experiment.log_confusion_matrix(
@@ -174,6 +181,7 @@ def _log_confusion_matrix(experiment, trainer, curr_step, curr_epoch):
 
 
 def _log_images(experiment, image_paths, curr_step, annotations=None):
+    """Logs images to the experiment with optional annotations."""
     if annotations:
         for image_path, annotation in zip(image_paths, annotations):
             experiment.log_image(image_path, name=image_path.stem, step=curr_step, annotations=annotation)
@@ -184,6 +192,7 @@ def _log_images(experiment, image_paths, curr_step, annotations=None):
 
 
 def _log_image_predictions(experiment, validator, curr_step):
+    """Logs predicted boxes for a single image during training."""
     global _comet_image_prediction_count
 
     task = validator.args.task
@@ -225,6 +234,7 @@ def _log_image_predictions(experiment, validator, curr_step):
 
 
 def _log_plots(experiment, trainer):
+    """Logs evaluation plots and label plots for the experiment."""
     plot_filenames = [trainer.save_dir / f'{plots}.png' for plots in EVALUATION_PLOT_NAMES]
     _log_images(experiment, plot_filenames, None)
 
@@ -233,6 +243,7 @@ def _log_plots(experiment, trainer):
 
 
 def _log_model(experiment, trainer):
+    """Log the best-trained model to Comet.ml."""
     experiment.log_model(
         COMET_MODEL_NAME,
         file_or_folder=str(trainer.best),
@@ -242,12 +253,14 @@ def _log_model(experiment, trainer):
 
 
 def on_pretrain_routine_start(trainer):
+    """Creates or resumes a CometML experiment at the start of a YOLO pre-training routine."""
     experiment = comet_ml.get_global_experiment()
     if not experiment:
         _create_experiment(trainer.args)
 
 
 def on_train_epoch_end(trainer):
+    """Log metrics and save batch images at the end of training epochs."""
     experiment = comet_ml.get_global_experiment()
     if not experiment:
         return
@@ -267,6 +280,7 @@ def on_train_epoch_end(trainer):
 
 
 def on_fit_epoch_end(trainer):
+    """Logs model assets at the end of each epoch."""
     experiment = comet_ml.get_global_experiment()
     if not experiment:
         return
@@ -296,6 +310,7 @@ def on_fit_epoch_end(trainer):
 
 
 def on_train_end(trainer):
+    """Perform operations at the end of training."""
     experiment = comet_ml.get_global_experiment()
     if not experiment:
         return

ultralytics/yolo/utils/callbacks/hub.py

@@ -9,6 +9,7 @@ from ultralytics.yolo.utils.torch_utils import get_flops, get_num_params
 
 
 def on_pretrain_routine_end(trainer):
+    """Logs info before starting timer for upload rate limit."""
     session = getattr(trainer, 'hub_session', None)
     if session:
         # Start timer for upload rate limit
@@ -17,6 +18,7 @@ def on_pretrain_routine_end(trainer):
 
 
 def on_fit_epoch_end(trainer):
+    """Uploads training progress metrics at the end of each epoch."""
     session = getattr(trainer, 'hub_session', None)
     if session:
         # Upload metrics after val end
@@ -35,6 +37,7 @@ def on_fit_epoch_end(trainer):
 
 
 def on_model_save(trainer):
+    """Saves checkpoints to Ultralytics HUB with rate limiting."""
     session = getattr(trainer, 'hub_session', None)
     if session:
         # Upload checkpoints with rate limiting
@@ -46,6 +49,7 @@ def on_model_save(trainer):
 
 
 def on_train_end(trainer):
+    """Upload final model and metrics to Ultralytics HUB at the end of training."""
     session = getattr(trainer, 'hub_session', None)
     if session:
         # Upload final model and metrics with exponential standoff
@@ -57,18 +61,22 @@ def on_train_end(trainer):
 
 
 def on_train_start(trainer):
+    """Run traces on train start."""
     traces(trainer.args, traces_sample_rate=1.0)
 
 
 def on_val_start(validator):
+    """Runs traces on validation start."""
     traces(validator.args, traces_sample_rate=1.0)
 
 
 def on_predict_start(predictor):
+    """Run traces on predict start."""
     traces(predictor.args, traces_sample_rate=1.0)
 
 
 def on_export_start(exporter):
+    """Run traces on export start."""
     traces(exporter.args, traces_sample_rate=1.0)
 
 

ultralytics/yolo/utils/callbacks/mlflow.py

@@ -16,6 +16,7 @@ except (ImportError, AssertionError):
 
 
 def on_pretrain_routine_end(trainer):
+    """Logs training parameters to MLflow."""
     global mlflow, run, run_id, experiment_name
 
     if os.environ.get('MLFLOW_TRACKING_URI') is None:
@@ -45,17 +46,20 @@ def on_pretrain_routine_end(trainer):
 
 
 def on_fit_epoch_end(trainer):
+    """Logs training metrics to Mlflow."""
     if mlflow:
         metrics_dict = {f"{re.sub('[()]', '', k)}": float(v) for k, v in trainer.metrics.items()}
         run.log_metrics(metrics=metrics_dict, step=trainer.epoch)
 
 
 def on_model_save(trainer):
+    """Logs model and metrics to mlflow on save."""
     if mlflow:
         run.log_artifact(trainer.last)
 
 
 def on_train_end(trainer):
+    """Called at end of train loop to log model artifact info."""
     if mlflow:
         root_dir = Path(__file__).resolve().parents[3]
         run.log_artifact(trainer.best)

ultralytics/yolo/utils/callbacks/raytune.py

@@ -7,6 +7,7 @@ except (ImportError, AssertionError):
 
 
 def on_fit_epoch_end(trainer):
+    """Sends training metrics to Ray Tune at end of each epoch."""
     if ray.tune.is_session_enabled():
         metrics = trainer.metrics
         metrics['epoch'] = trainer.epoch

ultralytics/yolo/utils/callbacks/tensorboard.py

@@ -12,12 +12,14 @@ writer = None  # TensorBoard SummaryWriter instance
 
 
 def _log_scalars(scalars, step=0):
+    """Logs scalar values to TensorBoard."""
     if writer:
         for k, v in scalars.items():
             writer.add_scalar(k, v, step)
 
 
 def on_pretrain_routine_start(trainer):
+    """Initialize TensorBoard logging with SummaryWriter."""
     if SummaryWriter:
         try:
             global writer
@@ -29,10 +31,12 @@ def on_pretrain_routine_start(trainer):
 
 
 def on_batch_end(trainer):
+    """Logs scalar statistics at the end of a training batch."""
     _log_scalars(trainer.label_loss_items(trainer.tloss, prefix='train'), trainer.epoch + 1)
 
 
 def on_fit_epoch_end(trainer):
+    """Logs epoch metrics at end of training epoch."""
     _log_scalars(trainer.metrics, trainer.epoch + 1)
 
 

ultralytics/yolo/utils/callbacks/wb.py

@@ -11,11 +11,13 @@ except (ImportError, AssertionError):
 
 
 def on_pretrain_routine_start(trainer):
+    """Initiate and start project if module is present."""
     wb.init(project=trainer.args.project or 'YOLOv8', name=trainer.args.name, config=vars(
         trainer.args)) if not wb.run else wb.run
 
 
 def on_fit_epoch_end(trainer):
+    """Logs training metrics and model information at the end of an epoch."""
     wb.run.log(trainer.metrics, step=trainer.epoch + 1)
     if trainer.epoch == 0:
         model_info = {
@@ -26,6 +28,7 @@ def on_fit_epoch_end(trainer):
 
 
 def on_train_epoch_end(trainer):
+    """Log metrics and save images at the end of each training epoch."""
     wb.run.log(trainer.label_loss_items(trainer.tloss, prefix='train'), step=trainer.epoch + 1)
     wb.run.log(trainer.lr, step=trainer.epoch + 1)
     if trainer.epoch == 1:
@@ -35,6 +38,7 @@ def on_train_epoch_end(trainer):
 
 
 def on_train_end(trainer):
+    """Save the best model as an artifact at end of training."""
     art = wb.Artifact(type='model', name=f'run_{wb.run.id}_model')
     if trainer.best.exists():
         art.add_file(trainer.best)