What is metadata?
What is metadata?
Metadata provides contextual information about your samples, such as:Best Practices for Metadata Upload
- 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.
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 ..
Sample Biom Type, Sample Host, Read Type, Illumina Fragment Length, Sample Collection Date, GPS Coordinates, Study Objectives, DNA Extraction Kit, Library Preparation Kit, Sequencing Platform, Project Name) :
- Long Format (default selection)
- Wide Format
Long format metadata
- Each sample is represented in columns. Each column has a Unique Sample ID (e.g., 1fb0f270-4848-4965-940a-df04b48662f3) and Sample Name (e.g., Sample1) as headers in rows 1 and 2 respectively.The first two rows need to stay constant and should not be modified or rearranged.
- Each metadata field gets its own row. Identifying metadata variables (like sampleID or treatment group) may have repeated values across each row.
- Metadata groups are represented in row 3 and beyond.
- To add a new metadata group, simply create a new row, with the metadata variable name in Column A and the data-type in Column B (either text, decimal, or datetime)
-
If predefined metadata is selected: row 3-15 represents system metadata fields which are optional fields to fill out if relevant to your project.
- Both Label and **Type (One of: text | decimal | datetime) **are required in columns A and B.
- Custom Metadata Field Labels cannot contain any special characters or spaces.
- Text fields should not exceed 32 characters.
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.
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. |