To highlight the core concepts and interactions, we're going to work with an open source dataset and computer vision task: classifying pet breeds from a photo. We'll be working with the oxford-iiit-pets dataset, which contains 6000 labeled images.
# Overall data structure├── imgs│ ├── Abyssinian_100.jpg│ ├── american_bulldog_125.jpg│ └── american_pit_bull_terrier_191.jpg├── inferences.json└── labels.json└── classnames.json# All images are mirrored online at# https://storage.googleapis.com/aquarium-public/quickstart/pets/imgs/<filename>.jpg# Format of labels.json[ {"file_name":"Sphynx_158.jpg","class_id":33,"species_id":0,"class_name":"sphynx","species_name":"cat","split_name":"train" }, ...]# Format of inferences.json[ {"confidence":1,"frame_id":"Sphynx_158","class_id":33,"class_name":"sphynx" }, ...]
Uploading the Data
Python Client Library
Reminder, the aquariumlearning package requires Python >= 3.6.
Aquarium provides a python client library to simplify integration into your existing ML data workflows. In addition to wrapping API requests, it also handles common needs such as efficiently encoding uploaded data or using disk space to work with datasets larger than available system memory.
You can install and use the library using the following code block:
!pip install aquariumlearningimport aquariumlearning as alal_client = al.Client()al_client.set_credentials(api_key=YOUR_API_KEY)
To get your API key, you can follow these instructions.
Projects
Projects are the highest level grouping in Aquarium and they allow us to:
Define a specific core task - in this case, pet breed detection (2D Classification)
Define a specific ontology
Hold multiple datasets for a given task/ontology
You can click here for more information on defining projects and best practices!
To create a project, we specify a name, what the full set of valid classifications are, and the primary task being performed.
import string
import random
import json
# Project names have to be globally unique in Aquarium
PROJECT_NAME = 'Pets_Quickstart'
# read in classnames file
with open('./classnames.json') as f:
classnames = json.load(f)
# create the project in Aquarium
# define ML task using the primary_task field
# the from_classnames() call uses the classnames we loaded in on line 9
al_client.create_project(
PROJECT_NAME,
al.LabelClassMap.from_classnames(classnames),
primary_task="CLASSIFICATION"
)
Labeled Datasets
Often just called "datasets" for short, these are versioned snapshots of input data and ground truth labels. They belong to a Project, and consist of multiple LabeledFrames.
In most cases a Frame is a logical grouping of an image and its structured metadata. In more advanced cases, a frame may include more than one image (context imagery, fused sensors, etc.) and additional metadata.
Now let's create our LabeledDataset object and add the LabeledFrames to it:
# read in labeled datawithopen('./labels.json')as f: label_entries = json.load(f)# defines our dataset we will be uploadinglabeled_dataset = al.LabeledDataset()# loop through each labeled/ground truth objectfor entry in label_entries:# Create a frame object, using the filename as an id# Frames must have a unique id frame_id = entry['file_name'].split('.jpg')[0] frame = al.LabeledFrame(frame_id=frame_id)# Add arbitrary metadata, such as the train vs test split frame.add_user_metadata('split_name', entry['split_name'])# Add an image to the frame image_url ="https://storage.googleapis.com/aquarium-public/quickstart/pets/imgs/"+ entry['file_name'] frame.add_image(image_url=image_url)# Add the ground truth classification label to the frame label_id = frame_id +'_gt' frame.add_label_2d_classification( label_id=label_id, classification=entry['class_name'] )# Add the frame to the dataset collection labeled_dataset.add_frame(frame)
Inferences
Now that we have created a Project and a LabeledDataset, let's also upload those model inferences. Inferences, like labels, must be matched to a frame within the dataset. For each LabeledFrame in your dataset, we will create an InferencesFrame and then assign the appropriate inferences to that InferencesFrame.
Creating InferencesFrame objects and adding inferences will look very similar to creating LabeledFrames and adding labels to them.
We then add the InferencesFrame to an Inferences object and then upload the Inferences object into Aquarium!
Important Things To Note:
Each InferencesFrame must exactly match to a LabeledFrame in the dataset. This is accomplished by ensuring the frame_id property is the same between corresponding LabeledFrames and InferencesFrames.
It is possible to assign inferences to only a subset of frames within the overall dataset (e.g. just the test set).
# load in inference filewithopen('./inferences.json')as f: inference_entries = json.load(f)# create our inference dataset we will be uploadinginference_dataset = al.Inferences()# loop through each inference objectfor entry in inference_entries:# Create a frame object, using the same frame id# labeled dataset image frame_id = entry['frame_id'] inf_frame = al.InferencesFrame(frame_id=frame_id)# Add the inferred classification label to the frame inf_label_id = frame_id +'_inf' inf_frame.add_inference_2d_classification( label_id=inf_label_id, classification=entry['class_name'], confidence=entry['confidence'] )# Add the frame to the inferences collection inference_dataset.add_frame(inf_frame)
At this point we have created a project in Aquarium, and uploaded our labels and inferences. The data has been properly formatted, but now as our final step, let's use the client to actually upload the data to our project!
Submit the Datasets!
Now that we have the datasets, using the client we can upload the data:
# the name of our dataset that will show up in AquariumLABELED_DATASET_NAME ='pet_labels'# call to upload our labeled dataset to our projectal_client.create_dataset( PROJECT_NAME, LABELED_DATASET_NAME, dataset=labeled_dataset, # Poll for completion of the processing job wait_until_finish=True)# the name of our dataset that will show up in AquariumINFERENCE_DATASET_NAME ='pet_inferences'# call to upload our inference dataset to the projectal_client.create_inferences( PROJECT_NAME, LABELED_DATASET_NAME, inferences=inference_dataset, inferences_id=INFERENCE_DATASET_NAME)
With the code snippet above your data will start uploading! Now we can monitor the status within the UI!
Monitoring Your Upload
When you start an upload, Aquarium performs some crucial tasks like indexing metadata and generating embeddings for dataset so it may take a little bit of time before you can fully view your dataset. You can monitor the status of your upload in the application as well as your console after running your upload script.
To view your upload status, log into Aquarium and click on your newly created Project. Then navigate to the tab that says "Streaming Uploads" where you can view the status of your dataset uploads.
Once your upload is completed under the "Datasets" tab, you'll see a view like this:
And congrats!! You've uploaded a dataset into Aquarium! You're now ready to start exploring your data in the application!
Completed Example Upload Script
Putting it all together here is the entire script you can use to replicate this project. Remember to download the data here to have access to the script and all the needed data.
#!pip install aquariumlearningimport aquariumlearning as alal_client = al.Client()al_client.set_credentials(api_key=YOUR_API_KEY)import stringimport randomimport json# defining names for project and the datasets as they'll show up in Aquarium# project names must be unique, and within a project, datasets must also have unique namesPROJECT_NAME ='Pets_Quickstart'LABELED_DATASET_NAME ='pets_labels'INFERENCE_DATASET_NAME ='pets_inferences'# define the filepaths we'll be working withclassnames_filepath ='pets_2D_classification_quickstart/classnames.json'labels_filepath ='pets_2D_classification_quickstart/labels.json'inferences_filepath ='pets_2D_classification_quickstart/inferences.json'# load in your classname filewithopen(classnames_filepath)as f: classnames = json.load(f)# load in your label datawithopen(labels_filepath)as f: label_entries = json.load(f)# load in your inference datawithopen(inferences_filepath)as f: inference_entries = json.load(f)# create the project in Aquarium# define ML task using the primary_task field# the from_classnames() call uses the classnames we loaded in on line 23al_client.create_project( PROJECT_NAME, al.LabelClassMap.from_classnames(classnames), primary_task="CLASSIFICATION")# defines our dataset we will be uploadinglabeled_dataset = al.LabeledDataset()# loop through each labeled/ground truth objectfor entry in label_entries:# Create a frame object, using the filename as an id# Frames must have a unique id frame_id = entry['file_name'].split('.jpg')[0] frame = al.LabeledFrame(frame_id=frame_id)# Add arbitrary metadata, such as the train vs test split frame.add_user_metadata('split_name', entry['split_name'])# Add an image to the frame image_url ="https://storage.googleapis.com/aquarium-public/quickstart/pets/imgs/"+ entry['file_name'] frame.add_image(image_url=image_url)# Add the ground truth classification label to the frame label_id = frame_id +'_gt' frame.add_label_2d_classification( label_id=label_id, classification=entry['class_name'] )# Add the frame to the dataset collection labeled_dataset.add_frame(frame)# call to upload our dataset to our projectal_client.create_dataset( PROJECT_NAME, LABELED_DATASET_NAME, dataset=labeled_dataset, # Poll for completion of the processing job wait_until_finish=True, # Preview the first frame before submission to catch mistakes preview_first_frame=True)# create our inference dataset we will be uploadinginference_dataset = al.Inferences()# loop through each inference objectfor entry in inference_entries:# Create a frame object, using the same frame id# labeled dataset image frame_id = entry['frame_id'] inf_frame = al.InferencesFrame(frame_id=frame_id)# Add the inferred classification label to the frame inf_label_id = frame_id +'_inf' inf_frame.add_inference_2d_classification( label_id=inf_label_id, classification=entry['class_name'], confidence=entry['confidence'] )# Add the frame to the inferences collection inference_dataset.add_frame(inf_frame)# call to upload our labeled dataset to our projectal_client.create_dataset( PROJECT_NAME, LABELED_DATASET_NAME, dataset=labeled_dataset, # Poll for completion of the processing job wait_until_finish=True, # Preview the first frame before submission to catch mistakes preview_first_frame=True)# call to upload our inference dataset to the projectal_client.create_inferences( PROJECT_NAME, LABELED_DATASET_NAME, inferences=inference_dataset, inferences_id=INFERENCE_DATASET_NAME)
