iaa_od.models

class iaa_od.models.Annotation(*, gt_filepath, gt_name, image_name=None, annotation, image_height=None)[source]

Bases: object

Represents a single annotation in a Ground Truth JSON file.

gt_filepath

Path to the Ground Truth JSON file.

Type:: str

gt_name

Name of the Ground Truth dataset.

Type:: str

id

Unique identifier for the annotation.

Type:: str

category_id

Category ID of the annotated object.

Type:: int

image_id

Identifier of the image containing the annotation.

Type:: str

bbox_coords

Bounding box coordinates of the annotation.

Type:: BoundingBox

image_name

Filename of the image (if available).

Type:: Optional[str]

source_file

Source file from which the annotation was derived (if available).

Type:: Optional[str]

unit_id

Identifier of the unit this annotation belongs to (if units were computed).

Type:: Optional[int]

annotation: InitVar

bbox_coords: BoundingBox

category_id: int

gt_filepath: str

gt_name: str

id: str

image_height: InitVar = None

image_id: str

image_name: Optional[str]

source_file: Optional[str]

property unique_id: str

Generate a unique identifier for the annotation by combining the Ground Truth name and the annotation ID.

Returns:: A unique identifier for the annotation.
Return type:: str

unit_id: Optional[int]

class iaa_od.models.AnnotationProtocol(*args, **kwargs)[source]

Bases: Protocol

Protocol representing the abstract structure of an annotation. This protocol defines both Annotation and RandomAnnotation.

gt_name

Name of the Ground Truth dataset this annotation belongs to.

Type:: str

id

Unique identifier for the annotation.

Type:: str

category_id

Category ID of the annotated object.

Type:: int

image_id

Identifier of the image containing the annotation.

Type:: str

bbox_coords

Bounding box coordinates of the annotation.

Type:: BoundingBox

unit_id

Identifier of the unit this annotation belongs to (if units were computed).

Type:: int

bbox_coords: BoundingBox

category_id: int

gt_name: str

id: str

image_id: str

unit_id: int

class iaa_od.models.AnnotationTimestamp(annotation_timestamp_data, result)[source]

Bases: object

Represents a single annotation timestamp in a Ground Truth JSON file.

annotation_id

Unique identifier for the annotation.

Type:: int

timestamp

The timestamp of the annotation in seconds from the UNIX epoch.

Type:: int

timestamp_datetime

The timestamp of the annotation as a datetime object.

Type:: datetime

normalised_timestamp

The normalised timestamp of the annotation as a timedelta object.

Type:: timedelta

image_id

Identifier of the image containing the annotation.

Type:: int

image_filename

Filename of the image corresponding to the image ID.

Type:: str

alpha_for_image

The alpha value for the image corresponding to the image ID.

Type:: float

alpha_for_image: float

annotation_id: int

annotation_timestamp_data: InitVar

image_filename: str

image_id: int

normalised_timestamp: timedelta

result: InitVar

timestamp: int

timestamp_datetime: datetime

class iaa_od.models.BoundingBox(*, image_height=None, input_coords)[source]

Bases: object

A class to represent a bounding box. This class can be initialised with either COCO format bounding box coordinates, or with XYXY format bounding box coordinates. Either way, the coordinates are then stored internally in COCO format.

coords

The bounding box coordinates in COCO format.

Type:: COCOCoordinates

property area: float

Calculate the area of the bounding box.

Returns:: The area of the bounding box.
Return type:: float

coords: COCOCoordinates

image_height: Optional[int]

input_coords: InitVar

class iaa_od.models.BoundingBoxColors(*, line_color, fill_color)[source]

Bases: object

Class for storing bounding box line and fill colors.

line_color

RGBA color for the bounding box line.

Type:: tuple[float, float, float, float]

fill_color

RGBA color for the bounding box fill.

Type:: tuple[float, float, float, float]

fill_color: tuple[float, float, float, float]

line_color: tuple[float, float, float, float]

class iaa_od.models.COCOCoordinates(input_x, input_y, input_w, input_h, *, image_height=None)[source]

Bases: object

A class to represent bounding box coordinates in (x, y, width, height) format.

x

The top-left corner x coordinate.

Type:: float

y

The top-left corner y coordinate.

Type:: float

w

The width of the box.

Type:: float

h

The height of the box.

Type:: float

h: int

image_height: InitVar = None

input_h: InitVar

input_w: InitVar

input_x: InitVar

input_y: InitVar

to_xyxy()[source]: Convert the (x, y, w, h) coordinates to XYXY format (x_min, y_min, x_max, y_max).

w: int

x: int

y: int

class iaa_od.models.CScore(*, c_score, per_unit_c_scores=<factory>)[source]

Bases: object

Represents the C-Score metric for inter-annotator agreement.

c_score

The computed C-Score value.

Type:: float

per_unit_c_scores

A dictionary mapping unit IDs to their respective C-Score values.

Type:: dict[int, float]

brief()[source]

Return type:: str

c_score: float

c_score_for_unit(unit_id)[source]

Retrieves the C-Score for a specific unit.

Parameters:: unit_id (int) – The ID of the unit to retrieve the C-Score for.
Returns:: The C-Score value for the specified unit, or None if not available.
Return type:: float

per_unit_c_scores: dict[int, float]

class iaa_od.models.GTSampleInfo(*, avg_bbox_area, avg_bboxes_per_image)[source]

Bases: object

Class to hold information about ground truths, including average bounding box area and average number of bounding boxes per image.

avg_bbox_area

The average area of bounding boxes in the sample.

Type:: float

avg_bboxes_per_image

The average number of bounding boxes per image in the sample.

Type:: float

avg_bbox_area: float

avg_bboxes_per_image: float

class iaa_od.models.Geometry(*, type, coords)[source]

Bases: object

Represents the geometry of an image in a geographical context.

type

The type of geometry.

Type:: str

coords

The coordinates defining the geometry.

Type:: str

coords: str

type: str

class iaa_od.models.Granularities(*, count, count_benchmark, count_median, size, size_benchmark, size_median, singletons)[source]

Bases: object

Class to hold Count and Size Granularity values for inter-annotator agreement analysis.

count

Dictionary mapping annotator names to their Count Granularity values.

Type:: dict[str, float]

count_benchmark

List of annotator names that are benchmarks for Count Granularity.

Type:: list[str]

count_median

Median Count Granularity value across all annotators (used to identify benchmarks).

Type:: float

size

Dictionary mapping annotator names to their Size Granularity values.

Type:: dict[str, float]

size_benchmark

List of annotator names that are benchmarks for Size Granularity.

Type:: list[str]

size_median

Median Size Granularity value across all annotators (used to identify benchmarks).

Type:: float

true_lone_units

The number of true lone units identified in the analysis.

Type:: int

brief()[source]

Returns a brief string representation of the granularities.

Returns:: A brief string representation of the granularities, including annotator names, benchmark indicators, and granularity values with deltas from benchmarks.
Return type:: str

count: dict[str, float]

count_benchmark: list[str]

count_median: float

singletons: int

size: dict[str, float]

size_benchmark: list[str]

size_median: float

class iaa_od.models.GroundTruth(*, gt_filepath, name)[source]

Bases: object

Represents a Ground Truth JSON file.

gt_filepath

Path to the Ground Truth JSON file.

Type:: str

name

Name of the Ground Truth dataset.

Type:: str

images

Dictionary of Image objects, keyed by image filename.

Type:: dict

annotations

Dictionary of lists of Annotation objects, keyed by image filename.

Type:: dict

categories_dict

Dictionary mapping category IDs to category names.

Type:: dict

image_id_to_filename

Dictionary mapping image IDs to filenames.

Type:: dict

annotations: dict[str, list[Annotation]]

categories_dict: dict[int, str]

find_annotations(gt_data, images)[source]

Finds and returns a dictionary of lists of Annotation objects from the Ground Truth data, keyed by image filename.

Parameters:

gt_data (dict) – The loaded Ground Truth JSON data.
images (dict) – A dictionary of Image objects, keyed by image filename.

Returns:

A dictionary of lists of Annotation objects, keyed by image filename.

Return type:

dict[str, list[Annotation]]

find_images(gt_data)[source]

Finds and returns a dictionary of Image objects from the Ground Truth data.

Parameters:: gt_data (dict) – The loaded Ground Truth JSON data.
Returns:: A dictionary of Image objects, keyed by image filename.
Return type:: dict[str, Image]

gt_filepath: str

image_filename_to_id: dict[str, int]

image_id_to_filename: dict[int, str]

images: dict[str, Image]

name: str

class iaa_od.models.GroundTruthProtocol(*args, **kwargs)[source]

Bases: Protocol

Protocol representing the abstract structure of a Ground Truth. This protocol defines the structure of GroundTruth and RandomGroundTruth.

name

Name of the Ground Truth dataset.

Type:: str

images

A dictionary mapping image filenames to Image objects.

Type:: dict[str, Image]

annotations

A dictionary mapping image filenames to lists of annotations.

Type:: dict[str, list[AnnotationProtocol]]

categories_dict

A dictionary mapping category IDs to category names.

Type:: dict[int, str]

annotations: dict[str, list[AnnotationProtocol]]

categories_dict: dict[int, str]

images: dict[str, Image]

name: str

class iaa_od.models.Image(image, *, input_geometry=None)[source]

Bases: object

Represents an image in a geographical context.

id

The ID of the image.

Type:: int

file_name

The filename of the image.

Type:: str

width

The width of the image.

Type:: int

height

The height of the image.

Type:: int

severity

The severity level associated with the image (if any).

Type:: str | None

site_type

The type of site depicted in the image (if any).

Type:: str | None

valid_fine_grain

Indicates if the image is a valid fine grain (if any).

Type:: bool | None

evidence

Indicates if the image is marked as evidence (if any).

Type:: bool | None

is_candidate_location

Indicates if the image is a candidate location (if any).

Type:: bool | None

geometry

The geographical geometry associated with the image (if any).

Type:: Geometry | None

annotations

List of annotations associated with the image (if any).

Type:: list | None

annotations: Optional[str]

evidence: Optional[bool]

file_name: str

geometry: Optional[Geometry]

height: int

id: int

image: InitVar

input_geometry: InitVar = None

is_candidate_location: Optional[bool]

severity: Optional[str]

site_type: Optional[str]

valid_fine_grain: Optional[bool]

width: int

class iaa_od.models.KAlphaObservationsMatrix(*, observations_matrix, row_totals, column_totals, total, n_filtered_units=None, macro_categories_dict=None)[source]

Bases: object

Data class to hold the observations matrix and related totals for Krippendorff’s Alpha analysis.

observations_matrix

A 2D numpy array representing the observations matrix.

Type:: np.ndarray

row_totals

A 1D numpy array representing the totals for each row.

Type:: np.ndarray

column_totals

A 1D numpy array representing the totals for each column.

Type:: np.ndarray

total

The grand total of all observations.

Type:: int

n_filtered_units

The number of filtered units (only set when filtering units).

Type:: int | None

macro_categories_dict

An optional dictionary mapping macro-category names to lists of category indices.

Type:: dict[str, list[int]] | None

column_totals: ndarray

macro_categories_dict: dict[str, list[int]] | None

n_filtered_units: int | None

observations_matrix: ndarray

row_totals: ndarray

total: int

class iaa_od.models.KAlphaUnit(*, id, img_filename, annotations=<factory>)[source]

Bases: object

Data class representing a “unit” for Krippendorff’s Alpha analysis. The definition of unit comes from Krippendorff’s 2011 paper “Computing Krippendorff’s Alpha-Reliability”.

id

Unique identifier for the unit.

Type:: int

img_filename

Filename of the image associated with the unit.

Type:: str

annotations

List of annotations linked to this unit.

Type:: list[Annotation]

annotations: list[AnnotationProtocol]

property average_area: float

Compute the average area of the bounding boxes in the annotations for this unit.

Returns:: The average area of the bounding boxes, or 0 if there are no annotations.
Return type:: float

id: int

img_filename: str

class iaa_od.models.LScore(*, l_score, agr_i_values=<factory>, mismatched_percentage, exclude_mismatched)[source]

Bases: object

Represents the L-Score metric for inter-annotator agreement.

l_score

The computed L-Score value.

Type:: float

agr_i_values

Dictionary mapping the number of annotators per unit to the respective percentage of total units with that number of annotators.

Type:: dict[int, float]

mismatched_percentage

Percentage of mismatched annotations.

Type:: float

exclude_mismatched

Whether mismatched annotations were excluded from the calculation.

Type:: bool

agr_i_values: dict[int, float]

exclude_mismatched: bool

l_score: float

mismatched_percentage: float

class iaa_od.models.RandomAnnotation(*, gt_name, id, category_id, image_id, coordinates)[source]

Bases: object

A class to represent a random annotation for an image.

gt_name

The name of the ground truth of the annotation.

Type:: str

id

The unique identifier for the annotation.

Type:: str

category_id

The category ID of the annotation.

Type:: int

image_id

The identifier of the image the annotation belongs to.

Type:: str

bbox_coords

The bounding box coordinates of the annotation.

Type:: BoundingBox

unit_id

The identifier of the unit this annotation belongs to (if units were computed).

Type:: Optional[int]

bbox_coords: BoundingBox

category_id: int

coordinates: InitVar

gt_name: str

id: str

image_id: str

unit_id: Optional[int]

class iaa_od.models.RandomGroundTruth(*, deviation=0.5, gts)[source]

Bases: object

A class to represent a randomly generated ground truth dataset, based on statistics sampled from existing ground truths.

name

The name of the randomly generated ground truth dataset.

Type:: str

images

A dictionary mapping image filenames to Image objects.

Type:: dict[str, Image]

annotations

A dictionary mapping image filenames to lists of RandomAnnotation objects.

Type:: dict[str, list[RandomAnnotation]]

categories_dict

A dictionary mapping category IDs to category names.

Type:: dict[int, str]

deviation

The standard deviation to use for the Gaussian distribution when generating random bounding box sizes. Default is 0.5.

Type:: float

annotations: dict[str, list[RandomAnnotation]]

categories_dict: dict[int, str]

deviation: float

gts: InitVar

images: dict[str, Image]

name: str

class iaa_od.models.Result(*, gts, iou_thr, iom, alpha=None, alpha_per_image=<factory>, mean_alpha=None, units=<factory>, observations=None, unfiltered_observations=None, mismatched_bounding_boxes=None)[source]

Bases: object

Represents the result of comparing detected objects against ground truth data.

gts

List of ground truth datasets used in the comparison.

Type:: list[GroundTruthProtocol]

iou_thr

The Intersection over Union (IoU) threshold used for matching.

Type:: float

iom

Whether Intersection over Minimum (IoM) matching was used.

Type:: bool

matching_algorithm

The algorithm used for matching annotations (only for Kappa).

Type:: MatchingAlgorithm | None

kappa

The calculated Kappa statistic (only for Kappa).

Type:: float | None

mean_kappa

The mean Kappa across images (only for Kappa).

Type:: float | None

kappa_per_image

Kappa values per image (only for Kappa).

Type:: dict[str, float]

counts

Overall comparison counts (only for Kappa).

Type:: ComparisonValues | None

counts_per_image

Comparison counts per image (only for Kappa).

Type:: dict[str, ComparisonValues]

alpha

The calculated Alpha statistic (only for Alpha).

Type:: float | None

alpha_per_image

Alpha values per image (only for Alpha).

Type:: dict[str, float]

mean_alpha

The mean Alpha across images (only for Alpha).

Type:: float | None

units

List of KAlphaUnit objects used in Alpha calculation (only for Alpha).

Type:: list[KAlphaUnit]

observations

Observations matrix for Alpha calculation (only for Alpha).

Type:: KAlphaObservationsMatrix | None

unfiltered_observations

Unfiltered observations matrix for Alpha calculation (only for Alpha).

Type:: KAlphaObservationsMatrix | None

mismatched_bounding_boxes

Number of mismatched bounding boxes (only for Alpha).

Type:: int | None

alpha: float | None

alpha_per_image: dict[str, float]

brief()[source]

Generate a brief summary of the Result object, including key fields and metrics.

Returns:: A formatted string summarizing the Result object.
Return type:: str

gts: list[GroundTruthProtocol]

iom: bool

iou_thr: float

mean_alpha: float | None

mismatched_bounding_boxes: int | None

property mismatched_bounding_boxes_percentage: float | None

Calculate the percentage of mismatched bounding boxes out of the total number of bounding boxes in the ground truths.

Returns:: The percentage of mismatched bounding boxes, or None if mismatched_bounding_boxes is not set.
Return type:: Optional[float]

observations: KAlphaObservationsMatrix | None

unfiltered_observations: KAlphaObservationsMatrix | None

units: list[KAlphaUnit]

class iaa_od.models.ScaleComplexity(*, global_sc, per_image_sc, global_alpha, per_image_alpha, global_alpha_collapsed, per_image_alpha_collapsed, partial=False)[source]

Bases: object

Represents the Scale Complexity metric for inter-annotator agreement.

global_sc

The global Scale Complexity value for the entire dataset.

Type:: float

per_image_sc

A dictionary mapping image filenames to their respective Scale Complexity values.

Type:: dict[str, float]

global_alpha

The original agreement value (Krippendorff’s Alpha) for the entire dataset before collapsing.

Type:: float

per_image_alpha

A dictionary mapping image filenames to their respective original agreement values (Krippendorff’s Alpha) before collapsing.

Type:: dict[str, float]

global_alpha_collapsed

The new agreement value (Krippendorff’s Alpha) for the entire dataset after collapsing categories.

Type:: float

per_image_alpha_collapsed

A dictionary mapping image filenames to their respective new agreement values (Krippendorff’s Alpha) after collapsing categories.

Type:: dict[str, float]

agreement_for_image(image_filename)[source]

Retrieves the agreement value (Krippendorff’s Alpha) for a specific image before and after collapsing categories.

Parameters:: image_filename (str) – The filename of the image for which to retrieve the agreement value.
Returns:: The agreement value (Krippendorff’s Alpha) for the specified image before and after collapsing categories.
Return type:: tuple[float, float]

brief()[source]

Return type:: str

global_alpha: float

global_alpha_collapsed: float

global_sc: float

partial: bool

per_image_alpha: dict[str, float]

per_image_alpha_collapsed: dict[str, float]

per_image_sc: dict[str, float]

sc_for_image(image_filename)[source]

Retrieves the Scale Complexity value for a specific image.

Parameters:: image_filename (str) – The filename of the image for which to retrieve the Scale Complexity value.
Returns:: The Scale Complexity value for the specified image.
Return type:: float

class iaa_od.models.XYXYCoordinates(x_min, y_min, x_max, y_max)[source]

Bases: object

A class to represent bounding box coordinates in (x_min, y_min, x_max, y_max) format.

x_min

The minimum x-coordinate (left).

Type:: float

y_min

The minimum y-coordinate (top).

Type:: float

x_max

The maximum x-coordinate (right).

Type:: float

y_max

The maximum y-coordinate (bottom).

Type:: float

to_coco()[source]: Convert the (x_min, y_min, x_max, y_max) coordinates to COCO format (x, y, width, height).

x_max: int

x_min: int

y_max: int

y_min: int

Modules

`annotation`
`annotation_protocol`
`annotation_timestamp`
`bbox_colors`
`bounding_box`
`c_score`
`constants`
`coordinates`
`geometry`
`granularities`
`ground_truth`
`ground_truth_protocol`
`gt_sample_info`
`image`
`k_alpha_observations_matrix`
`k_alpha_unit`
`l_score`
`random_annotation`
`random_ground_truth`
`result`
`scale_complexity`