> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cosmosid.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
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.
## 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
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.
## 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 .csv.
# Filling out the Metadata Template Form
When downloading the template CSV, you can download a template in 2 formats, as well as the option to include predefined metadata categories (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)
The platform supports two template formats:
**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.
**Other metadata requirements:**
* 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.
**Note:** Before uploading, always confirm that (1) no column headers are duplicated, (2) all date values are in the required format (dictated by your [Account Settings](/docs/setting-up-your-account), and (3) text fields comply with the 32-character length limit. See Troubleshooting, below, for more details.
You can filter your sample list based on metadata variables using the [**Sample Filtering panel**](/v2-0/documentation/guides/navigating-the-sample-dashboard/filtering-samples-by-metadata)
**Wide format metadata**
* Each sample is represented as an individual row.
* Metadata variables get their own column representing your metadata fields of choice.
* Column A and B contain the Unique Sample ID (e.g., 1fb0f270-4848-4965-940a-df04b48662f3) and Sample Name (e.g., Sample1) respectively.**The first two columns need to stay constant and should not be modified or rearranged.**
* To add a new metadata group, simply create a new column, with the metadata variable name in Row 1 and the data-type in Row 2 (either text, decimal, or datetime)
# 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:
Read through common pitfalls and errors during metadata upload at our [Troubleshooting Common Metadata Upload Errors](https://docs.cosmosid.com/docs/technical-appendix/technical-appendix/metadata-errors) page.
***
## 1. 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.
## 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 .
# 
**Other metadata requirements:**
* 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.
**Note:** Before uploading, always confirm that (1) no column headers are duplicated, (2) all date values are in the required format (dictated by your [Account Settings](/docs/setting-up-your-account), and (3) text fields comply with the 32-character length limit. See Troubleshooting, below, for more details.
