megadetector 5.0.8__py3-none-any.whl → 5.0.9__py3-none-any.whl

classification/identify_mislabeled_candidates.py

@@ -1,52 +1,45 @@
-########
-#
-# identify_mislabeled_candidates.py
-#
-# Identify images that may have been mislabeled.
-# 
-# A "mislabeled candidate" is defined as an image meeting both criteria:
-#     
-# * according to the ground-truth label, the model made an incorrect prediction
-#
-# * the model's prediction confidence exceeds its confidence for the ground-truth
-#   label by at least <margin>
-# 
-# This script outputs for each dataset a text file containing the filenames of
-# mislabeled candidates, one per line. The text files are saved to:
-#    
-#     <logdir>/mislabeled_candidates_{split}_{dataset}.txt
-# 
-# To this list of files can then be passed to AzCopy to be downloaded:
-#
-"""  
-azcopy cp "http://<url_of_container>?<sas_token>" "/save/files/here" \
-         --list-of-files "/path/to/mislabeled_candidates_{split}_{dataset}.txt"
-"""
-# 
-# To save the filename as <dataset_name>/<blob_name> (instead of just <blob_name>
-# by default), pass the --include-dataset-in-filename flag. Then, the images can
-# be downloaded with:
-#
-"""
-    python data_management/megadb/download_images.py txt \
-        "/path/to/mislabeled_candidates_{split}_{dataset}.txt" \
-        /save/files/here \
-        --threads 50
 """
-#
-# Assumes the following directory layout:
-#     <base_logdir>/
-#         label_index.json
-#         <logdir>/
-#             outputs_{split}.csv.gz
-# 
-########
 
-#%% Example usage
+identify_mislabeled_candidates.py
+
+Identify images that may have been mislabeled.
+
+A "mislabeled candidate" is defined as an image meeting both criteria:
+    
+* according to the ground-truth label, the model made an incorrect prediction
+
+* the model's prediction confidence exceeds its confidence for the ground-truth
+  label by at least <margin>
+
+This script outputs for each dataset a text file containing the filenames of
+mislabeled candidates, one per line. The text files are saved to:
+   
+    <logdir>/mislabeled_candidates_{split}_{dataset}.txt
+
+To this list of files can then be passed to AzCopy to be downloaded:
+
+""  
+azcopy cp "http://<url_of_container>?<sas_token>" "/save/files/here" \
+       --list-of-files "/path/to/mislabeled_candidates_{split}_{dataset}.txt"
+""
+
+To save the filename as <dataset_name>/<blob_name> (instead of just <blob_name>
+by default), pass the --include-dataset-in-filename flag. Then, the images can
+be downloaded with:
+
+""
+  python data_management/megadb/download_images.py txt \
+      "/path/to/mislabeled_candidates_{split}_{dataset}.txt" \
+      /save/files/here \
+      --threads 50
+""
+
+Assumes the following directory layout:
+    <base_logdir>/
+        label_index.json
+        <logdir>/
+            outputs_{split}.csv.gz
 
-"""
-    python identify_mislabeled_candidates.py <base_logdir>/<logdir> \
-        --margin 0.5 --splits val test
 """
 
 #%% Imports
@@ -63,6 +56,14 @@ import pandas as pd
 from tqdm import tqdm
 
 
+#%% Example usage
+
+"""
+    python identify_mislabeled_candidates.py <base_logdir>/<logdir> \
+        --margin 0.5 --splits val test
+"""
+
+
 #%% Main function
 
 def main(logdir: str, splits: Iterable[str], margin: float,

classification/json_to_azcopy_list.py

@@ -1,13 +1,13 @@
-########
-#
-# json_to_azcopy_list.py
-#
-# Given a queried_images.json file output from json_validator.py, generates
-# one text file <dataset>_images.txt for every dataset included.
-# 
-# See: https://github.com/Azure/azure-storage-azcopy/wiki/Listing-specific-files-to-transfer
-#
-########
+"""
+
+json_to_azcopy_list.py
+
+Given a queried_images.json file output from json_validator.py, generates
+one text file <dataset>_images.txt for every dataset included.
+
+See: https://github.com/Azure/azure-storage-azcopy/wiki/Listing-specific-files-to-transfer
+
+"""
 
 #%% Imports and constants 
 

classification/json_validator.py

@@ -1,76 +1,68 @@
-########
-#
-# json_validator.py
-#
-# Validates a classification label specification JSON file and optionally
-# queries MegaDB to find matching image files.
-# 
-# See README.md for an example of a classification label specification JSON file.
-# 
-# The validation step takes the classification label specification JSON file and
-# finds the dataset labels that belong to each classification label. It checks
-# that the following conditions hold:
-#    
-# 1) Each classification label specification matches at least 1 dataset label.
-#
-# 2) If the classification label includes a taxonomical specification, then the
-#    taxa is actually a part of our master taxonomy.
-#    
-# 3) If the 'prioritize' key is found for a given label, then the label must
-#    also have a 'max_count' key.
-#
-# 4) If --allow-multilabel=False, then no dataset label is included in more than
-#    one classification label.
-#
-# If --output-dir <output_dir> is given, then we query MegaDB for images
-# that match the dataset labels identified during the validation step. We filter
-# out images that have unaccepted file extensions and images that don't actually
-# exist in Azure Blob Storage. In total, we output the following files:
-# 
-# <output_dir>/
-#
-# - included_dataset_labels.txt
-#   lists the original dataset classes included for each classification label
-#
-# - image_counts_by_label_presample.json
-#    number of images for each classification label after filtering bad
-#    images, but before sampling
-#
-# - image_counts_by_label_sampled.json
-#   number of images for each classification label in queried_images.json
-#
-# - json_validator_log_{timestamp}.json
-#   log of excluded images / labels
-#
-# - queried_images.json
-#  main output file, ex:
-#     
-#     {
-#         "caltech/cct_images/59f5fe2b-23d2-11e8-a6a3-ec086b02610b.jpg": {
-#             "dataset": "caltech",
-#             "location": 13,
-#             "class": "mountain_lion",  // class from dataset
-#             "label": ["monutain_lion"]  // labels to use in classifier
-#         },
-#         "caltech/cct_images/59f79901-23d2-11e8-a6a3-ec086b02610b.jpg": {
-#             "dataset": "caltech",
-#             "location": 13,
-#             "class": "mountain_lion",  // class from dataset
-#             "bbox": [{"category": "animal",
-#                     "bbox": [0, 0.347, 0.237, 0.257]}],
-#             "label": ["monutain_lion"]  // labels to use in classifier
-#         },
-#         ...
-#     }
-#
-########
+"""
 
-#%% Example usage
+json_validator.py
+
+Validates a classification label specification JSON file and optionally
+queries MegaDB to find matching image files.
+
+See README.md for an example of a classification label specification JSON file.
+
+The validation step takes the classification label specification JSON file and
+finds the dataset labels that belong to each classification label. It checks
+that the following conditions hold:
+   
+1) Each classification label specification matches at least 1 dataset label.
+
+2) If the classification label includes a taxonomical specification, then the
+   taxa is actually a part of our master taxonomy.
+   
+3) If the 'prioritize' key is found for a given label, then the label must
+   also have a 'max_count' key.
+
+4) If --allow-multilabel=False, then no dataset label is included in more than
+   one classification label.
+
+If --output-dir <output_dir> is given, then we query MegaDB for images
+that match the dataset labels identified during the validation step. We filter
+out images that have unaccepted file extensions and images that don't actually
+exist in Azure Blob Storage. In total, we output the following files:
+
+<output_dir>/
+
+- included_dataset_labels.txt
+  lists the original dataset classes included for each classification label
+
+- image_counts_by_label_presample.json
+   number of images for each classification label after filtering bad
+   images, but before sampling
+
+- image_counts_by_label_sampled.json
+  number of images for each classification label in queried_images.json
+
+- json_validator_log_{timestamp}.json
+  log of excluded images / labels
+
+- queried_images.json
+ main output file, ex:
+    
+    {
+        "caltech/cct_images/59f5fe2b-23d2-11e8-a6a3-ec086b02610b.jpg": {
+            "dataset": "caltech",
+            "location": 13,
+            "class": "mountain_lion",  // class from dataset
+            "label": ["monutain_lion"]  // labels to use in classifier
+        },
+        "caltech/cct_images/59f79901-23d2-11e8-a6a3-ec086b02610b.jpg": {
+            "dataset": "caltech",
+            "location": 13,
+            "class": "mountain_lion",  // class from dataset
+            "bbox": [{"category": "animal",
+                    "bbox": [0, 0.347, 0.237, 0.257]}],
+            "label": ["monutain_lion"]  // labels to use in classifier
+        },
+        ...
+    }
 
-"""
-    python json_validator.py label_spec.json \
-        $HOME/camera-traps-private/camera_trap_taxonomy_mapping.csv \
-        --output-dir run --json-indent 2
 """
 
 from __future__ import annotations
@@ -96,6 +88,15 @@ from taxonomy_mapping.taxonomy_graph import (
     build_taxonomy_graph, dag_to_tree, TaxonNode)
 
 
+#%% Example usage
+
+"""
+    python json_validator.py label_spec.json \
+        $HOME/camera-traps-private/camera_trap_taxonomy_mapping.csv \
+        --output-dir run --json-indent 2
+"""
+
+
 #%% Main function
 
 def main(label_spec_json_path: str,

classification/map_classification_categories.py

@@ -1,48 +1,39 @@
-########
-#
-# map_classification_categories.py
-#
-# Maps a classifier's output categories to desired target categories.
-# 
-# In this file, we use the following terminology:
-# * "category": a category output by the classifier
-# * "target": name of a desired group, comprising >= 1 classifier categories
-# 
-# Takes as input 2 label specification JSON files:
-#
-# 1) desired label specification JSON file
-#    this should not have a target named "other"
-#    
-# 2) label specification JSON file of trained classifier
-#
-# The mapping is accomplished as follows:
-#    
-# 1. For each category in the classifier label spec, find all taxon nodes that
-#     belong to that category.
-#
-# 2. Given a target in the desired label spec, find all taxon nodes that belong
-#     to that target. If there is any classifier category whose nodes are a
-#     subset of the target nodes, then map the classifier category to that target.
-#     Any partial intersection between a target's nodes and a category's nodes
-#     is considered an error.
-#
-# 3. If there are any classifier categories that have not yet been assigned a
-#     target, group them into the "other" target.
-# 
-# This script outputs a JSON file that maps each target to a list of classifier
-# categories.
-# 
-# The taxonomy mapping parts of this script are very similar to json_validator.py.
-#
-########
+"""
 
-#%% Example usage
+map_classification_categories.py
+
+Maps a classifier's output categories to desired target categories.
+
+In this file, we use the following terminology:
+* "category": a category output by the classifier
+* "target": name of a desired group, comprising >= 1 classifier categories
+
+Takes as input 2 label specification JSON files:
+
+1) desired label specification JSON file
+   this should not have a target named "other"
+   
+2) label specification JSON file of trained classifier
+
+The mapping is accomplished as follows:
+   
+1. For each category in the classifier label spec, find all taxon nodes that
+    belong to that category.
+
+2. Given a target in the desired label spec, find all taxon nodes that belong
+    to that target. If there is any classifier category whose nodes are a
+    subset of the target nodes, then map the classifier category to that target.
+    Any partial intersection between a target's nodes and a category's nodes
+    is considered an error.
+
+3. If there are any classifier categories that have not yet been assigned a
+    target, group them into the "other" target.
+
+This script outputs a JSON file that maps each target to a list of classifier
+categories.
+
+The taxonomy mapping parts of this script are very similar to json_validator.py.
 
-"""
-    python map_classification_categories.py \
-        desired_label_spec.json \
-        /path/to/classifier/label_spec.json \
-        $HOME/camera-traps-private/camera_trap_taxonomy_mapping.csv
 """
 
 #%% Imports
@@ -65,6 +56,16 @@ from taxonomy_mapping.taxonomy_graph import (
     build_taxonomy_graph, dag_to_tree, TaxonNode)
 
 
+#%% Example usage
+
+"""
+    python map_classification_categories.py \
+        desired_label_spec.json \
+        /path/to/classifier/label_spec.json \
+        $HOME/camera-traps-private/camera_trap_taxonomy_mapping.csv
+"""
+
+
 #%% Main function
 
 def main(desired_label_spec_json_path: str,

classification/merge_classification_detection_output.py

@@ -1,74 +1,59 @@
-########
-#
-# merge_classification_detection_output.py
-#
-# Merges classification results with Batch Detection API outputs.
-#
-# This script takes 2 main files as input:
-#
-# 1) Either a "dataset CSV" (output of create_classification_dataset.py) or a
-#     "classification results CSV" (output of evaluate_model.py). The CSV is
-#     expected to have columns listed below. The 'label' and [label names] columns
-#     are optional, but at least one of them must be provided.
-#     * 'path': str, path to cropped image
-#         * if passing in a detections JSON, must match
-#             <img_file>___cropXX_mdvY.Y.jpg
-#         * if passing in a queried images JSON, must match
-#             <dataset>/<img_file>___cropXX_mdvY.Y.jpg or
-#             <dataset>/<img_file>___cropXX.jpg
-#     * 'label': str, label assigned to this crop
-#     * [label names]: float, confidence in each label
-# 
-# 2) Either a "detections JSON" (output of MegaDetector) or a "queried images
-#     JSON" (output of json_validatory.py).
-# 
-# If the CSV contains [label names] columns (e.g., output of evaluate_model.py),
-# then each crop's "classifications" output will have one value per category.
-# Categories are sorted decreasing by confidence.
-#     "classifications": [
-#         ["3", 0.901],
-#         ["1", 0.071],
-#         ["4", 0.025],
-#         ["2", 0.003],
-#    ]
-#
-# If the CSV only contains the 'label' column (e.g., output of
-# create_classification_dataset.py), then each crop's "classifications" output
-# will have only one value, with a confidence of 1.0. The label's classification
-# category ID is always greater than 1,000,000, to distinguish it from a predicted
-# category ID.
-#     "classifications": [
-#         ["1000004", 1.0]
-#     ]
-# 
-# If the CSV contains both [label names] and 'label' columns, then both the
-# predicted categories and label category will be included. By default, the
-# label-category is included last; if the --label-first flag is given, then the
-# label category is placed first in the results.
-#     "classifications": [
-#         ["1000004", 1.0],  # label put first if --label-first flag is given
-#         ["3", 0.901],  # all other results are sorted by confidence
-#         ["1", 0.071],
-#         ["4", 0.025],
-#         ["2", 0.003]
-#     ]
-#
-########
+"""
 
-#%% Example usage
+merge_classification_detection_output.py
+
+Merges classification results with Batch Detection API outputs.
+
+This script takes 2 main files as input:
+
+1) Either a "dataset CSV" (output of create_classification_dataset.py) or a
+    "classification results CSV" (output of evaluate_model.py). The CSV is
+    expected to have columns listed below. The 'label' and [label names] columns
+    are optional, but at least one of them must be provided.
+    * 'path': str, path to cropped image
+        * if passing in a detections JSON, must match
+            <img_file>___cropXX_mdvY.Y.jpg
+        * if passing in a queried images JSON, must match
+            <dataset>/<img_file>___cropXX_mdvY.Y.jpg or
+            <dataset>/<img_file>___cropXX.jpg
+    * 'label': str, label assigned to this crop
+    * [label names]: float, confidence in each label
+
+2) Either a "detections JSON" (output of MegaDetector) or a "queried images
+    JSON" (output of json_validatory.py).
+
+If the CSV contains [label names] columns (e.g., output of evaluate_model.py),
+then each crop's "classifications" output will have one value per category.
+Categories are sorted decreasing by confidence.
+    "classifications": [
+        ["3", 0.901],
+        ["1", 0.071],
+        ["4", 0.025],
+        ["2", 0.003],
+   ]
+
+If the CSV only contains the 'label' column (e.g., output of
+create_classification_dataset.py), then each crop's "classifications" output
+will have only one value, with a confidence of 1.0. The label's classification
+category ID is always greater than 1,000,000, to distinguish it from a predicted
+category ID.
+    "classifications": [
+        ["1000004", 1.0]
+    ]
+
+If the CSV contains both [label names] and 'label' columns, then both the
+predicted categories and label category will be included. By default, the
+label-category is included last; if the --label-first flag is given, then the
+label category is placed first in the results.
+    "classifications": [
+        ["1000004", 1.0],  # label put first if --label-first flag is given
+        ["3", 0.901],  # all other results are sorted by confidence
+        ["1", 0.071],
+        ["4", 0.025],
+        ["2", 0.003]
+    ]
 
 """
-    python merge_classification_detection_output.py \
-        BASE_LOGDIR/LOGDIR/outputs_test.csv.gz \
-        BASE_LOGDIR/label_index.json \
-        BASE_LOGDIR/queried_images.json \
-        --classifier-name "efficientnet-b3-idfg-moredata" \
-        --detector-output-cache-dir $HOME/classifier-training/mdcache \
-        --detector-version "4.1" \
-        --output-json BASE_LOGDIR/LOGDIR/classifier_results.json \
-        --datasets idfg idfg_swwlf_2019
-"""
-
 
 #%% Imports
 
@@ -88,6 +73,21 @@ from tqdm import tqdm
 from md_utils.ct_utils import truncate_float
 
 
+#%% Example usage
+
+"""
+    python merge_classification_detection_output.py \
+        BASE_LOGDIR/LOGDIR/outputs_test.csv.gz \
+        BASE_LOGDIR/label_index.json \
+        BASE_LOGDIR/queried_images.json \
+        --classifier-name "efficientnet-b3-idfg-moredata" \
+        --detector-output-cache-dir $HOME/classifier-training/mdcache \
+        --detector-version "4.1" \
+        --output-json BASE_LOGDIR/LOGDIR/classifier_results.json \
+        --datasets idfg idfg_swwlf_2019
+"""
+
+
 #%% Support functions
 
 def row_to_classification_list(row: Mapping[str, Any],