Segments

How to interact with segments through the SDK

Overview

Within Aquarium's SDK, all types of segments are represented by an object called Issue.

Issues were the predecessor to segments, which is why you'll see the object Issue being referenced. They were expanded on to provide the additional functionality you see in segments. To learn more about segments view this guide.

When it comes to working with segments, the key to working with them will be through the IssueManager. This is an object we have created to make it easy and accessible to access data surrounding your issues. The following guides will showcase some common operations surrounding segments that leverage our client APIs.

Prerequisites

• Installed aquariumlearning library

• Python >= 3.7

• Aquarium API Key - follow this guide to access it

  • Usually best to store this as an environment variable, you can find instructions on how to do this in the Working With The SDK section

Accessing Segment Information

Getting a List of All Segments

#!/usr/bin/env python3
import os
import aquariumlearning as al

AQUARIUM_API_KEY = os.environ['AQUARIUM_API_KEY']

al_client = al.Client()
al_client.set_credentials(api_key=AQUARIUM_API_KEY) 

issue_manager = al_client.get_issue_manager('Rareplanes_Wingtype_Project')

# you are returned a list of issue objects
issues = issue_manager.list_issues()

Getting a Segment ID

When working with Aquarium's client, you can usually pass in references to a Project or Dataset by their name. For example:

import os
import aquariumlearning as al

AQUARIUM_API_KEY = os.environ['AQUARIUM_API_KEY']

al_client = al.Client()
al_client.set_credentials(api_key=AQUARIUM_API_KEY) 

my_project = al_client.get_project('my_project_name')

However when working with Segments, you will often need to refer to it by its uuid. Here is the easiest way to pull the ID of a specific segment:

import os
import aquariumlearning as al
import json

AQUARIUM_API_KEY = os.environ['AQUARIUM_API_KEY']

al_client = al.Client()
al_client.set_credentials(api_key=AQUARIUM_API_KEY) 

# grab your issue_manager for the project
issue_manager = al_client.get_issue_manager('PROJECT_NAME')

# gets your issues for the project
issues = issue_manager.list_issues()

# searches your issues for the one with the same name
issue = next((x for x in issues if x.name == 'YOUR_ISSUE_NAME'), None)

# grabs the issue id
issue_id = issue.issue_id

Getting a Specific Segment

If you have the issue ID you can also use .get_issue() to retrieve the Issue object

#!/usr/bin/env python3
import os
import aquariumlearning as al

AQUARIUM_API_KEY = os.environ['AQUARIUM_API_KEY']

al_client = al.Client()
al_client.set_credentials(api_key=AQUARIUM_API_KEY) 

issue_manager = al_client.get_issue_manager('YOUR_PROJECT_NAME')

specific_issue = issue_manager.get_issue('ISSUE_ID')

Creating Segments

When creating a segment, the main effort involved is creating your IssueElement objects. An IssueElement is a frame or a crop that belongs to a Segment! Here we give you the skeleton of the steps you'll need to take, you can look at the next section, Copy Existing Segment to New Segment to view an example, however in that case it is a copy function.

import os
import aquariumlearning as al

AQUARIUM_API_KEY = os.environ['AQUARIUM_API_KEY']

al_client = al.Client()
al_client.set_credentials(api_key=AQUARIUM_API_KEY) 

# set up your issue manager
issue_manager = al_client.get_issue_manager('YOUR_PROJECT_NAME')
issues = issue_manager.list_issues()

# to create an segment you have to set if it is a frame or crop level segment
element_type = "crop"

# grab dataset info
dataset_name = ""
inference_set_name = ""
new_issue_name = ""

# create issue element list
elements_to_add = [
    al.IssueElement(
        element_id = gtLabelId,
        frame_id = element.frame_id,
        element_type = element_type,
        dataset = dataset_name,
        inference_set= inference_set_name
    )
]

issue_manager.create_issue(
    new_issue_name, 
    dataset_name, 
    elements = elements_to_add, 
    element_type = element_type, 
    inference_set =  inference_set_name
    )

Copying Existing Segment To New Segment

Use this example if you have a segment of say type "Model Performance" and you want to move the elements to a Bucket type segment.

At the moment, you are only able to create copied segments of type Bucket.

import os
import aquariumlearning as al

AQUARIUM_API_KEY = os.environ['AQUARIUM_API_KEY']

al_client = al.Client()
al_client.set_credentials(api_key=AQUARIUM_API_KEY) 

# set up your issue manager
issue_manager = al_client.get_issue_manager('YOUR_PROJECT_NAME')
issues = issue_manager.list_issues()

# to create an segment you have to set if it is a frame or crop level segment
element_type = "crop"

# get the issue you want to copy from
old_issue = next((x for x in issues if x.name == 'YOUR_ISSUE_NAME'), None)
# issue = issue_manager.get_issue('ISSUE_ID')

# grab dataset info
dataset_name = old_issue.dataset
inference_set_name = old_issue.inference_set

# lets grab all the elements from that issue so we can copy them

new_elements = []
for element in old_issue.elements:
     gtLabelId = element.element_id
     new_elements += [
            al.IssueElement(
                element_id = gtLabelId,
                frame_id = element.frame_id,
                element_type = element_type,
                dataset = dataset_name,
                inference_set= inference_set_name
            )
        ]

issue_manager.create_issue(
    f"{old_issue.name}_copy", 
    dataset_name, 
    elements = new_elements, 
    element_type = element_type, 
    inference_set =  inference_set_name
    )

Deleting Segments

Use this example if you would like to programmatically delete a segment through the API. You need access to the issue_id instead of issue name in order to delete it.

import os
import aquariumlearning as al
import json

AQUARIUM_API_KEY = os.environ['AQUARIUM_API_KEY']

al_client = al.Client()
al_client.set_credentials(api_key=AQUARIUM_API_KEY) 

# grab your issue_manager for the project
issue_manager = al_client.get_issue_manager('PROJECT_NAME')

# gets your issues for the project
issues = issue_manager.list_issues()

# searches your issues for the one with the same name
issue = next((x for x in issues if x.name == 'YOUR_ISSUE_NAME'), None)

# grabs the issue id
issue_id = issue.issue_id

issue_manager.delete_issue(issue_id)

Collection Campaign Segments

Creating a Crop Level Collection Campaign Segment

import json
import pandas as pd
import aquariumlearning as al

# set up the connection to Aquarium client
al_client = al.Client()
al_client.set_credentials(api_key=YOUR_API_KEY)

# provide the project and dataset - 
# inferences are assumed to be None and should be handled separately.
aquarium_project = 'rareplanes_2d_detection'
aquarium_dataset = 'retrain_rareplanes'
inference_set = None

# assume the source data is a three column csv 
# in the same directory as the script. 
# columns are - aquarium_label_id, aquarium_frame_id, segment_name
# where segment name is the name of the segment you want the data to be put into
source_data_path =  "./labels_for_collection.csv"
source_df = pd.read_csv(source_data_path)

# get the issue manager object 
im = al_client.get_issue_manager(aquarium_project)

for segment_name in source_df.segment_name.unique().tolist():
    elements_to_add = []
    # get the rows in the csv that have the same segment name
    segment_df = source_df.loc[source_df['segment_name'] == segment_name]
    for index, row in segment_df.iterrows():
        # creating the issue element object
        element = al.IssueElement(
            element_id = row['aquarium_label_id'],
            frame_id = row['aquarium_frame_id'],
            element_type = "crop",
            dataset = aquarium_dataset,
        )
        elements_to_add.append(element)
    # for each unique segment name create the segment
    im.create_issue(
        name = segment_name, 
        dataset = aquarium_dataset, 
        elements = elements_to_add, 
        element_type = "crop", 
        inference_set = None, 
        issue_type = "Collection Campaign"
    )