WellMapper

A flexible, configurable well plate layout designer and exporter for napari. Design plate layouts with dynamic field configuration and export to local or cloud storage (AWS S3, Azure Blob, Google Cloud Storage).

Features

• Flexible Configuration: Define experiment and well metadata fields via YAML config
• Visual Plate Design: Interactive grid for selecting and annotating wells
• Color-Coded Wells: Automatic color assignment based on well metadata for easy visualization
• Multiple Storage Backends: Export to local filesystem, AWS S3, Azure Blob Storage, or Google Cloud Storage
• Dynamic Field Types: Support for text, integer, date fields with autocompletion
• Incomplete Well Detection: Visual warnings for partially filled wells
• Configuration GUI: Built-in editors for plate parameters and storage settings

Installation

Basic Installation

pip install WellMapper

With Cloud Storage Support

For AWS S3:

pip install WellMapper[s3]

For Azure Blob Storage:

pip install WellMapper[azure]

For Google Cloud Storage:

pip install WellMapper[gcs]

For all storage backends:

pip install WellMapper[all]

Quick Start

1. Launch napari and open the plugin:

   • Plugins → WellMapper → Well Plate Layout

2. Configure your plate (optional):

   • Plugins → WellMapper → Set Plate Layout Parameters
   • Add/remove experiment and well information fields

3. Set up storage (optional):

   • Plugins → WellMapper → Set Storage Solution
   • Configure local or cloud storage backend

4. Design your layout:

   • Fill in experiment information (barcode, date, etc.)
   • Select wells and apply metadata
   • Export to CSV

Usage

Basic Workflow

1. Enter Experiment Information

   • Barcode (required)
   • Number of rows and columns
   • Date and any custom fields
   • Click "Confirm Experiment Info"

2. Annotate Wells

   • Fill in well metadata fields (donor, condition, concentration, etc.)
   • Select one or multiple wells in the plate grid
   • Click "Apply to Selected"
   • Wells are automatically color-coded based on their metadata

3. Export Layout

   • Click "Export CSV"
   • File is saved to configured storage backend
   • Default location: ./data/{barcode}/layout.csv

Configuration

Plate Parameters (plate_config.yaml)

Define custom fields for your experiments:

experiment_information:
  barcode:
    label: Barcode
    type: text
    required: true
  date:
    label: Date
    type: date
    default: today
    required: true
  interval:
    label: Interval (min)
    type: int
    default: 10
    min: 1
    max: 1440

well_information:
  donor:
    label: Donor ID
    type: text
  condition:
    label: Treatment
    type: text
    completer:
      - Control
      - Drug A
      - Drug B
  concentration:
    label: Concentration (µM)
    type: text
    completer:
      - "0"
      - "0.1"
      - "1"
      - "10"

Field Types:

• text: Free text input with optional autocomplete
• int: Integer input with min/max constraints
• date: Date picker

Mandatory Fields:

• rows, cols, barcode, date in experiment_information

Storage Configuration

Configure storage via GUI (Plugins → Set Storage Solution) or manually create .env:

Local Storage (default):

STORAGE_TYPE=local
STORAGE_PATH=./data

AWS S3:

STORAGE_TYPE=s3
S3_BUCKET=my-bucket
S3_PREFIX=plate-layouts
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=your-key
AWS_SECRET_ACCESS_KEY=your-secret

Azure Blob Storage:

STORAGE_TYPE=azure
AZURE_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=...
AZURE_CONTAINER=data
AZURE_PREFIX=plate-layouts

Google Cloud Storage:

STORAGE_TYPE=gcs
GCS_BUCKET=my-bucket
GCS_PREFIX=plate-layouts
GCS_PROJECT=my-project
GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json

CSV Output Format

The exported CSV includes all configured fields:

barcode,date,interval,well,donor,condition,concentration
ABC123,2024-01-15,10,A1,D001,Control,0
ABC123,2024-01-15,10,A2,D001,Drug A,0.1
ABC123,2024-01-15,10,A3,D001,Drug A,1
ABC123,2024-01-15,10,B1,D002,Control,0
...

Advanced Features

Color Coding

Wells are automatically assigned distinct colors based on their complete metadata profile. This helps visually identify:

• White: Empty wells
• Colored: Wells with complete metadata (same metadata = same color)
• Yellow "!" marker: Incomplete wells (partial metadata)

Multi-Well Selection

• Click individual wells or drag to select multiple wells
• Apply the same metadata to all selected wells at once
• Efficient for replicates and structured plate designs

Configuration Editor

Use the built-in GUI to:

• Add/remove experiment and well fields
• Set field types and constraints
• Define autocomplete options
• Configure default values

Storage Backend Testing

The storage configuration widget includes a "Test Connection" button to verify:

• Credentials are valid
• Bucket/container exists and is accessible
• Write permissions are correct

File Structure

WellMapper/
├── WellMapper/
│   ├── __init__.py
│   ├── _layout_widget.py       # Main plate layout widget
│   ├── _parameter_widget.py    # Configuration editor
│   ├── _storage_widget.py      # Storage setup widget
│   ├── storage_backends.py     # Storage implementations
│   ├── plate_config.yaml       # Default plate configuration
│   └── .env                    # Storage configuration (user-created)
├── napari.yaml                 # Plugin manifest
├── pyproject.toml             # Package configuration
└── README.md

Examples

Example 1: Drug Screening Plate

experiment_information:
  barcode:
    label: Plate Barcode
    type: text
    required: true
  assay_date:
    label: Assay Date
    type: date
    default: today
    required: true
  cell_line:
    label: Cell Line
    type: text
  passage:
    label: Passage Number
    type: int
    min: 1
    max: 100

well_information:
  compound:
    label: Compound
    type: text
    completer:
      - DMSO (Control)
      - Compound A
      - Compound B
      - Compound C
  concentration:
    label: Concentration (µM)
    type: text
    completer:
      - "0"
      - "0.01"
      - "0.1"
      - "1"
      - "10"
      - "100"
  replicate:
    label: Replicate
    type: text
    completer:
      - "1"
      - "2"
      - "3"

Troubleshooting

Storage Configuration Not Found

Error: "Could not initialize storage backend"

Solution: Create .env file in napari by Plugins -> WellMapper -> Set Storage Solution

Cloud Storage Dependencies Missing

Error: "boto3 required for S3 storage"

Solution: Install with storage extras:

pip install WellMapper[s3]

Wells Not Updating Colors

Issue: Wells stay white after applying metadata

Solution: Ensure all fields are filled. Partial data triggers incomplete well warning (yellow "!").

CSV Export Path Issues

Issue: Can't find exported files

Solution: Check storage configuration. Default is ./data/{barcode}/layout.csv relative to where napari was launched.

License

This project is licensed under the Apache License 2.0 License - see the LICENSE file for details.

Citation

If you use this plugin in your research, please cite:

@software{WellMapper,
  author = {van der Steen, Krijn H.},
  affiliation = {Lab of Cellular Disease Models, Regenerative Medicine Center Utrecht, UMC Utrecht, The Netherlands},
  title = {WellMapper: Well Plate Layout Designer for napari},
  year = {2026},
  url = {https://github.com/Living-Technologies/WellMapper}
}

Acknowledgments

• Built with napari