Skip to main content

Uploading Trials via CSV

Bulk upload trial data using a CSV file to quickly populate your experiment with multiple trials at once.

Overview​

The trial upload feature allows you to:

  • Import multiple trials in a single operation
  • Create new trials or update existing ones using Trial ID
  • Validate data before upload to catch errors early
  • Download error reports to fix issues and re-upload

Step-by-step guide​

Step 1: Download the CSV template​

  1. Navigate to your experiment's detail page
  2. Click the Import file button in the Trials section
  3. In the drawer that opens, click Download template
    Trials upload Screenshot

The template includes all required columns for your experiment:

  • Parameter columns: One column per parameter (e.g., "Parameter: Temperature")
  • Target columns: One column per target (e.g., "Target: Yield")
  • State: The trial state (PENDING, COMPLETED, FAILED, REJECTED)
  • State Message: Optional message for Failed or Rejected trials
  • Trial Number: System-generated display ID (informational only)
  • Trial ID: System-generated unique identifier (use for updates)

Step 2: Fill in your trial data​

Open the CSV template in Excel, Google Sheets, or any spreadsheet application.

Creating new trials​

Leave the Trial ID column blank. Fill in:

  • Parameter values (required for all states)
  • Target values (required for COMPLETED trials)
  • State (required - see Trial States)
  • State Message (required for FAILED and REJECTED trials)

Updating existing trials​

To update an existing trial, enter its Trial ID in the Trial ID column, then modify the values you want to update.

Export existing trials

Click Download Template to download a CSV with all current trial data. This is useful for:

  • Bulk editing existing trials
  • Using as a reference for the correct format
  • Copying trial data to create similar trials

Step 3: Upload the completed CSV​

  1. Drag and drop your CSV file into the upload area, or click Browse to select it
  2. The system will automatically validate your file and display:
    • Total rows processed
    • Valid rows that passed validation
    • Errors that need to be fixed

Step 4: Review validation results​

If validation passes ✓​

Trials upload valid Screenshot
  • You'll see a green success message: "File checks passed"
  • Click Create trials to upload the data

If validation fails ✗​

Trials upload invalid Screenshot
  • You'll see a red error message with error counts
  • Click Download report to get a CSV with error details
  • Each error row includes:
    • Error Count: Number of errors in that row
    • Errors: Detailed description of each error
    • All original columns for reference
  • Fix the errors in the downloaded report
  • Remove the "Error Count" and "Errors" columns
  • Re-upload the corrected file

Step 5: Create trials​

Trials upload complete Screenshot
After validation passes, click Create trials. The system will:

  1. Process each row in your CSV
  2. Create new trials or update existing ones
  3. Display a summary showing:
    • Created: Number of new trials added
    • Updated: Number of existing trials modified
    • Failed: Number of rows that couldn't be processed

If any rows failed during upload, download the error report to see detailed error messages.

Trial states​

The State column determines how the trial is used in BayBE optimization. Choose the appropriate state based on your trial outcome:

PENDING​

Use for: New trials that haven't been run yet

  • Include all parameter values
  • Target values can be missing or partial
  • BayBE will suggest these trials to be run

Example: You want to pre-load a set of experiments to run in the lab

COMPLETED​

Use for: Trials that have finished and produced valid results

  • Include all parameter values (required)
  • Include all target values (required)
  • BayBE will use this data for learning and optimization

Example: Your experiment ran successfully and you measured all outcomes

FAILED​

Use for: Trials that couldn't be completed due to technical issues

  • Include all parameter values
  • Include a reason in State Message (required)
  • BayBE excludes this from learning but may suggest similar parameters again
  • Use when the failure doesn't reflect the true system behavior (e.g., equipment failure, measurement error)

Example: The experiment failed because of a power outage during the run

REJECTED​

Use for: Trials you want to permanently exclude from consideration

  • Include all parameter values
  • Include a reason in State Message (required)
  • BayBE will not suggest similar parameter combinations in the future
  • Use when you want to avoid this region of the search space

Example: The parameter combination caused safety concerns or violated an unstated constraint

CSV format examples​

Example 1: Creating new PENDING trials​

Parameter: Temperature,Parameter: Time,Target: Yield,Target: Purity,State,State Message (for Failed or Rejected trials),Trial Number (system generated),Trial ID (system generated)
150,30,,,PENDING,,,
175,45,,,PENDING,,,
200,60,,,PENDING,,,

Example 2: Creating COMPLETED trials with results​

Parameter: Temperature,Parameter: Time,Target: Yield,Target: Purity,State,State Message (for Failed or Rejected trials),Trial Number (system generated),Trial ID (system generated)
150,30,75.5,92.3,COMPLETED,,,
175,45,82.1,95.7,COMPLETED,,,
200,60,78.9,89.2,COMPLETED,,,

Example 3: Mixed states including FAILED​

Parameter: Temperature,Parameter: Time,Target: Yield,Target: Purity,State,State Message (for Failed or Rejected trials),Trial Number (system generated),Trial ID (system generated)
150,30,75.5,92.3,COMPLETED,,,
175,45,,,FAILED,Equipment malfunction during measurement,,
200,60,78.9,89.2,COMPLETED,,,
225,75,,,REJECTED,Temperature exceeded safe operating limits,,

Example 4: Updating an existing trial​

Parameter: Temperature,Parameter: Time,Target: Yield,Target: Purity,State,State Message (for Failed or Rejected trials),Trial Number (system generated),Trial ID (system generated)
175,45,82.1,95.7,COMPLETED,,123,trial-abc-123-def

Frequently Asked Questions​

What file format is supported?​

Only .csv (comma-separated values) files are supported. Excel files (.xlsx) must be saved as CSV first.

Do I need to fill in Trial Number and Trial ID?​

  • Trial Number: System-generated, you can leave blank or ignore
  • Trial ID: Leave blank for new trials, or provide an existing Trial ID to update that trial

Can I upload trials with only some target values?​

Yes, for PENDING trials. For COMPLETED trials, all targets must have values.

What happens if I upload a CSV with errors?​

The upload will be blocked until all errors are fixed. Download the error report, correct the issues, and re-upload.

Can I update multiple trials at once?​

Yes, include the Trial ID for each trial you want to update in your CSV.

What parameter value formats are accepted?​

  • Numerical parameters: Plain numbers (e.g., 150, 42.5)
  • Categorical parameters: Category names (case-insensitive, automatically matched to defined categories)
  • Substance parameters: Substance names (case-insensitive, automatically matched to defined substances)
  • The system validates parameter types and acceptable ranges

What if my CSV has extra columns?​

Extra columns are ignored. Only the expected parameter, target, and system columns are processed.

Can I delete trials via CSV upload?​

No, CSV upload only creates or updates trials. To delete trials, use the UI delete function on individual trials.

What's the maximum file size?​

The file size is limited to reasonable CSV sizes (typically under 10 MB). For very large datasets, consider splitting into multiple uploads.

How do I handle special characters in values?​

Use standard CSV escaping:

  • If a value contains commas, wrap it in double quotes: "value, with, commas"
  • If a value contains quotes, escape with double quotes: "value with ""quotes"""

What does "Final validation will run during creation" mean?​

The file validation is a preliminary check. When you click "Create trials", additional server-side validation ensures data integrity with the experiment configuration.

Can I upload trials before defining all parameters and targets?​

No, you must first define all parameters and targets in your experiment. The CSV template is generated based on your current experiment configuration.

What if I need to upload trials with different parameters?​

Each experiment has a fixed set of parameters and targets. If you need different parameters, you should either:

  • Modify your experiment configuration first (if no trials exist yet)
  • Create a new experiment with the new parameter set

Tips for successful uploads​

✓ Start small: Test with a few rows first to verify your format is correct

✓ Use the template: Always download the template for your specific experiment to ensure correct column names

✓ Validate parameters: Make sure numerical values are within defined parameter bounds

✓ Case flexibility: Trial states, categorical values, and substance names are case-insensitive

✓ Be consistent: Use the same units and precision across all trials

✓ Provide context: Use State Message to document why trials Failed or were Rejected

✓ Keep backups: Save a copy of your original CSV before making corrections

Troubleshooting​

"Only .csv files are supported"​

Save your Excel file as CSV format (File → Save As → CSV)

"Missing required columns"​

Download a fresh template - column names must match exactly including "Parameter:" and "Target:" prefixes

"Invalid Trial ID"​

The Trial ID doesn't exist in this experiment. Leave blank to create new trials, or verify you're using the correct ID.

"Invalid State"​

State must be one of: PENDING, COMPLETED, FAILED, REJECTED, RUNNING, or ACCEPTED (case-insensitive)

"Required for COMPLETED trials"​

COMPLETED trials must include all parameter values and all target values

"Required for FAILED trials" / "Required for REJECTED trials"​

FAILED and REJECTED trials must include a State Message explaining the reason

Parameter validation errors​

Check that:

  • Numerical values are within the defined min/max bounds
  • Categorical values match defined categories (case-insensitive)
  • Substance values match defined substances (case-insensitive)
  • Required parameters are not empty