Uploading Metadata

Cosmos-Hub streamlines the process of organizing and analyzing your microbiome data by linking it to relevant experimental or sample metadata. Follow these detailed instructions to ensure smooth and efficient metadata integration into your analysis workflows.

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).

Editing Single-Sample Metadata

1. When Editing Metadata for a single sample, a pop-up window will appear to edit default metadata or New Custom Fields.
2. Enter a text/numeric/datetime value for relevant metadata categories, or add a new metadata category by selecting “Create Custom Field”.
3. Click “Save” once complete to view the updated metadata in the sidebar.

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 .csv.

Filling out the Metadata Template Form:

Download a Metadata CSV Form for all of your samples. The form is in long format with columns representing your different samples and rows representing your metadata fields. The first two rows needs to stay constant and are not modifiable. From Third row till Fifteenth row represents system metadata fields which are optional fields to fill out if its relevant to your project. Fields that needs to be filled out for custom metadata are

• Second Column and Fifteenth row onwards:- Custom Metadata Field Label without any special characters and spaces
• Third Column and Fifteenth row onwards - Custom Metadata Data Type. It can be either “Text” or “Decimal” (Numbers or Numerics)
• Fifteen Column and Onwards - Custom Metadata values for your respective samples

Note: Before uploading, always confirm that (1) no column headers are duplicated, (2) all date values are in the required ISO 8601 format (YYYY-MM-DD), and (3) text fields comply with the 32-character length limit. See Troubleshooting, below, for more details.

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)

Adding metadata enhances the power of your analysis by enabling cohort creation, comparative studies, and advanced statistical modeling.

Best Practices for Metadata Upload

1. Consistent Identifiers: Ensure your metadata variables are consistent across groups
2. Comprehensive Details: Include as much metadata as possible to support robust downstream analyses.
3. Regular Updates: Keep your metadata files up-to-date, especially for longitudinal studies.
4. 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:

1. download a template CSV for your samples
2. delete the variables for each sample, leaving the text in the Key/Label/Type/Example (columns A-D).
3. Save the file and reupload to the platform.
4. You’ll now see that the variable category has been completely deleted.

Here is a video tutorial for troubleshooting:

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.

Example Error Message:

“Not all metadata fields were updated properly. Please try again.”

This generic error is most commonly caused by:

• Duplicate columns
• Incorrect date/datetime format
• Text values exceeding the 32-character maximum
• File encoding issues

If you have followed all of the above and continue to have issues, please contact support with your metadata file attached for further assistance.

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.

Learn how to generate comparative analyses on our next page: Comparing Samples

---