# Welcome to Biodock
Biodock's AI platform automates time-consuming microscopy image analysis.
%20\(1\).gif?alt=media\&token=bda6bad4-3705-474a-8441-ba2401e36405)
Biodock is a new, open AI platform for researchers that makes it easy to identify any biological object with remarkable accuracy. We make it easy to create and run models in an interactive compute environment that outputs directly to charts, overlays, and data.
**Getting started with Biodock**
Tutorials that get you from raw images to end-to-end quantitative pipeline.
{% content-ref url="/pages/En6aJ8rFKulKbJDI99TW" %}
[Quickstart](/start/start-here-choose-a-tutorial)
{% endcontent-ref %}
# Why Biodock
## Our view of image analysis
Most image analysis tools aren't actually aligned with how the best R\&D teams actually work with images. This creates a lot of friction and undesired outcomes.
### **Agile R\&D teams have**:
* Images that may look quite a bit different or be more difficult than "model" images or cells, due to differences in acquisition or differences in treatment / gene variation.
* Limited coding/scripting resources due to a mix of team members that may or may not know how to code at a high level.
* Objectives that depend on how mature your application is:
* **Early experiments and creation:** Add new, accurate, analyses quickly as R\&D direction shifts, extracting early results. Might not need massive compute at this stage.
* **Optimization:** Maximize accuracy and adapt to different imaging conditions, phenotypes, and objects easily. May need to run large-scale analysis - should only pay when it's used (serverless architecture). Easy access to data, analyses, and results for multiple team members.
* **As analyses mature**: Quality control, downstream processing, streamlined workflows, and economies of scale.
If you resonate with any of the above statements, we've built Biodock to be built around them!
## What Biodock is
Biodock is an end-to-end image analysis platform built around the way that R\&D teams actually work. Scientists on our platform tackle even very difficult images, all in a no-code, intuitive package. See [Path 2: Train a fully-automated AI model](/start/path-2-train-a-fully-automated-ai-model) for some examples of what scientists on our platform accomplish.
Our platform brings together:
* A best in class training dashboard, including versioned, powerful image transformer models and AI-assisted labeling. Always be able to reproduce runs and access results.
* A results dashboard with instant statistics, plots, visualizations, and QC for every analysis. Download anything, including raw predictions, per-object metrics, and more.
* A run engine that automatically handles annoying problems, like cropping and stitching for large images, serverless runs, progress, parallelization, and more.
* Massive compute to handle the largest images (pathology) or largest scale (high throughput)
* Collaborative sharing of files, projects, and models with access roles.
* Data integrations with AWS S3, Google Drive, Dropbox, OneDrive, Box
* An open documented REST API to automate running analysis or integrate it as part of a larger pipeline
...and much more, all within an intuitive, [highly secure](https://docs.biodock.ai/www.biodock/security), easy to use interface built for the scientist.
## Approaches we don't recommend
After working with lots of the best teams in bio, we've seen many approaches to image analysis that often lead to bad outcomes. While these approaches aren't necessarily invalid, we generally advise against them unless you know that your application is especially well suited to these.
Below, we've compiled a list of some of these not recommended approaches, and why we think that generally they don't lead to the outcomes that teams think they will when they embark on those paths.
### Building in-house AI models and scripts
It's not too difficult for a talented engineer to get good performance on a subsection of an image by fine tuning an open-source model. However, this is only the tip of the iceberg. Once you get past initial model training, there are far more difficult problems, including:
* Labeling data to train the model (Pay? Use a commercial or free software?)
* Training optimally, with the newest architectures and best practices for bio
* Doing QC on results, and making sure those efforts result in better model performance
* Keeping around different model versions and managing your ground-truth data for reproducibility.
* Running images on different sizes of images, including those that may not fit in memory.
* Running inference at scale and stitching together objects across crop boundaries.
* Sharing the model in a way that can be run by your team and beyond, including people who are not computational.
* Having a tested and scalable API to automate analysis.
* Scaling and deploying your compute in a way that will work on larger analyses.
* Adapting your model to new data or variations.
* And many, many more considerations!
If none of these apply to you, it might be a good option. However, these are fairly large, pure software problems that each could be a full time job even for the best engineers with significant software and AI expertise. Our entire team works only on these things so that you don't need to.
In reality, the best investment on your computational team is if they can work on **novel problems** to drive forward your R\&D, and not have to deal with reinventing the wheel.
### Buying a license or software that "does X analysis."
At first glance, this may seem to be the easiest option. However, this can start to become an issue due to generalization. You may have experienced this before - an analysis made for a certain type of image doesn't work as well as soon as your images look a little bit different.
Generally, these licenses also tend to be inflexible in the case that research direction changes, and are often gated in a way that makes them work against your computational team members.
We've found that most other "AI" software products tend to have you annotate patches of data, and train using models like DenseNet, VGG, and other models that don't perform too well on images by modern standards. While pretty convenient, their "pixel classification" architectures tend to fail on all but the easiest analyses.
### Using open source software (sometimes)
We don't want to take away from the amazing tools that are available open source, like FIJI (ImageJ), CellProfiler, etc. If your analysis is low-volume and simple, extending them with macros might be a low-barrier way to do analysis, especially if your team has experience with them.
However, we generally find that in addition to the problems above from buying licenses, teams "get stuck" with the capability of these software packages. It's generally difficult to adapt when you run into problems (images are too difficult for good performance, images are too large, analysis is too slow, too many images, etc.) Teams often end up with pipelines that only work on simple images and often need to be tweaked for each new batch of images. They end up without a reproducible ledger of results, and need to build the rest of their pipeline, integrations, data outputs, and more.
## What Biodock isn't right for
Despite a host of open-source and commercial tools available, we believe that Biodock is the right choice for a large and expanding array of image analysis and organizations. However, Biodock isn't made for everything. If you fit in the list below and need to do analysis now, you should probably evaluate other tools.
### Applications with limited support on Biodock
* Applications that require local deployment (low latency or realtime applications, on-premise server communication, etc)
* 3D volumes (Z-stack 2D segmentation is supported)
* Object tracking keeping the same ID across frames (non-tracking time series can be done with image groups). **Coming soon.**
{% hint style="info" %}
Unsure if your application is supported? We'd love to help! Send us a message using the chat bubble in the bottom right or [Contact us](/company/contact-us)
{% endhint %}
# Start here (choose a tutorial)
Biodock makes it easy to identify, segment, and classify objects within your images, quantifying everything from signal intensity, to size, to morphology, or to relationships between objects.
You'll use powerful AI assisted tools like AI Detect (GIF below) and AI Select to automate away most of the effort!
. (AI Detect with two classes)
### What you need to start
* A registered account on Biodock (see [how to register here](/user/account-registration)), using Google Chrome (Biodock is only officially supported on Chrome)
* The images you want to train and analyze with, in a [supported format.](/files/supported-image-types)
* An idea of the type of object or objects you want to identify (ie: cells, organoids, puncta, tissue regions, etc.) on your images.
### Then, choose a tutorial
If you just want to do **small scale analysis** now (small images and/or very few # of images), start with our AI-assisted analysis. You can train a model from your analysis later if you want.
{% content-ref url="/pages/yywmxnhCbF8sRzpXPBJD" %}
[Path 1: AI-assisted analysis](/start/path-1-ai-assisted-analysis)
{% endcontent-ref %}
If you have **large images** (tissue slides) and/or a large number of images, start here - it will be faster to train a model from the beginning. If you want to automate your assay from the beginning, you can go here as well.
{% content-ref url="/pages/VmaxcVbBhHQmtsDExnqP" %}
[Path 2: Train a fully-automated AI model](/start/path-2-train-a-fully-automated-ai-model)
{% endcontent-ref %}
### What can you do with Biodock?
Examples of what you might be able to accomplish
* Identify the size, shape, and count of label-free organoids and compare them across groups
* Count the number, size, and fluorescent intensity of tumor and T cells within each solid tumor
* Identify areas of inflammation within enormous pathology slides
* Quantify puncta size and intensity in a in-situ hybridization assay
* Plain old cell segmentation to find positive cell populations
* Isolate crypts and epithelial cells within intestinal H\&E images
# Path 1: AI-assisted analysis
{% hint style="info" %}
Want to fully automate your analysis to batch run on many images? Follow that tutorial [here](/start/path-2-train-a-fully-automated-ai-model) instead. This tutorial involves some amount of manual work to get to your results.
{% endhint %}
## Overview
AI-assisted analysis is the fastest way to get to quantitative results for small image sets. However, as there is still a manual-edited portion, it may not be suitable for analyses that have too many objects, such as:
* Large batches of images with many objects per image
* Segmenting out small objects like cells on whole-slide images
## Tutorial
## 1. Upload images
*If you already have uploaded files, you can skip this step.*
Navigate to **Files** from the left sidebar, and press **Upload**. You'll be able to upload from your computer, or import from a third party ([even S3](/files/aws-s3-integration)). This will take a second to upload and process into files.
## 2. Start the analysis
Once your files are uploaded, go to **AI Analysis** on the left sidebar, and click **Start a new analysis run**. Then choose **AI-assisted**, and choose the files that you uploaded. Then press **Start**. This should open you into an AI-assisted analysis window.
## 3. Label
### Your labeling tools and how to use them
Select your first class on the left toolbar. Once you click, you will have three different tools you can toggle between by clicking them: AI Detect, AI Select, and Pen. You'll also now be in drawing mode, so you will now need to hold **Space** to be able to pan across your image.
AI Detect is the fastest, and you should use it unless it isn't working well for you, filling in the gaps with AI Select. The Pen is the slowest, and should be used if AI Select is not working for you. AI Detect is only applicable to object classes.
{% tabs %}
{% tab title="Using AI Detect" %}
{% hint style="info" %}
AI Detect might not work well for harder images - in these cases, you may need to use AI Select heavily. We'll be improving AI Detect over time.
{% endhint %}
To use AI Detect on a tile, drag a tight box around one example of your object, using the crosshairs to help you. AI will locate the position of similar-looking objects, and also segment them.
#### Using the filters
After you use AI detect, you'll need to filter the results, using the sliders. The **confidence score** slider controls the model score threshold at which objects are filtered out. Drag higher to get fewer labels, and lower to get more labels.
The **size range** slider has a minimum and maximum upper bound. You can filter out or include larger or smaller objects using these ranges.
{% endtab %}
{% tab title="Using AI Select" %}
To use AI select, "prep" a tile by clicking on it, which should be ready in around one second. You will start seeing predictions in real time when hovering.
#### Labeling objects with AI
1. Label your object by clicking, or drag a box around it for a more precise label on difficult objects.
2. Refine by clicking. Click outside the object to grow your object, and inside to shrink your object.
3. Press **A** on the keyboard to start a new object.
{% endtab %}
{% tab title="Using the Pen" %}
Drag and click around your object to get your label.
{% endtab %}
{% tab title="Select/Delete/Edit" %}
### Select
To select one object, click on it on the image, or select it from **Labeled objects** on the left. To select many, hold `Ctrl` or `Cmd` and drag on the image.
### Delete
To delete selected objects, you can press `Backspace`. Press `Enter` to confirm.
### Edit
Make sure that you are out of drawing mode (press `ESC`). Select an object by clicking it in the viewer or from the **Labeled objects** section. Then, press the key `e` or click on the pencil in the **Labeled objects** section to enter editing mode. From here, you can choose to Add or Subtract from the object. Draw an object that will be added or subtracted from that object. Once your object has been completed, your changes will be automatically saved.
{% endtab %}
{% endtabs %}
#### Other settings you might use for labeling
You might need to switch images, add images, configure classes, or adjust your brightness/contrast settings. Find the instructions for those below.
{% tabs %}
{% tab title="Classes" %}
#### Changing class color
You can also choose from different colors to represent the class. Simply click the colored circle to open up a color picker.
#### Changing the name or deleting a class
Hover over the class to reveal the 3 dots button, which you can click. From there, use the dropdown to rename or delete a class. **If you delete a class, every object created for that class will be deleted as well.**
#### **Add a new class**
Click the + button next to your size group on the left sidebar to add a new class. You might need to add a new size group if your new class represents an object that is of significantly different size or a different segmentation type.
{% endtab %}
{% tab title="Size groups" %}
#### Adding a new size group
Click **Add size group** from the left bar, and follow the setup flow to select your segmentation type and tile size.
#### What is a size group and why should I make one?
A size group is a group of classes that use the same tile size and segmentation type. They allow your AI model to see your objects at different scales in the same image, to optimize your accuracy. This also allows you to infer interesting parent-child hierarchy information from very different sized objects.
Create a new size group if you want to:
* Blending region segmentations (confluence, inflammation, tissue regions) with object (cell, cyst, organoid) in one model.
* Blend two very different sized objects in one model (organoid and cells, tumor and immune cell, crypts and goblet cells)
* Separate labeling for sparse vs. dense classes (rare cell type vs. very common cell types)
Keep in mind that adding a new size group increases training and analysis credit usage.
{% endtab %}
{% tab title="Switch or add images" %}
#### Switching between images
Click on the dropdown under **Choose image** on the left sidebar, and select a new image to change to it**.** You can scroll, filter, and search to find your image. Alternatively, press **Next** or **Prev** to move forward or backwards.
#### Adding images
If you need to upload more images, you'll need to exit the dashboard entirely and add more images. Click the **X** in the top left to exit, and look for the **Add or remove data** tab.
{% endtab %}
{% tab title="Brightness/Contrast" %}
#### Adjusting brightness/contrast
{% hint style="info" %}
Note: your model will **not** see these adjustments! If you need to adjust a channel to be able to see an object, you should make those changes in the project channel settings, as detailed in [Project settings](/ai-projects/project-settings)
{% endhint %}
From the top bar, click **Settings** -> **Image settings** Here, you can adjust brightness and contrast on a per-channel basis, or hide/show a specific channel for an image.
{% endtab %}
{% endtabs %}
## 4. Quantify your labeled objects
### Submit for analysis
Once you've labeled all of your objects of interest, you can quantify them. Don't worry, you'll be able to add more objects later and re-quantify.
Click the **Quantify objects** button, to open up your configuration window.
\
On this window, you can choose the metrics you'd like to quantify, including channel intensities and morphological characteristics. Choosing more metrics can lead to slower processing. Then, press submit.
### Interpreting your results
You're done and ready to look at your results! View the [Results dashboard overview](/ai-analysis/results-dashboard-overview) to understand this page.
# Path 2: Train a fully-automated AI model
This getting started tutorial will get you from raw images to an end-to-end custom AI image analysis with results. This tutorial is expected to take about 5-15 minutes of active work depending on the difficulty of your images, and about 1 hour of waiting. Your new model will classify, segment, and quantify your areas of interests in your images.
{% hint style="info" %}
This same tutorial is also shown as a checklist and tutorial in-platform.
{% endhint %}
### Watch the tutorial in video format
{% embed url="" %}
### Follow along in the docs
Press next below to follow along in the docs.
# Set up your project
*Time estimate: 4 minutes work, 3 minutes wait*
## 1. Create a Project
To start, navigate to [app.biodock.ai](https://app.biodock.ai/) and follow these steps:
Click on **AI Projects** from the sidebar, and click on **Create a new project.** Enter a helpful project name and description, and then click **Create** to finalize your project.
## 2. Upload Data
Once your project is created, it's time to import your images.
**Choose from files**
Click on **Select Files.** Choose the desired files from the list. Click **Import** to add them to your project. Wait for the import to finish and finish processing your files.
## 3. Configure your project
{% hint style="info" %}
If you have images with more than 3 channels, you will need to [configure channel settings](/ai-projects/project-settings) before you can proceed. You should also do this configuration if any of your channels are too dim.
{% endhint %}
First, enter the model creation dashboard by clicking on **Create or improve AI models**. Follow the instructions to create your first size group. You'll choose a segmentation type, choose a tile size, and add your first class.
#### Choosing a tile size
Biodock creates a grid-like set of tiles for labeling and training. Box around the object to select proper tile size. It's **very important** to follow the on-screen instructions to choose your tiles size correctly. Smaller tile sizes use more [credits](/user/usage-limits-and-team/run-credits-limits).
### Overview
The labeling tab has tools on the left side, your zoomable image in the center, and a tutorial on the right. If you follow the tutorial, it will guide you step by step to a great performing AI model in most cases.
Continue to the next page!
# Label and train
## 1. Label your first images
{% hint style="info" %}
Make sure to follow the guidelines (right toolbar), which has the most detailed instructions to walk you through creating your first model.
{% endhint %}
### Your labeling tools and how to use them
Select your first class on the left toolbar. Once you click, you will have three different tools you can toggle between by clicking them: AI Detect, AI Select, and Pen. You'll also now be in drawing mode, so you will now need to hold **Space** to be able to pan across your image.
AI Detect is the fastest, and you should use it unless it isn't working well for you, filling in the gaps with AI Select. The Pen is the slowest, and should be used if AI Select is not working for you.
It is **expected and normal** to have object cut off by the tiles. When the model is used for analysis, it will automatically stitch across tile boundaries. Do not adjust your tile size to avoid this.
{% tabs %}
{% tab title="Using AI Select" %}
To use AI select, "prep" a tile by clicking on it, which should be ready in around one second. You will start seeing predictions in real time when hovering.
#### Labeling objects with AI
1. Label your object by clicking, or drag a box around it for a more precise label on difficult objects.
2. Refine by clicking. Click outside the object to grow your object, and inside to shrink your object.
3. Press **A** on the keyboard to start a new object.
{% endtab %}
{% tab title="Using the Pen" %}
Drag and click around your object to get your label.
{% endtab %}
{% tab title="Select/Delete/Edit" %}
### Select
To select one object, click on it on the image, or select it from **Labeled objects** on the left. To select many, hold `Ctrl` or `Cmd` and drag on the image.
### Delete
To delete selected objects, you can press `Backspace`. Press `Enter` to confirm.
### Edit
Make sure that you are out of drawing mode (press `ESC`). Select an object by clicking it in the viewer or from the **Labeled objects** section. Then, press the key `e` or click on the pencil in the **Labeled objects** section to enter editing mode. From here, you can choose to Add or Subtract from the object. Draw an object that will be added or subtracted from that object. Once your object has been completed, your changes will be automatically saved.
{% endtab %}
{% endtabs %}
### Labeling guidelines
1. Focus on one tile at a time. Label every object in that tile, *including objects that are cut off* by the edge of the tile. Once every example in that tile has been labeled, click **Fully Labeled** on top of that tile (in the gray box).
2. Track your progress in the right sidebar tutorial as you mark more tiles as **Fully labeled**, until you fill up the bar.
3. Make sure you are being careful and consistent with labeling. Don't miss objects, and label the border of objects precisely, moving to the Pen when necessary. It is far better to label precisely than it is to label more data less precisely.
#### Other settings you might use for labeling
While labeling, you might need to do some of the following:
* Add or configure object/region classes
* Add a new size group for distinct objects
* Switch the currently displayed image
* Add training images to your project
* Adjust channel settings for your entire project
* Customize channel settings for each size group
Instructions for those features can be found below:
{% tabs %}
{% tab title="Classes" %}
#### Changing class color
You can also choose from different colors to represent the class. Simply click the colored circle to open up a color picker.
#### Changing the name or deleting a class
Hover over the class to reveal the 3 dots button, which you can click. From there, use the dropdown to rename or delete a class. **If you delete a class, every object created for that class will be deleted as well.**
#### **Add a new class**
Click the + button next to your size group on the left sidebar to add a new class. If your new class represents an object that is of significantly different size or a different segmentation type, you may need to [**create a new size group**](#size-groups) for best results.
{% endtab %}
{% tab title="Size groups" %}
#### Adding a new size group
Click **Add size group** from the left bar, and follow the setup flow to select your segmentation type and tile size.
#### What is a size group and why should I make one?
A size group is a group of classes that use the same tile size and segmentation type. Each size group will have it's own ML model trained, and your pipeline will use these models in conjunction to detect all objects in your images. This optimizes accuracy by allowing your AI model to see your objects at different scales in the same image. This also allows you to infer interesting parent-child hierarchy information from very differently sized objects.
Create a new size group if you want to:
* Combine region segmentations (confluence, inflammation, tissue regions) with object (cell, cyst, organoid) in one pipeline.
* Detect two very different sized objects in one pipeline (organoid and cells, tumor and immune cell, crypts and goblet cells)
* Separate labeling for sparse vs. dense classes (e.g. rare cell type vs. very common cell types)
Keep in mind that adding a new size group increases training and analysis credit usage.
You can [**customize channel settings**](#channel-settings) for each size group to further optimize accuracy across diverse objects.
{% endtab %}
{% tab title="Switch or add images" %}
#### Switching between images
Click on the dropdown under **Choose image** on the left sidebar, and select a new image to change to it**.** You can scroll, filter, and search to find your image. Alternatively, press **Next** or **Prev** to move forward or backwards.
#### Adding images
If you need to upload more images, you'll need to exit the dashboard entirely and add more images. Click the **X** in the top left to exit, and look for the **Add or remove data** tab.
{% endtab %}
{% tab title="Channel Settings" %}
#### Adjusting Channel Settings
{% hint style="info" %}
Note: your model will **only** see your channel setting changes if you press **Save**. Otherwise, your changes will be lost when you leave the Labeling UI.
{% endhint %}
At the top of the labeling sidebar, click the **Channel settings** button. Here, you can adjust brightness and contrast on a per-channel basis, or disable/enable a specific channel for an image.
#### Channel Settings Options
* **Save:** you must press this button for your changes to be saved and applied during training
* **Discard Changes:** resets your adjustments to the last saved settings (or to default settings)
* **Enable size group customization:** this mode allows you to define custom channel settings for each size group, rather than applying the same settings across the whole project.
#### Tips for "Size Group" Mode:
* The channel settings window will adjust channel settings for your **currently selected size group**
* Pressing **Revert to project settings** will delete all size group settings and ensure your project settings are applied to all size groups
* This mode is designed for the following use cases:
* Fluorescent images with distinct signal channels
* Images where specific classes become distinguishable only with adjusted channel settings
{% endtab %}
{% endtabs %}
## 2. Train your first AI model
Once you've filled up the Tutorial progress bar, you're ready to train your first AI model! Click on the **Train** tab, and click **Train a new model**. You'll see the following screen, where you can:
* Split labeled images into train and test sets
* Customize transforms applied during training
* Add an optional description for this pipeline
* Define size group hierarchies
* Only applicable when multiple size groups are present, see [ROI Hierarchies](/start/path-2-train-a-fully-automated-ai-model/configuring-your-model#size-group-roi-hierarchy) for more details
* Review image channel settings
* When [Size Group mode](#channel-settings) is enabled, you can review settings for each size group
When your pipeline is ready to go, click **Start training**.
Now, you can monitor your training progress. It will have a progress bar and an approximate ETA.
## 3. Test and improve your model
Once fully trained, we'll see how well your first model does on tiles it hasn't seen.
Navigate to **Project and model details**, and click on the AI model version, and click on the Statistics tab. You'll see "Quantitative metrics," These metrics indicate how this AI model performed on the images selected for training and test. If there is a particular group of data your analysis didn't do well on, it might mean you need more data in that area.
"Training Set" refers to tiles that you labeled that were used to train the AI model. "Test Set" refers to tiles that were not included in training the AI model. The statistics given are a measure of how close the AI model was to replicating your labels, that is how accurate it is.
Intersection-over-union (IoU) indicates how closely the AI's predictions are with your training labels you put in. It's calculated by dividing the area of overlap between the predictions and your training labels by the union, that is the area covered by at least one prediction. That gives a score between 0 and 100, where higher scores indicate better accuracy.
The bbox column under statistics means a bounding box around the predicted and labeled objects while the mask means the outline of the detected object itself.
If the score is 100, that indicates the predicted labels were exactly overlapping with the labels you put in, whereas a score of zero means no predicted labels overlapped with your training labels.
This can be helpful in quantifying how accurate a model is, but qualitatively determining if a models is making the right calls or not is often better.
Navigate to **Label** on the top bar, or click **Evaluate** on your trained pipeline to be taken there.
### Test using AI Prelabel
As prompted by the right toolbar, use the new **AI Prelabel** button next to your size group to test your new model out. Click the tool, and then click unlabeled tiles on your images to prelabel them - they should be labeled in less than 10 seconds. If you have multiple size groups, you'll need to do this for each size group.
Your first model will almost always have mistakes after your first training run, due to the very small number of objects it was trained on. Choose **Improve model**.
### Improving your model
{% hint style="info" %}
Now that you've trained a first model, you should probably stop using AI Detect. Using AI Prelabel, followed by AI Select for corrections is more efficient after training your first model.
{% endhint %}
Once you've trained and evaluated your first AI model, you will now be able to label and improve assisted by AI. Your workflow is now:
1. **Prelabel tiles with AI** - Use the new AI prelabel tool on the left toolbar to test your model, and generate labels with your last model version.
2. **Correct prelabeled tiles** - Prelabeled tiles are shown in purple. Correct these by adding, removing, and editing objects, and mark them as corrected. Make sure to focus on one tile at a time, only clicking **Corrected** once that tile is completely correct. Verify that every object has been labeled, even ones on the edge, and incorrect labels have been deleted.
3. **Train and test** - Once you have a good amount of newly fully labeled and fully corrected tiles, train a new version like before to get a better model. The tutorial will suggest how many tiles you should correct to get a big boost in performance, but you can do this at any time.
You'll want to repeat these 3 steps until you have perfect or close to perfect performance! In most cases, it's best to improve your model at least two times before moving on, but you can always come back to improve it more.
# Labeling shortcuts
#### General Controls
* Shift key: Hide labels over the image
* A: Accept AI selection
* Escape: Stop labeling
* Space bar: Switch from labeling to move image
* Number buttons: Switch to that size group
#### Editing Objects within Size Classes
* D: AI detect (drag the box around one object and AI will try to select all)
* S: AI select tool (click to select individual objects)
* P: Pen tool (manually draw objects)
#### After Clicking on an Object
* E: Edit an object with the pen tool
* A: Add with the pen tool onto an existing object
* M: Subtract area from the selected object with the pen tool
* Delete: Delete the selected object
#### Multiple Object selection and bulk actions
* Command (Mac) / Ctrl (Windows) + Click: select multiple objects
* Command (Mac)/ Ctrl (Windows) + Drag with mouse: highlight/select multiple objects
* After selecting multiple objects you can perform bulk actions such as, delete, merge and change class.
# Run your AI model
*Estimated time: <1 minute*
Now that you have a good version of an AI model, it's very easy to run it on new data.
### Starting analysis
Navigate to **AI Analysis**, and select **Start a new analysis run**.
### Step 1: Select model
Choose your activated AI model from the dropdown. Click **Select** next to the AI model (and a version, if you have multiple activated versions).
### Step 2: Select images
Select the images or folders you wish to analyze. If you select a folder, all images within that folder will be analyzed. You can select multiple items by dragging your mouse or holding the shift button while clicking. Selected images and folders will be highlighted in blue to indicate they are currently selected. Click the **Confirm selection** button at the bottom of the page when you have selected all of the items you wish to analyze.
#### **Folder hierarchies**
If you create a hierarchy of folders, we will create selectable groups for you in results. This makes it very easy to be able to compare groups of images once your analysis is complete. See the following illustration to see how this is mapped into a selectable tree on the results dashboard:
**Step 3: Enter parameters and Submit**
Finally, review your run credit cost and click the **Submit** button to start running your AI Module. Doing so will take you to the Results List where your new run will be shown at the top of the list with a progress bar.
### Observing progress
Once the AI Module starts running, you can observe its progress on the Results List. The higher the size and number of your images, the longer the module will take to run. It is safe to close the browser tab and reopen it later.
### Interpreting your results
Once the AI Module is finished running, its Result will become a link which will take you to its [Results Dashboard](/ai-analysis/results-dashboard-overview). You can click this to immediately see statistics, plots, and data download.
# Configuring your model
Once you have a model that works well, you might want to add and remove different metrics for morphological characteristics, intensity, model score, or others.
You can change the metrics computed per object, predict fewer or greater objects, or create parent-child hierarchies to answer questions like "How many of class X in class Y?". Find each section below.
## Customizing model behavior
{% hint style="info" %}
To customize model behavior, it must be activated. For all customizations on this page, your metrics will only be computed for *new* result*s.* Submit a new run to see your changes.
{% endhint %}
To customize model behavior, head over to **AI Projects** and click on your project. In the bottom section under **Active AI models**, choose the version you'd like to customize. Then follow the instructions for what you want to customize.
### Predict greater or fewer # of objects
For **object** classes, every prediction comes with a model score, which is a decimal ranging from 0 to 1. To reduce the number of bad predictions, we set a threshold at 0.05, which filters out predictions with a model score less than 0.05.
To change the threshold used for cutoff during analysis time, go to the **Train/test predictions** tab. Simply drag the slider, and observe the changes that you see. Then, to lock in that threshold for analysis, select **Update analysis threshold**.
### Change computed metrics
Each model comes with default metrics for each object, such as X-Y position, object area, channel intensities, and more. You can add or remove metrics by going to the **Metrics** tab. Check on or off metrics, and hit **Save selection** to lock in your settings.
* **X Position** - Pixel X position of the centroid of the object (left to right). This is in absolute pixels of the entire image.
* **Y Position** - Pixel Y position of the centroid of the object (top to bottom). This is in absolute pixels of the entire image.
* **Area** - Number of pixels that the object covers.
* **Perimeter** - Count of pixels over the outer boundary of the object.
* **Image origin** - Filename of the image the object originated from.
* **Average Intensity (channel N)** - Average intensity in channel N over the object area. If there are N channels in the image, there will be N channel features.
* **Solidity** - A measurement of the overall concavity of an object. Ratio of pixels in the region to pixels of the convex hull image.
* **Eccentricity** - A measure of how elliptical an object is. A perfect circle has an eccentricity of 0.
* **Major axis** - The length of the major axis of the ellipse that has the same normalized second central moments as the region. This is generally a good proxy for the longest width of the object.
* **Minor axis -** The length of the minor axis of the ellipse that has the same normalized second central moments as the region. This is generally a good proxy for the shortest width of the object.
* **Curved length** - A good metric for the length of a long curved object (like lung cells, worms, etc). Obtained using the binary skeletonization of the mask, this is not a good fit for mostly circular objects.
* **Model score** - The score, generally from 0 to 1, that the AI model computed for this object. This is often referred to as the confidence score.
#### Less common
* **Equivalent Diameter** - The diameter of a circle with the same area as the object.
* **Euler Number** - The total number of objects minus the total number of holes in those objects in an image.
* **Extent** - The ratio of pixels in the object to the pixels in the bounding box of the object.
* **Feret Diameter Maximum** - The longest distance between points around an object’s convex hull contour.
* **Orientation** - The orientation of the object.
* **Perimeter Crofton** - The perimeter of the object approximated by the Crofton formula in 4 directions.
* **Area Bounding Box** - The number of pixels the bounding box of the object occupies.
* **Area Convex** - The area of the convex hull image, which is the smallest convex polygon that encloses the region.
* **Area Filled** - The area of the region with all holes filled in.
* **Colocalization: Pearson** - Correlation coefficient between channel pairs
* **Colocalization: Manders** - Overlap coefficient between channel pairs
* **Area threshold** -For a specified channel, applies brightness/contrast settings and determines the area above or below the specified threshold. Units are in pixels or percentage. This allows for quantifying the positive signal after adjusting the brightness and contrast. In the setting below, the system will quantify all pixels above the threshold set by the brightness and contrast setting. If you set it to Below, it will quantify all pixels below the threshold.
Area threshold set set up
Original Green channel setting
This is how it looks when you set the green channel setting as seen in the screenshot above.
### Hierarchies
#### Class Hierarchy
Class Hierarchies are parent-child relationships that allow metrics such as Number of Class X within Class Y, as well as others.\
\
Examples of how you might use this as parent→child:
* **Organoid→cell** Get the number of cells per organoid
* **Cell→puncta** Get the number of puncta within each cell
* **Tissue region→positive cell** Count number of positive cells in a certain region
* **Tumor→immune cell** Get metrics for immune cell infiltration
To create a new hierarchy, start from **Configure class hierarchy**. From there, select **Create class hierarchy**. Fill out the form and press **OK.**
#### Size Group ROI Hierarchy
Define region of interest hierarchies between size groups to enhance precise analysis and detection within specified areas. Once configured, the child class is segmented only within the parent class, while areas outside the parent class remain unsegmented. This saves time and credits during segmentation job.
**Tissue region→positive cell** Positive cells are only segmented in a Tissue region
**Organoid→cell** Cells are only segmented with organoid
### Configure grow/shrink transforms
#### Object Scaling and Transformation
This feature allows you to expand or contract a class of objects by desired pixel amounts:
* **Grow:** Useful for expanding cells from the nucleus, associating cytoplasmic or extracellular expressions, or connecting puncta to the nearest cell.
* **Shrink:** Helps in removing autofluorescence or edge effects near the boundaries of a cell or tissue sample.
Options include:
* **Hollow:** Creates a ring around the object.
* **Filled:** Transforms the object into a filled shape.
Customizations:
* **Naming Classes:** Assign names to different object classes.
* **Color Changes:** Modify the color of the objects as needed.
# Project settings
For anything in this page, head to **AI Projects** -> **Your Project Name** -> **Project Settings**. This is not to be confused with general settings on the bottom of the sidebar.
On this screen, you can change the project name, description, tile size, and even delete a project. You can also change the Featured Project Image and Channel settings, explained below.
### Changing the Featured Project Image
The Featured Project Image dictates the thumbnail that will be auto selected for visual purposes when choosing an AI model. You can change this to whatever base image you would like by clicking the filename in the dotted box, and choosing an image to swap to
### Changing Project Channel Settings
You must configure project channel settings if you have images with > 3 channels. You can also configure just to change brightness/contrast settings.
Biodock supports up to 7 channels using psuedocoloring, but generally performance is best with 3 channels or fewer, unless your channels are sparse. You should choose only the most essential channels needed to identify your objects of interest.
{% hint style="info" %}
Note that even if you only choose 3 channels here, you will still be able to quantify intensity across up to 100 channels! These channels are only for segmentation.
{% endhint %}
Use the Add channel button to name your channels and choose the color with which to represent them. At analysis time, you can map input images to these channels, even if they aren't in the right order.
You can also choose brightness and contrast adjustments, per channel, that will apply across every image in the project, as well as at analysis time. If you have significant variation, it's best to be conservative with these adjustments.
You can also make adjustments to project channel settings, or define custom settings per size group, in the [Labeling UI](/start/path-2-train-a-fully-automated-ai-model/label-and-train#channel-settings).
#### Channels:
In Biodock, a channel represents a single layer of image intensity data corresponding to a specific signal, such as a stain, marker, or wavelength. Each channel can be visualized as a grayscale image, where intensity reflects signal strength. Multiple channels can be combined and color-mapped (e.g., RGB) to form composite images for analyzing multiple signals simultaneously.
Before uploading to Biodock, you should check how many channels your images contain and what each channel represents. Most color images have three channels (Red, Green, Blue), while grayscale images, such as those from electron microscopy, typically have a single channel. In immunofluorescence images, each channel usually corresponds to a specific biological marker. In some cases, an image may technically contain three channels, but only one carries signal while the others are empty, making it effectively a single-channel image.
Biodock can process all of these image types; however, before training a model or analyzing images, users should confirm that channels are correctly interpreted and correspond to the expected signals.
#### Deleting the project
Go to Project Settings scroll down to Delete Project
# Sharing your AI project
It's easy to share your AI projects with collaborators or labelers.
In order to add people to your project, simply navigate to **AI Projects**-> **Your Project Name** -> **Project** **Settings** and scroll down to **Project Members**.
### Roles
**Owner** - has the same privileges as the creator of the project. They can submit training jobs, add project members, and have access to trained AI pipelines from this project.
**Labeler** - limited privileges, and can only review images and label objects of interest in ground truth datasets. They do not have access to trained AI models from this project.
# Training a model
**Description**
This is a label for your convenience that will be shown in the AI pipelines table. This will help you distinguish between multiple versions.
**Choose classes to include**
Select one or more classes that you created to include in training. Any classes you do not check here will be excluded from training.
**Create a test set**
You can customize which tiles you'd like to use for training vs test. Test images are **not** trained on, and used only to assess performance. This is important to realistically evaluate the performance you will get during analysis time.
In your first few iterations, it's more important to use all of your training data, as this won't be your final model. We recommend not using any tiles for testing until your model performance starts to look very good.
### Supported model types
We support the following model types:
* Instance segmentation (classify, segment, and separate each type of object within an image)
* Semantic segmentation (classify and segment out object regions within an image)
We use state-of-the-art models for our segmentation models, transfer learning off an optimal dataset. Our architectures are usually based off of vision transformer bases.
## Training run performance
Biodock allows you to evaluate a training run's performance quantitatively and statistically after a model has been trained. You can see these from doing evaluation on a trained model (see [Label and train](/start/path-2-train-a-fully-automated-ai-model/label-and-train)), or by navigating to **AI Projects -> Active AI models** or **All AI models ->** Click on the version that you would like to open.
### Training details
The training details section helps you get a broad picture of the AI pipeline and the data it was trained on. You can review information such as total images, included images, average number of images, included classes, and errors or warnings.
### Qualitative performance
The qualitative performance tab allows you to see, qualitatively, how well the model performed on your test image and your training images. To toggle between the two, simply select on the toggle between **Test images** and **Train images**.
You'll immediately see the image viewer, which will allow you to toggle between different images and see objects that were predicted with AI.
#### Thresholds
For each object, your AI models output a confidence score. The threshold controls the minimum score needed to be included in the output. Drag the slider up and down to control which objects are displayed - a lower threshold will output more objects, while a higher threshold will output fewer objects. Then, to lock in your threshold for use during Analysis, click **Update analysis threshold**.
#### Choose visible classes
Use the class selector and **Show outlines** in order to toggle on and off outlines to help you look at how the segmentation did.
### Statistical performance
The statistical performance section shows a table with summary statistics about how the model performed on both the train and test set. These metrics are especially useful when trying to compare performance between different models.
# Public AI models
Now you can make your models that you trained in Biodock Public to any users of Biodock. Under **Project and model details g**o to **AI Project Settings.**
#### Public AI Models
You can make AI models trained in Biodock available to all Biodock users by publishing them as **Public Models**.
To publish a model:
1. Open your AI project and navigate to **AI Project Settings**.
2. Select the model version you want to make public.
3. Enter the required model information and descriptions.
4. Enable the **Public** option and save your changes.
Once published, the model will appear in the **Public Models** tab of the **AI Projects** section.
#### Using Public Models
To use a public model:
1. Open the **Public Models** tab in the **AI Projects** section.
2. Click **Add** next to the model you want to use.
3. The model will then appear under **Biodock AI Models** in the **Analysis** section.
> Note: You need to scroll down in the Analysis section to find the **Biodock AI Models** category.
Intestinal model here is the public model
# Results dashboard overview
Every analysis job exports directly to the Results Dashboard, an interactive data view. To open the Results Dashboard for a job, go to **AI Analysis**, and click the completed (and successful) result name.
### Overview
The Results Dashboard allows you to access the content of the segmentation jobs you have ran containing tools to review, export, and graph the analysis results, organizing your populations and comparisons in several ways.
The Results Dashboard is organized into several widgets, which help you to evaluate and compare/contrast results.
**Top-level widget** - this contains Job information, Group, Filter, and Actions columns.
1. **Job info** has information related to this particular result. It includes the AI module and parameters used to generate the result.
2. **Group** - this shows you the treatment groups present in the analysis file. Next to each treatment group inside the parenthesis, you will see the number of images present in the group. You can also click and unclick to view the results corresponding to each treatment group.
3. **Filter** ([learn more](/ai-analysis/filters-like-flow-cytometry)) - this shows the population tree and allows users to view gated populations created by gating tools on Graphing window.
4. **Actions** allow you to download the results spreadsheet and masks in npz format and view the parameters used to run the analysis.
**Segmentation data** **widget** - this contains Graphing window on the left and an Image Viewer on the right, and on the bottom, it shows quantitative data for the selected object from the Image viewer and Graphing window.
1. **Graphing window** - allows you to graph data points in scatter plot and histogram formats.
**(1a)** Below you can change X and Y axes on the scatter plot and X-axis on the histogram. We also display the ability to rename channels for images with color/fluorescent expression. **(1b)** On the scatter plot, you can also click on any object to view its quantitative metrics. Here we selected one cell on the scatter plot indicated in red.
2. **Create filters** [(learn more)](/ai-analysis/filters-like-flow-cytometry) - this allows users to generate gated populations using several types of gating tools.
3. **Image Viewer** [(learn more)](broken://pages/MWANlQZPTYOpLbJK6siC) - this is an interactive viewer that shows the images with outlines around objects (cells, tissue regions, cell types, etc.) and allows you to click into and edit objects (see [Editing results](/ai-analysis/editing-objects-qc)).
**Comparison data widget -** this contains bar graphs with standard deviation and allows you to compare data between images and treatment groups. You can plot any metrics extracted during analysis depending on the AI model, including object count, area, morphological metrics, fluorescent intensity, etc. To select the metrics to be plotted on the Y axis, click on the dropdown menu.
# Download results and reports
You can download nearly everything Biodock generates for you in the Results Dashboard.
#### Downloading out an aggregate report
You should download the aggregate report when you want to compare across images or experimental groups on a mean/std. dev basis.
Click on the **Download data** dropdown on the top right of the Results Dashboard. This will have a dropdown - select **Download aggregate data**. This will process, and then ping you with a notification shortly with a download link for a CSV file that contains a report with one line per group as well as per image.
#### Downloading out a per-object CSV
You should download the per-object CSV when you need object-by-object data, either to import into another program, do downstream analysis, or look at specific objects.
Click on the **Download data** dropdown on the top right of the Results Dashboard. This will have a dropdown - select **Generate CSV**. This will process, and then ping you with a notification shortly with a download link for a CSV file that contains extracted metrics for every object within the whole run, represented by each row.
*These CSVs can get very large, and take several minutes to run if you have hundreds of thousands or millions of objects (one row per object). Consider downloading the aggregate report instead.*
#### Downloading plots
The scatter, histogram, and aggregate plot can all be downloaded by hovering over and hitting the camera icon. This will download a .png.
#### Downloading out AI-generated object masks
You may want to download out raw masks to create your own overlay visualizations, generate custom metrics, or do any sort of miscellaneous processing.
Click on the **Download data** dropdown on the Top-level widget in the Results Dashboard. This will have a dropdown - select **Generate masks data**. This mask data will be downloaded in a compact zip archive containing JSON files that can be parsed with scripts and used for further computational analysis. The format of the archive is as follows:
```
|- index.json # pipeline run meta information
|- {image_id}_objects.json # for each image in the run
```
{% code title="image.json" %}
```json
{
"resultId": "AAAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAA",
"dateRun": "2022-08-08T19:03:06.458Z",
"classData": {
"Cyst": {
"name": "Cyst",
"type": "Instance"
}
}
}
```
{% endcode %}
#### Processing Biodock output masks
Biodock output masks are encoded in a COCO-style RLE format. You can use cocoapi tools in Python, Lua, or Matlab to parse them easily. Some basic examples are below in Python - check out the [Github repo](https://github.com/cocodataset/cocoapi) for further documentation or for other languages
#### Installing pycocotools
```shell
pip install pycocotools # or conda install -c conda-forge pycocotools
```
#### Parsing Biodock output masks for an image into an array of binary masks
```python
import base64
import json
import pycocotools.mask as maskutil
with open('AAA_objects.json') as maskfile:
mask_results = json.load(maskfile)
first_image_objects_encoded = mask_results["objects"]
first_image_masks = []
for obj in first_image_objects_encoded.values():
encoded_mask = obj["rle"]
encoded_mask["counts"] = base64.b64decode(encoded_mask["counts"])
first_image_masks.append(maskutil.decode(encoded_mask))
```
You can then convert these binary masks into polygons using a number of different libraries, and then, for example into FIJI using the [ROI importer](https://imagej.nih.gov/ij/plugins/roi-importer.html)
#### Downloading high-resolution overlay images
If you are interested in downloading high-resolution images with overlaid masks, you can click **Download** buttonin the Image Viewer window in Results Dashboard.
# Correcting results to improve your model
## Motivation
As you acquire different types of images, from different cell lines, procedures, or other variation, you may notice that for some new images, your results may not be 100% accurate. This is often the case when your initial training set didn't capture the variation seen within the images that you are running.
Biodock provides an easy way to take these results, import them as labels into your project, and only correct labels that may be missing or incorrect to improve performance in your model.
## Importing labels
You can find the Add to AI Project button right above the image viewer. Click the button to start importing predictions for this option.
A modal will appear. If you've changed your class names, you may need to respecify which classes will be mapped to which labeling classes. In most cases, you'll want to import them back to the same project.
## Correcting and retraining
Once you click the blue button in the bottom right, the modal will close, and you'll soon get a notification in platform that the import succeeded. If you go back to the original project, you'll be able to open the imported image:
You should correct one or more of these imported tiles from this image, especially focusing on areas where the model underperformed. Make sure that every object is labeled correctly in the tile. Then you can mark these as fully-labeled by clicking on the tile checkbox.
Finally, once you've imported enough images and corrected more tiles, you should train another version! The new version should perform much better on images that look like the ones you corrected.
# Editing objects (QC)
Occasionally, you may identify errors in the detected objects from Biodock's AI modules. You can rectify these errors by using the object editor, accessed by clicking the **Edit objects** button on the Results Dashboard.
> Note: some AI modules do not support editing objects. If the Results Dashboard contains the **Edit objects** button, then your AI module does support editing objects.
The object editor displays the image on the right with all existing outlines. At the top, you can toggle displaying existing object outlines and adjusting the image brightness and contrast.
### Pending vs committed edits
As you make edits, the changes you make are saved to allow you to continue working at a later time if necessary. New edits are saved in the **Pending** state, meaning that the changes have not yet been committed to the computed data we display on the Results Dashboard.
In order to have your edits reflected in the data displayed on the Results Dashboard, you will need to **apply** your edits. Clicking the **Apply edits** button will start recomputing the results data in the background. After this process completes (usually takes less than 5 minutes), the data and image viewer on the Results Dashboard will reflect your changes, and the edits you made will be moved to the **Committed** state.
### Add a new object
In order to add a new object, you need to be in Object Editor mode and click **New object** button.
Then you will see the following buttons: **Finish creating, Add and Subtract.** Once you are in the new object mode, you will be able to add or subtract objects. The color of the newly created masks will be in Green (Add) or Red (Subtract) colors depending on whether you choose Add or Subtract tools. If you are finished adding a new object you can click **Finish creating**, or **Stop creating**.
*Left: Add mode. Right: Subtract mode.*
This is how objects will look like after finishing the edits. Left: Once you complete editing. Right: once you click Finish creating The objects turns green.
### **Edit an object**
You can also edit an existing object. Once you are in Object Editor mode, you can select an object that you want to edit by simply selecting the object.
Once the object is selected you need to click **Edit object area** to initiate the editing.
After you click **Edit object area**, you can edit the mask. Green and red outlines appear depending on if you are using **Add** or **Subtract**, respectively.
After editing one object, you need to click Finish editing to complete the changes.
You can also delete the object by clicking **Delete object.**
Once you finish your edits, and click Apply edits, Biodock will recalculate objects and you will see the message at the bottom of the results dashboard.
# Filters (like flow cytometry)
Creating gated populations can help you create filtered populations to answer things like:
* How many large (area >1SD above the mean) and round (eccentricity > 1SD above the mean) organoids do I have? What percent are they? How does their average intensity compare to the broader population?
* What's the average size and count of double positive cells for CD8 and CD4?
There are multiple tools you can use to create gated populations. Simply click on the Create filter to see these tools.
#### **Manual Gating**
You can gate populations manually by using the Rectangle, Oval, or Freeform tools.
#### **Statistical Gating**
The ***By Statistics*** gating tool allows you to gate populations based on standard deviation or threshold.
When you select ***By Statistics***, a new window will appear where you can toggle between ***Standard Deviation*** and ***Simple Threshold*** gating.
For ***Standard Deviation*** gating, you can specify how many standard deviations (SD) from the mean you want to use. For the SD value, you need to specify the desired settings for how the SD value should be applied. Choose the less than (<) or greater than (>) sign and specify either above or below the mean.
Lastly, you need to define what metrics (channel, cell, nuclear size, etc.) to use for gating.
For ***Simple Threshold*** gating, you need to specify the threshold and decide if you want the population Below or Above the threshold. Lastly, you need to define what metrics (channel, cell, nuclear size, etc.) to use for gating.
#### **By Image**
This gating tool is used to select a specific image(s) you want to look at.
## Overlaying filters on the scatter plot
{% hint style="info" %}
Currently, Biodock does not support overlays for scatterplots with over 60,000 objects.
{% endhint %}
### **Selecting a color to overlay the population**
For every population you created, you can overlay them with a specific color. Hover over **three dots (...)** on the right side of the population and click on **Overlay** and select the color.
After you select a specific color, the gated population appears colored in the graph.
### Viewing color overlaid population on Image Viewer
Once you created a population with gating tools (refer to [creating populations with filters](/ai-analysis/filters-like-flow-cytometry)), and overlay them with a specific color, the image viewer will also reflect this color overlay.
In the image below, the image viewer shows the red outlines for the GFP+ population created in the gating tool.
# Biodock Platform Script Guidelines
### Overview
This guide provides instructions for running scripts on the Biodock platform via the new "Scripts" tab. Follow these steps to ensure your script functions correctly within the platform's environment.
### 1. Convert the Notebook to a Python Script
Convert your Jupyter notebook (`.ipynb`) to a single Python script (`.py`). Ensure that all necessary code and dependencies are included in the script file.
### 2. Handling Input Paths for Images and JSON Files
Biodock handles file management before invoking your script. All images and GeoJSON files will exist in the same filesystem as your script, so you do not need to download anything manually.
Modify your script to accept file paths via command-line arguments:
```
import sys
import json
input_items_path = sys.argv[1] # Path to input JSON file list
output_dir = sys.argv[2] # Directory for output files
with open(input_items_path, "r") as f:
input_items = json.load(f)
print(f"Loaded {len(input_items)} input items.")
# Example: Accessing the first image and its corresponding GeoJSON file
json_file_path = input_items[0]["geojson_path"]
image_path = input_items[0]["image_path"]
```
### 3. Writing Output Files
All output files should be written to the `output_dir`. Any file in this directory will be automatically uploaded to the cloud and made accessible to the user.
Example:
```
import os
example_output_path = os.path.join(output_dir, "example_output.txt")
with open(example_output_path, "w") as f:
f.write("This is an example output file.")
```
### 4. Handling Matplotlib Plots
Replace all `plt.show()` calls with `plt.savefig()` to ensure that plots are saved instead of being displayed interactively. Save the files in `output_dir`.
Example:
```
import matplotlib.pyplot as plt
plt.savefig(os.path.join(output_dir, f"{layer_name}_Thickness_by_Adjusted_Angle.png"))
```
### 5. Remove Unnecessary Imports
Remove any imports related to Google Cloud or Google Colab, as these are not needed within the Biodock platform environment.
### 6. Specify Dependencies in `requirements.txt`
Create a `requirements.txt` file listing all the dependencies required for your script. Before execution, Biodock will create a new Python environment and install these dependencies.
Example `requirements.txt`:
```
matplotlib
numpy
pandas
shapely
tifffile
scikit-image
```
### 7. Uploading and Running Your Script
Once your script and `requirements.txt` file are ready, follow these steps:
1. Place the `.py` file and `requirements.txt` in a single folder.
2. On the Biodock platform, navigate to the **Scripts** tab.
3. Click **Upload Script** > **Browse Folders** and upload your script folder.
4. Once uploaded, go to the **Runs** sub-tab.
5. Click **Run Script** and specify the script and analysis job.
6. After execution, download the results, including:
* Script outputs
* Console output (print statements)
* Error messages (if any)
Following these guidelines ensures that your script runs efficiently on the Biodock platform. If you have any questions, contact Biodock support for further assistance.
# Uploading images
{% hint style="info" %}
If you'd like to connect data from S3, you can import data via our [AWS S3 integration](/files/aws-s3-integration)
{% endhint %}
In order to analyze your images, you first need to upload them to the Biodock platform. Each user has their own filesystem where their data is securely and privately stored.
You can upload files to Biodock by navigating to **Files** from the left sidebar and clicking the **Upload files** button. This will open the upload modal where you can select files for upload
#### Uploading files from your computer
By selecting the **browse files** link, you will be prompted to select files on your computer to upload to Biodock. You can select as many files as you'd like to upload.
#### Uploading folders from your computer
By selecting the **browse folders** link, you will be prompted to select *folders* on your computer to upload to Biodock. This will upload all of the files in the folder, even files in nested subfolders! The structure of uploaded folders will be preserved after you import them into Biodock.
For example, if you upload the following folder with the following structure:
* `3/22/2022 Scans`
* `test-image1.tif`
* `Control`
* `control-image1.tif`
* `control-image2.tif`
* `control-image3.tif`
* `Experiment`
* `experiment-image1.tif`
* `experiment-image2.tif`
* `experiment-image3.tif`
We would create folders called `3/22/2022 Scans`, `Control` and `Experiment`, with all of the files in the correct locations!
You will see a preview of the folder structure in Biodock after you select a folder to upload.
#### Uploading files from other sources
The upload modal also supports uploading from other storage options, such as Google Drive, Box, Dropbox or OneDrive. By clicking on the icons for these services, you can authenticate with their platforms and select files from their platforms to be imported into Biodock.
### Uploading to a new folder
By default, your uploaded files will be placed in the folder you had open when you clicked **Upload files**. (Most of the time, this will be the top level **My Files** folder.)
Sometimes, however, you may want to upload files to a separate folder. By checking the **Create folder** box in the upload modal, your files will be placed into a new folder with the name you specify after they have been uploaded and processed by our servers.
# AWS S3 integration
Biodock supports integration with existing S3 cloud datastores
## Generating a limited S3 read user and keys
{% hint style="info" %}
You can skip this step and go down to if you already have AWS Access Key ID and Secret Key ID for the S3 buckets you wish to integrate
{% endhint %}
Log into the AWS console and navigate to the **IAM Dashboard** → **Users***.* Then, click **Add User.**
From the Add User screen, pick any username, like *biodock-s3-access,* and check **Programmatic access.**
On the next screen, select **Attach existing policies directly** and search for S3. From the results, choose AmazonS3ReadOnlyAccess.
*Note: If you want to restrict access to a single bucket, you will need to create a custom policy and attach it to the user. An example minimum policy is shown at the bottom of this page.*
Once you have created your user by clicking next through the screens, make sure to copy this user's AWS Key ID & Secret Key ID for the next step.
## Connecting your S3 Bucket with Biodock
Navigate to the **Files** page on the left sidebar and select the **Amazon S3** option --
Provide your AWS Access Key & Secret. Your keys are AES-256 encrypted and stored but you can disconnect at any time using the **Disconnect** button on the top right, which will purge your keys from Biodock.
You can **search** only by prefix in the S3 file explorer (this restriction is created by AWS). Type in the prefix for the desired files or folders you want to import into Biodock and click **Import to Biodock** and then choose the location in **My Files** where you would like to import the image.
You can then navigate to **My Files** and start using your imported files in Biodock. See [Running AI Analysis on Images](broken://pages/bdEIYXiQz4t5Hwt0u5T8).
### Minimum working policy
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:ListBucket"
],
"Resource": [
"arn:aws:s3:::test-examples-biodock", // Replace with your bucket
"arn:aws:s3:::test-examples-biodock/*" // Replace with your bucket
]
},
{
"Sid": "VisualEditor1",
"Effect": "Allow",
"Action": "s3:ListAllMyBuckets",
"Resource": "*"
}
]
}
```
# View and manage data
From the Biodock files screen, you can perform various operations on your files.
###
###
###
###
# Viewing images
After you upload your images, you can preview them by double clicking. You can also preview by right clicking an image (or by clicking the `...` button in the top right corner) and selecting **Open**.
Doing this will open the image viewer, which supports:
* zooming (even on very large images!)
* adjusting brightness and contrast
* toggling channels
* selecting which image channel should be represented by a given color (eg, for images with 8+ channels)
# File details and download
### View details
You can view additional details for a file or folder by either:
* Right clicking on the file or folder and selecting **View details**
* Clicking the `i` (info) button in the action bar.
This will open the file details sidebar which contains additional file information such as file size and dimensions, along with a higher resolution thumbnail of the image.
### Download
You can download an image by right clicking a file or folder and selecting **Download.** This will download the file or a zip of the contents of the folder.
# Copy, cut, move
### Copy and paste
You can duplicate files by either:
* Right clicking a file or folder and selecting **Make a copy**
* Selecting a file or folder and pressing `Command+C` (`Control+C` if you're on Windows), then navigating to where you want to paste your files, and pressing `Command+P` (`Control+P`).
* When you copy the files, you should see a small popup that looks like this:
* 
### Cut and paste
You can also cut and paste files by pressing `Command+X` (`Control+X` if you're on Windows), then navigating to where you want to paste your files, and pressing `Command+P` (`Control+P`).
Note that cutting will remove the files from the original location and move them to the new location, while copying will preserve the files in the original location and increase your storage usage.
### Move
You can move files in your file system by either clicking and dragging, or right clicking and selecting the **Move** option.
This will open a modal where you can select the new destination for the selected files.
# Sharing data
To share files with other accounts in Biodock, select the files you wish to share and click **Share**.
You should see a list of people within the same organization of your Biodock account or none if there aren't any other accounts. You can type in the account email for an external account you wish to share with and click **Share to external email**.
The shared account now has access to the file. The shared files will appear in the **Shared with me** section, underneath **My Files**.
# Merging channels
Biodock exposes a feature for merging single channel image files into 3D multichannel images. If you have single channel images for which you want to run Nuclear Cell Segmentation analysis, you will have to merge your single channel images into multichannel images.
In the filesystem make a selection of image files that need to be merged into 1 or more multichannel images. Click the ellipsis options menu in the top right or right click optionally. The merge option should appear.
### Merging through example
In this example, we are going to merge 5 images into a set of two multichannel images. One set is 2 files with the prefix of *Hepatocytec* and another set is 3 files with a prefix of *test.*
In the modal that appears, the regex input determines the naming conventions of your resulting 3D merged files and which channels get applied to which file. The regex requires two capture groups - one to identify the groupings of files that get merged together and a second group specifying the changing channels within each group.
In this example, a regex of '*(Hepatocytec|test)(1|2|3)*' splits the files into 2 groups.
The first capture group of *Hepatocytec|test s*plits the 2 files with the prefix of *'Hepatocytec'* into one group and the the 3 files with the prefix of *test* into another. The result will be two 3D files of *Hepatocyec* and *test.*
The second capture group of *1|2|3* specifies the changing channels between files within each group. The result is the merge of *test1, test2, test3* into one single file *test* with channel 1 applied to *test1*, channel 2 to *test2* and channel 3 to *test3.* In the *Hepatocytec* group - we apply channel 1 to *Hepatocytec1* and channel 2 to *Hepatocytec3*.
By default, the channel regex group applies the channel ordering in alphanumeric ascending order, i.e - channel 1 gets applied to *Hepatocytec1* and *test1,* channel 2 to *Hepatocytec3* and *test2., etc...*
You can reverse the order of the channel application by checking the box to reverse order in channel settings -
A notification will appear that your merge is in progress. Once Biodock's system completes the merge, a folder will be created in your filesystem in the same location where you made your selection of files. This folder will contain your merged 3D multichannel image files, which in our example are *Heptocytec.tif* and *test.tif*.
Below is the viewer of the merged 3D file *test.tif.* The image has 3 channels, comprising of the 3 files captured over 3 different channels which have been merged as specified by the settings we had input earlier on this page.
#### Channel appears first in file name
The merge regex by default sets the second capture group to identify channel values. With advanced settings, you can flip the capture group ordering so files that have channel appearing first can be matched with the first regex group.
Regex can become complex but it is flexible enough to support the naming conventions and desired grouping conventions of your image files. See[ Examples](/files/view-and-manage-data/merging-channels) for help on specifying the merge settings to merge your single channel images.
## Examples
1\) Files -
* *ControlMAP2X1.tif*
* *ControlNOMAP1X3.tif*
* *ControlSOMETHINGELSEX6.tif*
* *ControlOTHERx8.tif*
The regex to merge these files into a single file Control.tif -
**(Control).+(x\[1-9])** - matches the prefix common to all files first -- Control. Then matches any character any number of times -- until the 2nd group match of 'x followed by a number between 1 & 9.
# Supported image types
## Supported file formats
Our filesystem supports any file format supported by Bioformats (see limitations below). You can see their supported formats [here](https://docs.openmicroscopy.org/bio-formats/6.8.1/supported-formats.html).
### Most battle-tested formats
Some formats have been used and tested more extensively on Biodock. If you can export files in multiple formats, you should use these.
* .tiff/.tif
* .svs
* .czi (with limitations below)
* .lif (with limitations below)
* .png
* .jpg/.jpeg
* ome.tiff
* mrxs (see how to upload below)
* vsi (see how to upload below)
### Special format uploads: mrxs and vsi
MRXS and VSI files are complex files that need multiple accompanying folders and files in order to be appropriately opened in Biodock and other software.
See below how these files needs to be structured before you upload them to Biodock.
MRXS format set up
VSI format set up
Once you have these files set up correctly, you can upload them to Biodock using "Browse folders"
Select the top level file and click upload
Confirm the file format is correct. In this example this is one VSI file
Processing large images takes time, so please give few minutes before it is finished. The upload starts off as yellow progress bar, when the progress bar turns blue, you can close the window.
Yellow progress bar
Blue progress bar
## General limitations
**Time series**
Biodock does not support time series data within a single file, time series traces on the Dashboard, or tracking objects between timepoints. If you would like to analyze on time-series data, you can separate each time point into it's own folder. This will allow you to compare metrics across time points on the dashboard.
**3D data**
Biodock only supports training and analysis on 2D (but multichannel supported) images. This means that Biodock does not yet support volumetric metrics. If you have 3D images, you can currently:
* Use max projection images
* Pick z stacks to do analysis
* Run training/analysis across each of your z-dimension images
# Overview
Biodock provides a public REST API so that users can invoke actions on Biodock through simple web requests. This allows users to integrate an AI analysis built on Biodock into scripts and programs.
{% hint style="info" %}
Biodock's public API is in beta, meaning that resources may change.
Also note that **creating** an AI model, which is a highly visual process in the labeler, cannot be done through our API.
{% endhint %}
Any action that is invoked through the API will also be tracked in our dashboard. For example, any files uploaded through the API will be visible in the Biodock Filesystem, and any Analysis Jobs submitted through the API will be visible on the results page.
### Example use cases for our API
* A script that automatically analyzes cell culture images acquired, three times a day, and uploads results to a cloud server.
* A sync tool that uploads data to one place (Biodock) from multiple imagers.
* A continuously running alarm that runs quality control on samples and sends an alert when quality control fails.
* Integrate Biodock into an internal tool, allowing users to submit files for analysis from an existing dashboard.
# Authentication
To authenticate with the public API, you must first [generate an API key](https://app.biodock.ai/settings/api). You can generate an API key by going to Settings -> API and pressing the Generate button.
**IMPORTANT:** Your API keys grant access to your data, so please keep them secure.
It is highly recommended you also turn on copyable ids. You can do this by ensuring the checkbox is enabled.
Once you have an API key, you can verify it is working using the following endpoint.
## Verify API key
`GET` `https://app.biodock.ai/api/external/check`
#### Headers
| Name | Type | Description |
| ------------------------------------------- | ------ | ----------- |
| X-API-KEY\* | String | API key. |
{% tabs %}
{% tab title="200: OK Request was processed successfully" %}
```javascript
{
user: "auth0|1234567890",
email: "michael@biodock.ai",
messsage: "API key is valid."
}
```
{% endtab %}
{% endtabs %}
### Sample Usage
```python
import requests
API_KEY = "" # Replace with your api key
URL = "https://app.biodock.ai/api/external/check"
headers = {"X-API-KEY": API_KEY, "Content-Type": "application/json"}
response = requests.get(URL, headers=headers)
print(response.text)
```
# Examples
### Upload and analyze files from your local machine
In this scenario, you want to run an analysis job consisting solely of files which exist on your local machine. One way to do this would be to upload each file, then submit an analysis job with all of the file ids.
```python
import requests
import os
LOCAL_FILES = [""] # Replace with your file paths, change list size as necessary
API_KEY = "" # Replace with your api key
DESIRED_FOLDER = "" # Replace with your desired folder name
PIPELINE_ID = "" # Replace with your pipeline id
UPLOAD_URL = "https://app.biodock.ai/api/external/filesystem-items/upload-file"
ANALYSIS_URL = "https://app.biodock.ai/api/external/analysis-jobs"
# Upload files
biodock_file_ids = []
for my_file in LOCAL_FILES:
with open(my_file, "rb") as file_to_upload:
data = {
"fileName": os.path.basename(my_file),
"destinationFolder": DESIRED_FOLDER
}
headers = {"X-API-KEY": API_KEY}
files = {"upload": file_to_upload}
response = requests.post(UPLOAD_URL, data=data, headers=headers, files=files)
print(response.text)
biodock_file_ids.append(response.json()["id"])
# Submit analysis job
submit_headers = {"X-API-KEY": API_KEY, "Content-Type": "application/json"}
data = {"filesystemIds": biodock_file_ids, "pipelineId": PIPELINE_ID}
response = requests.post(ANALYSIS_URL, json=data, headers=submit_headers)
print(response.text)
```
### Upload and analyze files from your local machine and the Biodock Filesystem
In this scenario you have an existing folder with files on the Biodock Filesystem. You also have files on your local machine. You would like add the local files to the remote folder, and run analysis on all the files.
```python
import requests
import os
LOCAL_FILES = [""] # Replace with your file paths, change list size as neccesary
API_KEY = "" # Replace with your api key
BIODOCK_FOLDER_NAME = "" # Replace with your existing folder name
BIODOCK_FOLDER_ID = "" # Replace with your existing folder id
PIPELINE_ID = "" # Replace with your pipeline id
UPLOAD_URL = "https://app.biodock.ai/api/external/filesystem-items/upload-file"
ANALYSIS_URL = "https://app.biodock.ai/api/external/analysis-jobs"
# Upload files
for my_file in LOCAL_FILES:
with open(my_file, "rb") as file_to_upload:
data = {
"fileName": os.path.basename(my_file),
"destinationFolder": BIODOCK_FOLDER_NAME
}
headers = {"X-API-KEY": API_KEY}
files = {"upload": file_to_upload}
response = requests.post(UPLOAD_URL, data=data, headers=headers, files=files)
print(response.text)
# Submit analysis job
submit_headers = {"X-API-KEY": API_KEY, "Content-Type": "application/json"}
data = {"filesystemIds": [BIODOCK_FOLDER_ID], "pipelineId": PIPELINE_ID}
response = requests.post(ANALYSIS_URL, json=data, headers=headers)
print(response.text)
```
###
# Resources
Files: Contains information and examples for uploading files to the Biodock Filesystem
Analysis Jobs: Contains information and examples for submitting and viewing analysis jobs
Pipelines: Contains information and examples for viewing pipelines.
# Files
{% hint style="info" %}
The public API supports uploading files up to 2 GB. If you would like to upload files larger than this, they must be uploaded using the website.
{% endhint %}
To upload a file, use the following endpoint:
## Upload file
`POST` `https://app.biodock.ai/api/external/filesystem-items/upload-file`
#### Headers
| Name | Type | Description |
| ------------------------------------------- | ------ | ----------- |
| X-API-KEY\* | String | API key. |
#### Request Body
| Name | Type | Description |
| ------------------------------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------- |
| fileName\* | String | Desired name of file in the Biodock filesystem. |
| destinationFolder | String | Desired parent folder of file in the Biodock filesystem. Will create folders if they do not exist. Defaults to the root folder. |
| upload\* | file | File to upload. |
{% tabs %}
{% tab title="200: OK " %}
```javascript
{
id: "0123456789",
__t: "File"
}
```
{% endtab %}
{% endtabs %}
To view items in the Biodock filesystem, use the following endpoint:
## List filesystem items
`GET` `https://app.biodock.ai/api/external/filesystem-items`
#### Query Parameters
| Name | Type | Description |
| ------------- | ------ | ---------------------------------------------- |
| limit | Number | Maximum number of results to show. |
| startingAfter | String | Pagination cursor id. |
| folderId | String | Parent folder id. Will default to root folder. |
#### Headers
| Name | Type | Description |
| ------------------------------------------- | ------ | ----------- |
| X-API-KEY\* | String | API key. |
{% tabs %}
{% tab title="200: OK " %}
```javascript
{
results: [{
id: "0123456789",
name: "my_file.png",
createdAt: "2000-01-01T00:00:00.001Z",
__t: "File"
},
{
id: "1234567890",
name: "my_folder",
createdAt: "2000-01-01T00:00:00.001Z",
__t: "Folder"
}],
count: 2
}
```
{% endtab %}
{% endtabs %}
### Sample Usage
Upload a file
```python
import requests
API_KEY = "" # Replace with your api key
FILE_TO_UPLOAD = "" # Replace with your file path
DESIRED_FILENAME = "" # Replace with your desired filename
DESIRED_FOLDER = "" # Replace with your desired folder
URL = "https://app.biodock.ai/api/external/filesystem-items/upload-file"
with open(FILE_TO_UPLOAD, "rb") as file_to_upload:
data = {"fileName": DESIRED_FILENAME, "destinationFolder": DESIRED_FOLDER}
headers = {"X-API-KEY": API_KEY}
files = {"upload": file_to_upload}
response = requests.post(URL, data=data, headers=headers, files=files)
print(response.text)
```
List filesystem items in the root folder
```python
import requests
API_KEY = "" # Replace with your api key
URL = "https://app.biodock.ai/api/external/filesystem-items"
headers = {"X-API-KEY": API_KEY, "Content-Type": "application/json"}
response = requests.get(URL, headers=headers)
print(response.text)
```
List filesystem items in a different folder
```python
import requests
API_KEY = "" # Replace with your api key
FOLDER_ID = "" # Replace with your folder id
URL = f"https://app.biodock.ai/api/external/filesystem-items?folderId={FOLDER_ID}"
headers = {"X-API-KEY": API_KEY, "Content-Type": "application/json"}
response = requests.get(URL, headers=headers)
print(response.text)
```
# Analysis Jobs
{% hint style="info" %}
The public API supports submitting analysis jobs. To submit an analysis job, you must have already uploaded the files you wish to analyze to the Biodock filesystem, and you must have a published analysis pipeline.
{% endhint %}
{% hint style="info" %}
Pipelines can only be created and published through the website, NOT the API.
{% endhint %}
{% hint style="info" %}
Only user-created pipelines are supported through the public API, NOT Biodock pipelines.
{% endhint %}
To submit an analysis job, use the following endpoint:
## Submit analysis job
`POST` `https://app.biodock.ai/api/external/analysis-jobs`
#### Headers
| Name | Type | Description |
| ------------------------------------------- | ------ | ----------- |
| X-API-KEY\* | String | API key. |
#### Request Body
| Name | Type | Description |
| ----------------------------------------------- | ------------- | ----------------------------- |
| pipelineId\* | String | Pipeline to use for analysis. |
| filesystemIds\* | List\[String] | Filesystem items to analyze. |
| name | String | Name of the job. |
{% tabs %}
{% tab title="200: OK " %}
```javascript
{
id: "0123456789",
percentageCompleted: 0,
status: "PENDING"
}
```
{% endtab %}
{% endtabs %}
You can view progress for your analysis job using the following endpoint:
## Fetch analysis job
`GET` `https://app.biodock.ai/api/external/analysis-jobs/{id}`
#### Path Parameters
| Name | Type | Description |
| ------------------------------------ | ------ | ----------- |
| id\* | String | |
#### Headers
| Name | Type | Description |
| ------------------------------------------- | ------ | ----------- |
| X-API-KEY\* | String | API key. |
{% tabs %}
{% tab title="200: OK " %}
```javascript
{
id: "0123456789",
percentageCompleted: 100,
status: "SUCCEEDED",
objectsDataCSVUrl: "https://...",
aggregateDataCSVUrl: "https://..."
}
```
{% endtab %}
{% endtabs %}
You can view progress for all your analysis jobs using the following endpoint:
## List analysis jobs
`GET` `https://app.biodock.ai/api/external/analysis-jobs`
#### Query Parameters
| Name | Type | Description |
| ------------- | ------ | ---------------------------------- |
| limit | Number | Maximum number of results to show. |
| startingAfter | String | Pagination cursor id. |
#### Headers
| Name | Type | Description |
| ------------------------------------------- | ------ | ----------- |
| X-API-KEY\* | String | API key. |
{% tabs %}
{% tab title="200: OK " %}
```javascript
{
results: [{
id: "0123456789",
percentageCompleted: 100,
status: "SUCCEEDED",
objectsDataCSVUrl: "https://...",
aggregateDataCSVUrl: "https://..."
}],
count: 1
}
```
{% endtab %}
{% endtabs %}
Masks data is not generated by default during an analysis job. If you would like to obtain the masks data for your analysis job, you must first generate the masks data with the following endpoint:
## Submit download masks job
`POST` `https://app.biodock.ai/api/external/analysis-jobs/{id}/download-masks`
#### Path Parameters
| Name | Type | Description |
| ------------------------------------ | ------ | ----------- |
| id\* | String | |
#### Headers
| Name | Type | Description |
| ------------------------------------------- | ------ | ----------- |
| X-API-KEY\* | String | API key. |
{% tabs %}
{% tab title="200: OK " %}
```javascript
{
percentageCompleted: 0,
status: "SUBMITTED"
}
```
{% endtab %}
{% endtabs %}
Once the masks generation has completed, the download link to the masks will be available. You can view the progress and obtain the download link with the following endpoint:
## Fetch download masks job
`GET` `https://app.biodock.ai/api/external/analysis-jobs/{id}/download-masks`
#### Path Parameters
| Name | Type | Description |
| ------------------------------------ | ------ | ----------- |
| id\* | String | |
#### Headers
| Name | Type | Description |
| ------------------------------------------- | ------ | ----------- |
| X-API-KEY\* | String | API key. |
{% tabs %}
{% tab title="200: OK " %}
```javascript
{
percentageCompleted: 100,
status: "SUCCEEDED",
masksZipUrl: "https://..."
}
```
{% endtab %}
{% endtabs %}
### Sample Usage
Submitting an analysis job
```python
import requests
API_KEY = "" # Replace with your api key
FILESYSTEM_IDS = [""] # Replace with your filesystem ids. Add to the list as neccesary
PIPELINE_ID = "" # Replace with your pipeline id
URL = "https://app.biodock.ai/api/external/analysis-jobs"
headers = {"X-API-KEY": API_KEY, "Content-Type": "application/json"}
data = {"filesystemIds": FILESYSTEM_IDS, "pipelineId": PIPELINE_ID}
response = requests.post(URL, json=data, headers=headers)
print(response.text)
```
View the progress of a specific analysis job
```python
import requests
API_KEY = "" # Replace with your api key
ANALYSIS_JOB_ID = "" # Replace with your analysis job id
URL = f"https://app.biodock.ai/api/external/analysis-jobs/{ANALYSIS_JOB_ID}"
headers = {"X-API-KEY": API_KEY, "Content-Type": "application/json"}
response = requests.get(URL, headers=headers)
print(response.text)
```
View the progress of all your analysis jobs
```python
import requests
API_KEY = "" # Replace with your api key
URL = "https://app.biodock.ai/api/external/analysis-jobs"
headers = {"X-API-KEY": API_KEY, "Content-Type": "application/json"}
response = requests.get(URL, headers=headers)
print(response.text)
```
Generate masks data for an analysis job
```python
import requests
API_KEY = "" # Replace with your api key
ANALYSIS_JOB_ID = "" # Replace with your analysis job id
URL = f"https://app.biodock.ai/api/external/analysis-jobs/{ANALYSIS_JOB_ID}/download-masks"
headers = {"X-API-KEY": API_KEY, "Content-Type": "application/json"}
response = requests.post(URL, headers=headers)
print(response.text)
```
View the progress of masks generation
```python
import requests
API_KEY = "" # Replace with your api key
ANALYSIS_JOB_ID = "" # Replace with your analysis job id
URL = f"https://app.biodock.ai/api/external/analysis-jobs/{ANALYSIS_JOB_ID}/download-masks"
headers = {"X-API-KEY": API_KEY, "Content-Type": "application/json"}
response = requests.get(URL, headers=headers)
print(response.text)
```
# Pipelines
The public API supports viewing active pipelines. To view active pipelines, use the following endpoint:
## List pipelines
`GET` `https://app.biodock.ai/api/external/pipelines`
#### Query Parameters
| Name | Type | Description |
| ------------- | ------ | ---------------------------------- |
| limit | Number | Maximum number of results to show. |
| startingAfter | String | Pagination cursor id. |
#### Headers
| Name | Type | Description |
| ------------------------------------------- | ------ | ----------- |
| X-API-KEY\* | String | API key. |
{% tabs %}
{% tab title="200: OK " %}
```javascript
{
results: [{
id: "0123456789",
description: "My first pipeline",
createdAt: "2000-01-01T00:00:00.001Z"
}],
count: 1
}
```
{% endtab %}
{% endtabs %}
### Sample Usage
View all your active pipelines
```python
import requests
API_KEY = "" # Replace with your api key
URL = "https://app.biodock.ai/api/external/pipelines"
headers = {"X-API-KEY": API_KEY, "Content-Type": "application/json"}
response = requests.get(URL, headers=headers)
print(response.text)
```
# Limitations
The public API is in beta and is being actively developed. There are some features which are available through the website which are not yet available through the API.
Currently, the only available upload mechanism is from your local device. Other upload mechanisms supported by the website such as S3 import, Google Drive, Dropbox are not available at this time.
Currently, not all file formats which can be uploaded through the website can be uploaded through the API. The current list of available file formats is:
* png
* jpg and jpeg
* tif and tiff
* svs
* ndpi
* vms
* vmu
* scn
* svslide
* bif
Note that files in other file formats can still be submitted for analysis through the API if they have already been uploaded through the website.
# Deep AI models
After creating an AI model, you should evaluate the model visually and or by looking at the statistics page.
# Evaluating Performance
Intersection over union is a way to measure the overlap between the segmentations that the model is predicting against your labels you put in.
A well performing model would exactly predict the labels you put in, and the overlap would be complete.
IoU = area of overlap / area of union (the total area of both objects together, overlapping area is only counted once)
IoU of a well performing model should be 1, a poorly performing model would be 0.
IoU is calculated at different thresholds. If 50% of the area of a predicted object and the object you labeled overlap, at 0.5 that is counted as a match, but not at 0.95.
Average precision (AP) is how accurate the model is. What proportion of the predicted objects are a match to the labels you put in, at different thresholds, averaged over all the objects in that group.
Mean over IoU is averaging the IoU scores at different thresholds.
For objects, bbox is a bounding box tightly drawn around the object, wheras mask is the actual polygon you drew and that the AI predicted.
For region or semantic classes, the average precision is determined on a per pixel basis.
# Account registration
Click 'Sign Up' on the top right of this docs page to create a new user account. **Academic** users, be sure to use your **.edu email address** so that we can make additional credits accessible to you ***at no cost***.
Sign up screen
Biodock uses the [Auth0 ](https://auth0.com/)platform for authentication and authorization. You should have received an email to verify the email address you used to sign up.
Once verified, you'll fill out a few fields about your organization and your use case, and that's it! You should see your home screen with an onboarding checklist.
**We highly recommend you follow these steps to get started.** You can also follow along using our Getting Started guide, linked below:
{% content-ref url="/pages/En6aJ8rFKulKbJDI99TW" %}
[Quickstart](/start/start-here-choose-a-tutorial)
{% endcontent-ref %}
# Change password, login, logout
## Change password
To change your password, make sure you log out of your account. Then, navigate to app.biodock.ai, and make sure you get a **Log in** screen. From there, click **Forgot your password?** and follow the instructions to reset your password.
## Logging in
Visit [**app.biodock.ai**](https://app.biodock.ai) to be redirected to the Biodock login page.
Provide your Biodock account's email address and password.
Alternatively, you can login with your Google account if you used a gmail address to create your Biodock account. Click on **Continue with Google** to be redirected to the gmail sign-in page.
## Logout
Click on the name card in your account. This will pop up a sidebar with a **Logout** button. Click it to logout
# Usage limits and team
Biodock's platform comes with analysis and storage usage limits based on the file size of the images that are stored or analyzed on your user account.
### Viewing your usage limits
In order to view your analysis and storage limits, click your name card in the top right of the screen. This will open up a sidebar that includes information about your organization and plan, as well as dials that show how much capacity you have.
### How your storage limits are computed
#### Storage limit
Storage limits are computed based on the cumulative total images that you have in your files. This means that deleting files frees up your storage space. We do not yet add your result data size to your storage, but some result data will eventually count towards your storage space.
We never count user data, logs, or files that we compute for viewing to your storage limits.
### Analysis and training limits
If you have a filesize based analysis limit:
{% content-ref url="/pages/UH4c8NbOCMDpqJIBk4v4" %}
[Filesize based limits](/user/usage-limits-and-team/filesize-based-limits)
{% endcontent-ref %}
If you have a run credits based analysis limit:
{% content-ref url="/pages/kVt2KxoOqMZcwjpONGpN" %}
[Run credits limits](/user/usage-limits-and-team/run-credits-limits)
{% endcontent-ref %}
## Team
{% hint style="info" %}
Looking to add a member to an AI project? Add them from Project Settings instead.
{% endhint %}
### Team Management
To manage your team, navigate to **Settings → Team** from the main sidebar.
Adding team members allows multiple users to share the same **Run Credits** and **Storage** allocation. However, team members do **not** automatically gain access to your projects, analysis runs, or files.
To collaborate on projects or data, you must share them manually. When sharing projects or files, your team members will be automatically suggested in the sharing and project invitation dialogs.
### Team Member Limits
Free Academic accounts can add up to **one team member**.
To add additional team members, your account must have an active paid plan. You can upgrade by purchasing **Run Credits** or **Storage** through the [**Billing**](https://docs.biodock.ai/~/revisions/p7ymXsvCfFKfKgE1SN6X/user/billing) page.
Once your account has an active paid subscription or purchase, you can invite and manage additional team members.
# Filesize based limits
{% hint style="info" %}
If you are on a plan that bills based on analysis based on run credits, this page does not apply to your organization.
{% endhint %}
#### Analysis limit
Analysis limits are computed based on the size of the images sent through any AI analysis module. This means that you only accumulate usage when you click run on the Analysis screen.
#### Training credits
You use one training credit per model that you train. If you train a pipeline with multiple models, this will consume one credit per model included.
# Run credits limits
{% hint style="info" %}
If you are on a contract that bills based on analysis based on file size, this page does not apply to your organization.
{% endhint %}
Run credits are a consumable that can be used to initiate model training and analysis on Biodock.
### **Run credit consumption for analysis**
An analysis run consumes fractional run credits based on the # of images contained in the run, and the # of AI inferences (usually crops of size 1000, 2000, etc.) in the run. See pricing table below, with graduated discounts shown.
This cost is additive, with total credits used = image credits + crop credits.
#### Credit pricing per image
| Base price | Over 1k images (60% off) | Over 5k images (80% off) |
| ---------- | ------------------------ | ------------------------ |
| 0.001 | 0.0004 | 0.0002 |
#### Credit pricing per crop
| Base price | Over 5k crops (75% off) | Over 100k crops (90% off) |
| ---------- | ----------------------- | ------------------------- |
| 0.0002 | 0.00005 | 0.00002 |
### Run credit consumption for training
Training jobs consume 0.5 run credits. If you expressly choose to add **both** region and object classes to one model (rarely the case), then training jobs consume 1 run credit.
### Tips for optimizing your credit usage
* Models trained with larger tile sizes use much fewer credits during analysis.
* Submitting many images at once, instead of one at a time, will help push more of your analysis into our discounted rates, saving credits. It's typically much cheaper to run one very large job than 10 small ones (if it is large enough).
# Free user limitations
## Archived Content for Free Users
### Overview
To help optimize platform resources and storage availability for all users, Biodock may archive older content associated with Free accounts.
Archiving allows Biodock to maintain platform performance while continuing to provide free access to the platform.
### What can be archived?
The following types of content may be archived if they have not been accessed for an extended period:
* Files
* Analysis jobs and results
* AI models
As a general guideline, content that has not been accessed for approximately **3 months** may become eligible for archiving.
> **Note**\
> Archiving policies, eligibility criteria, and retention periods may change as Biodock continues to improve platform resource management.
### Download important results before archiving
If you are using a Free account, Biodock recommends downloading any files, analysis results, or other data that you may need in the future.
Because older content may be archived after extended periods of inactivity, downloading important results ensures you maintain access to your data regardless of account status.
> **Best Practice**\
> Regularly download and store important outputs, reports, and datasets locally or in your organization's preferred storage solution.
### What happens when content is archived?
When an item is archived:
* It remains stored by Biodock.
* It is no longer available for use, viewing, or execution within the platform.
* Any workflows that depend on the archived item may be unavailable until the item is restored.
### Restoring archived content
Archived content is only eligible for restoration after the account has been converted to a paid account through the purchase of:
* Credits
* Storage
* Other eligible Biodock services
After becoming a paid user, archived content is **not restored automatically**.
To restore archived content, you must submit a restoration request to the Biodock team. Restoration requests are typically completed within **72 hours**.
> **Important**
>
> * Archived content cannot be restored while the account remains on the Free plan.
> * Purchasing credits, storage, or other Biodock services does not automatically restore archived content.
> * A restoration request must be submitted after upgrading to a paid account.
> * Restoration requests may take up to 72 hours to complete.
# Billing
{% hint style="info" %}
Biodock uses Stripe to collect your payment information. We never store, process, or even see your sensitive payment information.
{% endhint %}
### Billing and Payments
#### Adding a Payment Method
To add a payment method:
1. Navigate to **Settings → Billing**.
2. Click **Add Billing Method**.
3. You will be redirected to **Stripe**, where you can securely add a credit card or another supported payment method.
Adding a payment method allows you to purchase additional Run Credits and Storage when needed. Your payment method will only be charged when you complete a purchase.
#### Purchasing Additional Credits and Storage
Academic users can purchase additional **Run Credits** and **Storage** at any time from the **Billing** page in their account settings.
**Run Credits**
Run Credits are available through two purchase options:
* **Annual Subscription** – Renews automatically each year and offers a lower cost per credit.
* **One-Time Purchase** – A single, non-recurring purchase.
**Storage**
Additional Storage is available through an **Annual Subscription**, which renews automatically each year.
#### Subscription Renewals and Cancellations
Subscription plans renew automatically at the end of each billing period. If you do not wish to renew your subscription, please cancel it before the renewal date.
> Refunds are not available for subscription purchases.
# Academics and startups
### Academics
Creating a Biodock account is free for academic scientists, as part of our mission to support and accelerate bio R\&D with AI. Academic users can sign up at using an email from an accredited research institution (e.g., *.edu*, *.ac.uk*) and receive immediate access to 10 GB of storage and 3 run credits for AI training and AI analysis.
**Free academic credits are provided at Biodock's discretion as part of our academic support program.** Because the program is supported by Biodock's computing resources, the number of free credits, eligibility criteria, and availability may change over time based on program demand and available resources.
Run credits automatically expire after 12 months, but if you are unable to use all of them before expiration, you can reach out to us and we will extend the expiration so you keep access to your remaining credits. If you need more than the included 3 run credits or additional storage, you can purchase more at any time through the billing page.
If you are an academic but do not have a qualifying email, [reach out](/company/contact-us) to us so we can set you up with a free account!
#### Upload Limitations for Free Academic users
Free Academic accounts can upload any supported imaging file type, with a maximum file size of **250 MB per upload**.
This limit is designed to support most medium and large imaging datasets while preventing excessive resource usage. Processing large files requires significant computing resources, which are shared across AI training and analysis workloads on the platform. The upload limit helps ensure fair and reliable access for all users.
### FAQs for academic researchers
I'm an academic user - why do I have 0 analysis capacity on my account?
Our system automatically detects academic emails and assigns an academic account for those emails. If you signed up with a non-academic email (like a Gmail account) or one that our system incorrectly classifies as non-academic, your account will not automatically given an academic standing. You can [reach out](/company/contact-us) to us and once we have proof of your academic affiliation we can upgrade your account to an academic account.
Will I ever need to convert to a paid membership?
Once free credits are used, your lab must purchase additional credits via the Billing page. For large academic storage and analysis needs, we offer services at cost—the prices shown reflect this. Our goal is to support academic R\&D at minimal cost while preventing resource abuse.
What are the terms of services and privacy policy?Is my data sold or shared?
We will **never** sell or share your data, images, results, or otherwise to third parties. We will also **never** claim IP ownership over any discovery made using our platform. In some cases, we use our corpus of data as a starting point to help train more accurate models.
What limitations do I have for publishing and usage?
Please give an inline citation. See .
For academic account usage, even for usage towards a publication, your use case must be strictly noncommercial. An academic account is not appropriate for use by a for-profit business or institution in most cases. Additionally, being a nonprofit or academic does not necessarily qualify your use case if it is still primarily intended for or directed toward commercial advantage or monetary compensation. Papers that include any significant authorship from a non-academic affiliated author generally require a paid account.
## Startups
Biodock has special startup pricing for high-growth small startups that are affiliated with a top accelerator like YCombinator, IndieBio, and Alchemist and with less than 25 FTEs.
Reach out to **** to learn more.
# Contact us
We want to hear from you! Find our email channels below.
### More information
Email **** - we're happy to answer any questions over email or discuss over a quick video call.
### Technical support and feedback
Email ****
### Get a demo
Directly schedule an introductory call or demo [here](https://docs.biodock.ai/company/www.biodock.ai/contact), or reach out to ****.
# Citing Biodock
### Citation without a Biodock author
If you are publishing a paper or presentation that has used Biodock for annotation or analysis, please cite us with the following:
{% hint style="info" %}
Biodock, AI Software Platform. Biodock 2024. Available from [www.biodock.ai](http://www.biodock.ai).
{% endhint %}
Please note: Biodock's academic accounts should be used only with academic-only papers. Papers that include any significant authorship from a commercial affiliated author generally require a paid account.
### Citation with a Biodock author
In most cases, we're happy to contribute to a methods section with a Biodock author for no charge. We're just excited to contribute to the next generation of science! Reach out [here](/company/contact-us).
# Security & IP
#### **1. Your Intellectual Property Remains Yours**
All data, analyses, and results you generate within Biodock remain **your intellectual property**. We do not claim ownership over any user-generated content.
#### **2. No Data Selling or Sharing**
We **never sell, share, or transfer** customer data to third parties. Data is used only to operate the Biodock platform as intended.
#### **3. Trusted by Leading Biopharma Organizations**
Biodock is trusted by **Fortune 500 biopharma and life-science organizations**, reflecting our commitment to enterprise-grade security and compliance.
#### **4. Secure Cloud Infrastructure**
Biodock is hosted on a **secure, high-reliability cloud environment** with industry-standard security controls including network isolation, encryption, access monitoring, and resilient architecture.
#### **5. Data Encryption In Transit and At Rest**
Your data is encrypted using modern cryptographic standards while stored and while transferred between you and our platform.
#### **6. Strict Access Controls**
We enforce least-privilege access, role-based permissions, and continuous monitoring to ensure only authorized personnel can access operational systems.
#### **7. Third-Party Risk Management**
We evaluate and monitor all third-party services to ensure they meet our security and reliability requirements.
#### **8. Secure Development & Testing Practices**
Biodock follows a secure development lifecycle including code reviews, vulnerability scanning, and change control to maintain a safe and reliable platform.
#### **9. Data Retention & Deletion**
You control your data. Upon request, we securely delete data from active systems and backups according to our data lifecycle and retention policies.
#### **10. Business Continuity & Reliability**
We maintain a comprehensive Business Continuity and Disaster Recovery program that ensures platform availability and data resilience during unexpected disruptions.
For any additional questions about our security or IP practices, please reach out to us at ****.
. (AI Detect with two classes)
### What you need to start
* A registered account on Biodock (see [how to register here](/user/account-registration)), using Google Chrome (Biodock is only officially supported on Chrome)
* The images you want to train and analyze with, in a [supported format.](/files/supported-image-types)
* An idea of the type of object or objects you want to identify (ie: cells, organoids, puncta, tissue regions, etc.) on your images.
### Then, choose a tutorial
%20(1).gif?alt=media&token=abd07fb6-6bbe-4eb1-9290-cdc7293314f6)
## 2. Upload Data
Once your project is created, it's time to import your images.
**Choose from files**
Click on **Select Files.** Choose the desired files from the list. Click **Import** to add them to your project. Wait for the import to finish and finish processing your files.
## 3. Configure your project
{% hint style="info" %}
If you have images with more than 3 channels, you will need to [configure channel settings](/ai-projects/project-settings) before you can proceed. You should also do this configuration if any of your channels are too dim.
{% endhint %}
First, enter the model creation dashboard by clicking on **Create or improve AI models**. Follow the instructions to create your first size group. You'll choose a segmentation type, choose a tile size, and add your first class.
#### Choosing a tile size
Biodock creates a grid-like set of tiles for labeling and training. Box around the object to select proper tile size. It's **very important** to follow the on-screen instructions to choose your tiles size correctly. Smaller tile sizes use more [credits](/user/usage-limits-and-team/run-credits-limits).
### Overview
The labeling tab has tools on the left side, your zoomable image in the center, and a tutorial on the right. If you follow the tutorial, it will guide you step by step to a great performing AI model in most cases.
in the Image Viewer window in Results Dashboard.
# Correcting results to improve your model
## Motivation
As you acquire different types of images, from different cell lines, procedures, or other variation, you may notice that for some new images, your results may not be 100% accurate. This is often the case when your initial training set didn't capture the variation seen within the images that you are running.
Biodock provides an easy way to take these results, import them as labels into your project, and only correct labels that may be missing or incorrect to improve performance in your model.
## Importing labels
You can find the Add to AI Project button right above the image viewer. Click the button to start importing predictions for this option.
After you click **Edit object area**, you can edit the mask. Green and red outlines appear depending on if you are using **Add** or **Subtract**, respectively.
After editing one object, you need to click Finish editing to complete the changes.
You can also delete the object by clicking **Delete object.**
Once you finish your edits, and click Apply edits, Biodock will recalculate objects and you will see the message at the bottom of the results dashboard.
# Filters (like flow cytometry)
Creating gated populations can help you create filtered populations to answer things like:
* How many large (area >1SD above the mean) and round (eccentricity > 1SD above the mean) organoids do I have? What percent are they? How does their average intensity compare to the broader population?
* What's the average size and count of double positive cells for CD8 and CD4?
There are multiple tools you can use to create gated populations. Simply click on the Create filter to see these tools.
#### **Manual Gating**
You can gate populations manually by using the Rectangle, Oval, or Freeform tools.
#### **Statistical Gating**
The ***By Statistics*** gating tool allows you to gate populations based on standard deviation or threshold.
When you select ***By Statistics***, a new window will appear where you can toggle between ***Standard Deviation*** and ***Simple Threshold*** gating.
For ***Standard Deviation*** gating, you can specify how many standard deviations (SD) from the mean you want to use. For the SD value, you need to specify the desired settings for how the SD value should be applied. Choose the less than (<) or greater than (>) sign and specify either above or below the mean.
Lastly, you need to define what metrics (channel, cell, nuclear size, etc.) to use for gating.
For ***Simple Threshold*** gating, you need to specify the threshold and decide if you want the population Below or Above the threshold. Lastly, you need to define what metrics (channel, cell, nuclear size, etc.) to use for gating.
#### **By Image**
This gating tool is used to select a specific image(s) you want to look at.
## Overlaying filters on the scatter plot
{% hint style="info" %}
Currently, Biodock does not support overlays for scatterplots with over 60,000 objects.
{% endhint %}
### **Selecting a color to overlay the population**
For every population you created, you can overlay them with a specific color. Hover over **three dots (...)** on the right side of the population and click on **Overlay** and select the color.
After you select a specific color, the gated population appears colored in the graph.
### Viewing color overlaid population on Image Viewer
Once you created a population with gating tools (refer to [creating populations with filters](/ai-analysis/filters-like-flow-cytometry)), and overlay them with a specific color, the image viewer will also reflect this color overlay.
In the image below, the image viewer shows the red outlines for the GFP+ population created in the gating tool.
# Biodock Platform Script Guidelines
### Overview
This guide provides instructions for running scripts on the Biodock platform via the new "Scripts" tab. Follow these steps to ensure your script functions correctly within the platform's environment.
### 1. Convert the Notebook to a Python Script
Convert your Jupyter notebook (`.ipynb`) to a single Python script (`.py`). Ensure that all necessary code and dependencies are included in the script file.
### 2. Handling Input Paths for Images and JSON Files
Biodock handles file management before invoking your script. All images and GeoJSON files will exist in the same filesystem as your script, so you do not need to download anything manually.
Modify your script to accept file paths via command-line arguments:
```
import sys
import json
input_items_path = sys.argv[1] # Path to input JSON file list
output_dir = sys.argv[2] # Directory for output files
with open(input_items_path, "r") as f:
input_items = json.load(f)
print(f"Loaded {len(input_items)} input items.")
# Example: Accessing the first image and its corresponding GeoJSON file
json_file_path = input_items[0]["geojson_path"]
image_path = input_items[0]["image_path"]
```
### 3. Writing Output Files
All output files should be written to the `output_dir`. Any file in this directory will be automatically uploaded to the cloud and made accessible to the user.
Example:
```
import os
example_output_path = os.path.join(output_dir, "example_output.txt")
with open(example_output_path, "w") as f:
f.write("This is an example output file.")
```
### 4. Handling Matplotlib Plots
Replace all `plt.show()` calls with `plt.savefig()` to ensure that plots are saved instead of being displayed interactively. Save the files in `output_dir`.
Example:
```
import matplotlib.pyplot as plt
plt.savefig(os.path.join(output_dir, f"{layer_name}_Thickness_by_Adjusted_Angle.png"))
```
### 5. Remove Unnecessary Imports
Remove any imports related to Google Cloud or Google Colab, as these are not needed within the Biodock platform environment.
### 6. Specify Dependencies in `requirements.txt`
Create a `requirements.txt` file listing all the dependencies required for your script. Before execution, Biodock will create a new Python environment and install these dependencies.
Example `requirements.txt`:
```
matplotlib
numpy
pandas
shapely
tifffile
scikit-image
```
### 7. Uploading and Running Your Script
Once your script and `requirements.txt` file are ready, follow these steps:
1. Place the `.py` file and `requirements.txt` in a single folder.
2. On the Biodock platform, navigate to the **Scripts** tab.
3. Click **Upload Script** > **Browse Folders** and upload your script folder.
4. Once uploaded, go to the **Runs** sub-tab.
5. Click **Run Script** and specify the script and analysis job.
6. After execution, download the results, including:
* Script outputs
* Console output (print statements)
* Error messages (if any)
Following these guidelines ensures that your script runs efficiently on the Biodock platform. If you have any questions, contact Biodock support for further assistance.
# Uploading images
{% hint style="info" %}
If you'd like to connect data from S3, you can import data via our [AWS S3 integration](/files/aws-s3-integration)
{% endhint %}
In order to analyze your images, you first need to upload them to the Biodock platform. Each user has their own filesystem where their data is securely and privately stored.
You can upload files to Biodock by navigating to **Files** from the left sidebar and clicking the **Upload files** button. This will open the upload modal where you can select files for upload
#### Uploading files from your computer
By selecting the **browse files** link, you will be prompted to select files on your computer to upload to Biodock. You can select as many files as you'd like to upload.
#### Uploading folders from your computer
By selecting the **browse folders** link, you will be prompted to select *folders* on your computer to upload to Biodock. This will upload all of the files in the folder, even files in nested subfolders! The structure of uploaded folders will be preserved after you import them into Biodock.
For example, if you upload the following folder with the following structure:
* `3/22/2022 Scans`
* `test-image1.tif`
* `Control`
* `control-image1.tif`
* `control-image2.tif`
* `control-image3.tif`
* `Experiment`
* `experiment-image1.tif`
* `experiment-image2.tif`
* `experiment-image3.tif`
We would create folders called `3/22/2022 Scans`, `Control` and `Experiment`, with all of the files in the correct locations!
You will see a preview of the folder structure in Biodock after you select a folder to upload.
#### Uploading files from other sources
The upload modal also supports uploading from other storage options, such as Google Drive, Box, Dropbox or OneDrive. By clicking on the icons for these services, you can authenticate with their platforms and select files from their platforms to be imported into Biodock.
### Uploading to a new folder
By default, your uploaded files will be placed in the folder you had open when you clicked **Upload files**. (Most of the time, this will be the top level **My Files** folder.)
Sometimes, however, you may want to upload files to a separate folder. By checking the **Create folder** box in the upload modal, your files will be placed into a new folder with the name you specify after they have been uploaded and processed by our servers.
# AWS S3 integration
Biodock supports integration with existing S3 cloud datastores
## Generating a limited S3 read user and keys
{% hint style="info" %}
You can skip this step and go down to if you already have AWS Access Key ID and Secret Key ID for the S3 buckets you wish to integrate
{% endhint %}
Log into the AWS console and navigate to the **IAM Dashboard** → **Users***.* Then, click **Add User.**
From the Add User screen, pick any username, like *biodock-s3-access,* and check **Programmatic access.**
On the next screen, select **Attach existing policies directly** and search for S3. From the results, choose AmazonS3ReadOnlyAccess.
*Note: If you want to restrict access to a single bucket, you will need to create a custom policy and attach it to the user. An example minimum policy is shown at the bottom of this page.*
Once you have created your user by clicking next through the screens, make sure to copy this user's AWS Key ID & Secret Key ID for the next step.
## Connecting your S3 Bucket with Biodock
Navigate to the **Files** page on the left sidebar and select the **Amazon S3** option --
Provide your AWS Access Key & Secret. Your keys are AES-256 encrypted and stored but you can disconnect at any time using the **Disconnect** button on the top right, which will purge your keys from Biodock.
You can **search** only by prefix in the S3 file explorer (this restriction is created by AWS). Type in the prefix for the desired files or folders you want to import into Biodock and click **Import to Biodock** and then choose the location in **My Files** where you would like to import the image.
You can then navigate to **My Files** and start using your imported files in Biodock. See [Running AI Analysis on Images](broken://pages/bdEIYXiQz4t5Hwt0u5T8).
### Minimum working policy
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:ListBucket"
],
"Resource": [
"arn:aws:s3:::test-examples-biodock", // Replace with your bucket
"arn:aws:s3:::test-examples-biodock/*" // Replace with your bucket
]
},
{
"Sid": "VisualEditor1",
"Effect": "Allow",
"Action": "s3:ListAllMyBuckets",
"Resource": "*"
}
]
}
```
# View and manage data
From the Biodock files screen, you can perform various operations on your files.
###
###
###
###
# Viewing images
After you upload your images, you can preview them by double clicking. You can also preview by right clicking an image (or by clicking the `...` button in the top right corner) and selecting **Open**.
Doing this will open the image viewer, which supports:
* zooming (even on very large images!)
* adjusting brightness and contrast
* toggling channels
* selecting which image channel should be represented by a given color (eg, for images with 8+ channels)
# File details and download
### View details
You can view additional details for a file or folder by either:
* Right clicking on the file or folder and selecting **View details**
* Clicking the `i` (info) button in the action bar.
This will open the file details sidebar which contains additional file information such as file size and dimensions, along with a higher resolution thumbnail of the image.
### Download
You can download an image by right clicking a file or folder and selecting **Download.** This will download the file or a zip of the contents of the folder.
# Copy, cut, move
### Copy and paste
You can duplicate files by either:
* Right clicking a file or folder and selecting **Make a copy**
* Selecting a file or folder and pressing `Command+C` (`Control+C` if you're on Windows), then navigating to where you want to paste your files, and pressing `Command+P` (`Control+P`).
* When you copy the files, you should see a small popup that looks like this:
* 
### Cut and paste
You can also cut and paste files by pressing `Command+X` (`Control+X` if you're on Windows), then navigating to where you want to paste your files, and pressing `Command+P` (`Control+P`).
Note that cutting will remove the files from the original location and move them to the new location, while copying will preserve the files in the original location and increase your storage usage.
### Move
You can move files in your file system by either clicking and dragging, or right clicking and selecting the **Move** option.
This will open a modal where you can select the new destination for the selected files.
# Sharing data
To share files with other accounts in Biodock, select the files you wish to share and click **Share**.
You should see a list of people within the same organization of your Biodock account or none if there aren't any other accounts. You can type in the account email for an external account you wish to share with and click **Share to external email**.
The shared account now has access to the file. The shared files will appear in the **Shared with me** section, underneath **My Files**.
# Merging channels
Biodock exposes a feature for merging single channel image files into 3D multichannel images. If you have single channel images for which you want to run Nuclear Cell Segmentation analysis, you will have to merge your single channel images into multichannel images.
In the filesystem make a selection of image files that need to be merged into 1 or more multichannel images. Click the ellipsis options menu in the top right or right click optionally. The merge option should appear.
### Merging through example
In this example, we are going to merge 5 images into a set of two multichannel images. One set is 2 files with the prefix of *Hepatocytec* and another set is 3 files with a prefix of *test.*
In the modal that appears, the regex input determines the naming conventions of your resulting 3D merged files and which channels get applied to which file. The regex requires two capture groups - one to identify the groupings of files that get merged together and a second group specifying the changing channels within each group.
In this example, a regex of '*(Hepatocytec|test)(1|2|3)*' splits the files into 2 groups.
The first capture group of *Hepatocytec|test s*plits the 2 files with the prefix of *'Hepatocytec'* into one group and the the 3 files with the prefix of *test* into another. The result will be two 3D files of *Hepatocyec* and *test.*
The second capture group of *1|2|3* specifies the changing channels between files within each group. The result is the merge of *test1, test2, test3* into one single file *test* with channel 1 applied to *test1*, channel 2 to *test2* and channel 3 to *test3.* In the *Hepatocytec* group - we apply channel 1 to *Hepatocytec1* and channel 2 to *Hepatocytec3*.
By default, the channel regex group applies the channel ordering in alphanumeric ascending order, i.e - channel 1 gets applied to *Hepatocytec1* and *test1,* channel 2 to *Hepatocytec3* and *test2., etc...*
You can reverse the order of the channel application by checking the box to reverse order in channel settings -
A notification will appear that your merge is in progress. Once Biodock's system completes the merge, a folder will be created in your filesystem in the same location where you made your selection of files. This folder will contain your merged 3D multichannel image files, which in our example are *Heptocytec.tif* and *test.tif*.
Below is the viewer of the merged 3D file *test.tif.* The image has 3 channels, comprising of the 3 files captured over 3 different channels which have been merged as specified by the settings we had input earlier on this page.
#### Channel appears first in file name
The merge regex by default sets the second capture group to identify channel values. With advanced settings, you can flip the capture group ordering so files that have channel appearing first can be matched with the first regex group.
Regex can become complex but it is flexible enough to support the naming conventions and desired grouping conventions of your image files. See[ Examples](/files/view-and-manage-data/merging-channels) for help on specifying the merge settings to merge your single channel images.
## Examples
1\) Files -
* *ControlMAP2X1.tif*
* *ControlNOMAP1X3.tif*
* *ControlSOMETHINGELSEX6.tif*
* *ControlOTHERx8.tif*
The regex to merge these files into a single file Control.tif -
**(Control).+(x\[1-9])** - matches the prefix common to all files first -- Control. Then matches any character any number of times -- until the 2nd group match of 'x followed by a number between 1 & 9.
# Supported image types
## Supported file formats
Our filesystem supports any file format supported by Bioformats (see limitations below). You can see their supported formats [here](https://docs.openmicroscopy.org/bio-formats/6.8.1/supported-formats.html).
### Most battle-tested formats
Some formats have been used and tested more extensively on Biodock. If you can export files in multiple formats, you should use these.
* .tiff/.tif
* .svs
* .czi (with limitations below)
* .lif (with limitations below)
* .png
* .jpg/.jpeg
* ome.tiff
* mrxs (see how to upload below)
* vsi (see how to upload below)
### Special format uploads: mrxs and vsi
MRXS and VSI files are complex files that need multiple accompanying folders and files in order to be appropriately opened in Biodock and other software.
See below how these files needs to be structured before you upload them to Biodock.
