Skip to main content

​
Video walkthrough of Metadata import and generating comparative analyses

​
Adding your Metadata

Metadata can be added or edited for one or more samples by selecting them in the “Cohorts and Metadata” 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

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.

​
Editing Multi-Sample Metadata by Template Batching

When Editing Metadata for multiple samples, select all files and download the template CSV.

​
Filling up the Metadata CSV Upload Template Form:

At the upload stage, you will be asked to 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.

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

​

​
Generating Comparatives and splitting Cohorts automatically using your custom metadata fields as well as your Folder Structure:

Cosmos-Hub allows you to generate comparatives automatically using automated cohort splitting instead of selecting each sample manually for different cohorts. The video down below gives you a short demonstration on how to use this functionality for your use-case.
The results for the comparative analysis can be viewed from the Comparative Analysis Section on the menu. The video down below gives you a short demonstration on how to navigate to the Comparative Analysis Results and explore the results.