Video walkthrough of Metadata import and generating comparative analyses
Adding New Metadata
Metadata can be added or edited for one or more samples by selecting them in the “Samples” Menu and clicking “Edit Metadata”. Depending on the number of samples selected, you will be prompted to edit metadata categories through a pop-up (Single Edit) or a template .CSV file (Batch Edit).
1. Editing Single-Sample Metadata
- When Editing Metadata for a single sample, a pop-up window will appear to edit default metadata or New Custom Fields.
- Enter a text/numeric/datetime value for relevant metadata categories, or add a new metadata category by selecting “Create Custom Field”.
- Click “Save” once complete to view the updated metadata in the sidebar.
2. Editing Multi-Sample Metadata by Template Batching
When Editing Metadata for multiple samples, select all files and download the template CSV. We prefer to edit these in Excel, ensuring that no formulas/special characters are added and the file be saved as a ..Long format: Columns represent your different samples and rows represent your metadata fields. This is the default format when downloading a template. Short format: Rows represent your different samples and columns represent your metadata fields. This format may be more familiar if you’re used to traditional spreadsheet layouts.
- Third Column and Fifteenth row onwards - Custom Metadata Data Type. It can be either “Text” or “Decimal” (Numbers or Numerics)
YYYY-MM-DD
What is metadata?Metadata provides contextual information about your samples, such as:
- Collection details (e.g., date, location, method)
- Sample type (e.g., stool, soil, wastewater)
- Experimental variables (e.g., treatment groups, timepoints)
- Demographic details (e.g., age, sex, BMI, clinical data)
- Consistent Identifiers: Ensure your metadata variables are consistent across groups
- Comprehensive Details: Include as much metadata as possible to support robust downstream analyses.
- Regular Updates: Keep your metadata files up-to-date, especially for longitudinal studies.
- Group Wide-Ranging Continuous Variables: if you have a wide-ranging numerical value for metadata (e.g., ages ranging from 0-60), consider grouping them into categories (Age: 0-18years, 19-39 years, 40-60years). Pick relevant ranges according to your study.
How to delete existing metadata categories
To delete existing metadata categories entirely, follow these steps:- download a template CSV for your samples
- delete the variables for each sample, leaving the text in the Key/Label/Type/Example (columns A-D).
- Save the file and reupload to the platform.
- You’ll now see that the variable category has been completely deleted.
Filtering your Dashboard View with Custom Metadata Fields:
Cosmos-Hub allows you to filter your dashboard view on the Cohorts & Metadata menu by using your uploaded custom metadata fields. The video down below gives you a short demonstration on how to use this functionality for your use-case.Troubleshooting Common Metadata Upload Errors
If you encounter errors during metadata upload, please check for the following issues:- Duplicate Column Names: All column headers must be unique. For example, do not include the same field (such as “Visit Date”) more than once. Duplicate headers will block uploads.
- Datetime Format Requirements: Date fields must use ISO 8601 format (
YYYY-MM-DD), unless otherwise specified. Spreadsheet editors (like Excel) often auto-format dates; double-check and reformat as needed. For best results, use Numbers or CSV tools that preserve formatting. - Character Limits: Text field values must not exceed 32 characters.
- No Special Characters or Spaces in Field Labels: For custom fields, avoid all special characters and spaces in labels.
- File Encoding: Save your metadata as UTF-8 encoded CSV to prevent issues with hidden or non-printable characters.
Error messages reference
Below are the specific error messages you may encounter and how to resolve them:Label and uniqueness errors
| Error | Resolution |
|---|---|
| Duplicate label detected: “label” conflicts with an existing metadata label. | Rename the label so all metadata labels are unique. |
| Missing metadata label: Each metadata field must have a label name. | Add a Metadata label and try again. |
| Invalid label: “label” cannot be empty or contain only spaces. | Enter a meaningful metadata label. |
System metadata errors
| Error | Resolution |
|---|---|
| System metadata is read-only: “label” cannot be edited. | Revert it to its original value. System metadata fields are protected and cannot be modified. |
Metadata type errors
| Error | Resolution |
|---|---|
| Metadata type mismatch: “label” expects type X, but the uploaded value is Y. | Update the values or change the metadata label type to match. |
| Missing metadata type: Each metadata field must specify a type (e.g., text, decimal, datetime). | Define the type and try again. |
Template integrity errors
| Error | Resolution |
|---|---|
| Template error detected: The metadata template appears to be corrupted or modified incorrectly. | Download a fresh template and re-enter your metadata. |
| Invalid template format: This file does not match the required Cosmos-Hub metadata template. | Download the latest template and upload it without modifying its structure. |
Numeric value errors
| Error | Resolution |
|---|---|
| Invalid Values: “label” must contain a numeric value. | Remove non-numeric characters and try again. |
| Invalid number format: “label” expects a numeric value, but received “input”. | Enter a valid number (e.g., 3, 3.14). |
Date value errors
| Error | Resolution |
|---|---|
| Invalid date: “label” must be a valid date. | Use one of the supported date formats. |
| Invalid date format: “label” must be a valid date using a supported format. | Use ISO 8601 format (YYYY-MM-DD) or another supported format. |
Sample matching errors
| Error | Resolution |
|---|---|
| No matching samples found: The sample IDs in your metadata file do not match any of the selected samples. | Verify that sample names are spelled correctly and match existing sample IDs exactly. |