Trovomics CSV File Guidelines

When uploading metadata to Trovomics, it is essential that your CSV files follow strict formatting rules. This enables accurate linking of your sample data, smooth downstream analyses, and minimal rework due to file validation errors. The Trovomics CSV validation function checks for:

1. Presence of Required Columns

2. Illegal Characters in Column Names

3. Illegal Characters in Data Cells

Any violations trigger error details and a validation failure. Review these guidelines carefully to avoid upload errors and ensure efficient data processing.

1. Required Columns

Your CSV file must include the following mandatory columns, which are used to link metadata to your actual omics data files:

• SampleName

  • A unique identifier for each sample in your experiment.

  • If you have multiple replicates, each row should have a distinct SampleName, unless they are multiple files for the same sample.

• Filename

  • The Filename should be unique across the entire analysis.

  • The name of the raw data file (FASTQ) corresponding to each sample.

  • This should match the file’s exact name. Do not include the path.

These two columns are case-sensitive and must appear exactly as shown (SampleName and Filename). Files missing either required column will be rejected.

2. General Guidelines

All metadata values should be categorical. If your dataset contains a column with numerical data, it should be turned into appropriate categories before uploading the csv file.

Example:

Numerical values

Variable: Age

Values: 21, 25, 30, 37, 28, 32, 22, 33, 29, 34.

Covert these values into categories appropriate for the goals of your analysis (e.g. younger_than_30, 30_or_older).

Categorical values

Variable: Age

Values: younger_than_30, younger_than_30, 30_or_older, 30_or_older,

younger_than_30, 30_or_older, younger_than_30, 30_or_older, younger_than_30,

30_or_older

3. Column Name Guidelines

In addition to the required columns, you may include any number of optional columns (e.g., Condition, Genotype, Tissue, Treatment). These additional columns capture the experimental metadata that Trovomics uses for downstream analyses. All columns, including required and optional, must adhere to the following naming rules:

3.1 Valid Characters

Column names may contain only letters, numbers and underscores.

Column names must start with a letter.

3.2 Example Disallowed Characters

Column names must not contain any of the following:

• Punctuation/Special Characters:

  , ; : . / \ | ? < > [ ] { } ( ) + -

• Whitespace:

  Spaces are disallowed in column names (e.g., “Group Name” is invalid). If needed,

  use camelCase or underscores (e.g., “GroupName” or “Group_Name”).

• Leading Characters:

  Column names should start with a letter, not a number or an underscore (_).

4. Data Cell Guidelines

Each row in the CSV file represents a single sample (or replicate). You can include as many optional metadata columns as you need; for example, you might have columns for Condition, Dose, Genotype, Treatment, Batch, Tissue, Cell_Type, etc.

4.1 Required Columns

• SampleName: Must be present and non-empty for every row.

• Filename: Must be present and non-empty for every row, exactly matching the physical data file name (including the file extension). Missing values in either SampleName or Filename will invalidate the CSV.
  The corresponding sequencing files must follow either the Illumina filename convention or the NCBI GEO filename convention for .fastq.gz files.

  Examples:

  • Illumina: Sample1_S1_L001_R1_001.fastq.gz
    (SampleName value: Sample1,
    Filename value: Sample1_S1_L001_R1_001.fastq.gz)

  • NCBI GEO: SRR1234567_1.fastq.gz
    (SampleName value: SRR1234567,
    Filename value: SRR1234567_1.fastq.gz)

4.2 Valid Characters

• Data Cell values may contain only letters, numbers and underscores.

• Data Cell values must start with a letter.

4.3 Data Columns

• Formatting & Type

  • Avoid using any of the disallowed characters listed in Section 3.2.

• Missing or Null Data

  • If you wish to explicitly label missing data, consider using the value no_data instead of NA, NaN, or NULL, which are reserved and may interfere with the pipeline.

4.4 Examples of Valid vs. Invalid Column Names and Data Cell Values

• Valid: SampleName, Filename, Condition, Replicate01, Treatment_2, A673, ETV6, H3K4me3

• Invalid: Sample Name, Drug+, Group?, _Condition, Group-Name, 5e10, pi, Inf, NA

5. Practical Tips for Omics Datasets

1. Consistent Naming: Align SampleName with your laboratory records. For example, if a sample is known as Patient1_TissueA_Rep1, use that exact identifier in the CSV.

2. Exact Filename Matching: Ensure the Filename column matches the actual data files in your system (e.g., Patient1_TissueA_Rep1_S1_L001_R1_001.fastq.gz). Any mismatch leads to processing errors.

3. Descriptive Metadata Columns: Add columns like Condition, Genotype, Tissue, Treatment for robust downstream analysis. Avoid disallowed characters or spaces in these column names.

4. Make Sure to Include Only Valid Characters: Columns and data cells may contain only letters, numbers and underscores, and must start with a letter.

5. Local Validation: It is good practice to inspect your CSV before uploading. This can save time and prevent re-uploads.

6. Example CSV Layout

The way sequencing files are linked to your samples depends on the analysis pipeline you are using.

RNA-seq Pipeline

For RNA-seq analyses, all sample metadata and sequencing file information are stored in a single CSV file, the FASTQ file names are included directly in the metadata table.

• SampleName: Unique for each sample

• Filename: Matches each FASTQ file exactly

• Condition, Tissue, Treatment, etc: Additional metadata columns

• No spaces or disallowed characters in headers or required cell values

single-end data:

csv

SampleName,Filename,Condition,Tissue

Sample1,Sample1_S1_L001_R1_001.fastq.gz,Control,Liver

Sample2,Sample2_S2_L001_R1_001.fastq.gz,Control,Liver

Sample3,Sample3_S3_L001_R1_001.fastq.gz,Control,Liver

Sample4,Sample4_S4_L001_R1_001.fastq.gz,Treatment,Liver

Sample5,Sample5_S5_L001_R1_001.fastq.gz,Treatment,Liver

Sample6,Sample6_S6_L001_R1_001.fastq.gz,Treatment,Liver

Sample7,Sample7_S7_L001_R1_001.fastq.gz,Control,Heart

Sample8,Sample8_S8_L001_R1_001.fastq.gz,Control,Heart

Sample9,Sample9_S9_L001_R1_001.fastq.gz,Control,Heart

Sample10,Sample10_S10_L001_R1_001.fastq.gz,Treatment,Heart

Sample11,Sample11_S11_L001_R1_001.fastq.gz,Treatment,Heart

Sample12,Sample12_S12_L001_R1_001.fastq.gz,Treatment,Heart

paired-end data:

csv

SampleName,Filename,Condition,Tissue

Sample1,Sample1_S1_L001_R1_001.fastq.gz,Control,Liver

Sample1,Sample1_S1_L001_R2_001.fastq.gz,Control,Liver

Sample2,Sample2_S2_L001_R1_001.fastq.gz,Control,Liver

Sample2,Sample2_S2_L001_R2_001.fastq.gz,Control,Liver

Sample3,Sample3_S3_L001_R1_001.fastq.gz,Control,Liver

Sample3,Sample3_S3_L001_R2_001.fastq.gz,Control,Liver

Sample4,Sample4_S4_L001_R1_001.fastq.gz,Treatment,Liver

Sample4,Sample4_S4_L001_R2_001.fastq.gz,Treatment,Liver

Sample5,Sample5_S5_L001_R1_001.fastq.gz,Treatment,Liver

Sample5,Sample5_S5_L001_R2_001.fastq.gz,Treatment,Liver

Sample6,Sample6_S6_L001_R1_001.fastq.gz,Treatment,Liver

Sample6,Sample6_S6_L001_R2_001.fastq.gz,Treatment,Liver

Sample7,Sample7_S7_L001_R1_001.fastq.gz,Control,Heart

Sample7,Sample7_S7_L001_R2_001.fastq.gz,Control,Heart

Sample8,Sample8_S8_L001_R1_001.fastq.gz,Control,Heart

Sample8,Sample8_S8_L001_R2_001.fastq.gz,Control,Heart

Sample9,Sample9_S9_L001_R1_001.fastq.gz,Control,Heart

Sample9,Sample9_S9_L001_R2_001.fastq.gz,Control,Heart

Sample10,Sample10_S10_L001_R1_001.fastq.gz,Treatment,Heart

Sample10,Sample10_S10_L001_R2_001.fastq.gz,Treatment,Heart

Sample11,Sample11_S11_L001_R1_001.fastq.gz,Treatment,Heart

Sample11,Sample11_S11_L001_R2_001.fastq.gz,Treatment,Heart

Sample12,Sample12_S12_L001_R1_001.fastq.gz,Treatment,Heart

Sample12,Sample12_S12_L001_R2_001.fastq.gz,Treatment,Heart

Before uploading, verify that:

• Every sample has the correct FASTQ filename(s).

• Filenames exactly match the uploaded FASTQ files, including the .fastq.gz extension.

ChIP-seq Pipeline

For ChIP-seq analyses, sequencing information is separated into two CSV files:

1. metadata.csv

This file contains the experimental design and sample annotations. Each row represents one biological sample and should include:

• SampleName – Unique sample identifier.

• Replicate – Biological replicate number (digits only).

• Factor – Target protein or mark (for example, a transcription factor or histone modification).

• Tissue – Cell type or tissue.

• Condition – Experimental condition or genotype.

• Treatment – Treatment or perturbation (if applicable).

• SampleType – Specify whether the sample is IP or Input.

• ControlName – For IP samples, provide the corresponding Input sample name. For Input samples, use Input.

Replicate numbering conventions for ChIP-seq:

• Replicates are grouped by Factor, Tissue, Condition, Treatment, SampleType

• Within each group, replicate numbers must start at 1, have no gaps, and not duplicates.

Condition/Treatment rule for ChIP-seq:

• Condition and Treatment can be empty, but each column must be empty for every row or filled for every row.

2. files.csv

This file maps each sample to its sequencing files.

For single-end sequencing, include: SampleName, Filename

For paired-end sequencing, include: SampleName, Filename_1_1, Filename_1_2

where:

• Filename_1_1 contains the R1 FASTQ file.

• Filename_1_2 contains the R2 FASTQ file.

single-end data:

metadata csv file

SampleName,Replicate,Factor,Tissue,Condition,Treatment,SampleType,ControlName

Factor1_IP_Tissue1_Treated_1,1,Factor1,Tissue1,Condition1,Treated,IP,Input_Tissue1_1

Factor1_IP_Tissue1_Control_1,1,Factor1,Tissue1,Condition1,Control,IP,Input_Tissue1_1

Factor2_IP_Tissue1_Treated_1,1,Factor2,Tissue1,Condition1,Treated,IP,Input_Tissue1_1

Factor2_IP_Tissue1_Control_1,1,Factor2,Tissue1,Condition1,Control,IP,Input_Tissue1_1

Input_Tissue1_1,1,Input,Tissue1,Input,Input,Input,Input

files csv file

SampleName,Filename

Factor1_IP_Tissue1_Treated_1,Factor1_IP_Tissue1_Treated_1_S1_L001_R1_001.fastq.gz

Factor1_IP_Tissue1_Control_1,Factor1_IP_Tissue1_Control_1_S2_L001_R1_001.fastq.gz

Factor2_IP_Tissue1_Treated_1,Factor2_IP_Tissue1_Treated_1_S3_L001_R1_001.fastq.gz

Factor2_IP_Tissue1_Control_1,Factor2_IP_Tissue1_Control_1_S4_L001_R1_001.fastq.gz

Input_Tissue1_1,Input_Tissue1_1_S5_L001_R1_001.fastq.gz

paired-end data:

metadata csv file

SampleName,Replicate,Factor,Tissue,Condition,Treatment,SampleType,ControlName

Input_WT_rep1,1,Factor1,Tissue1,WT,,Input,Input

Input_WT_rep2,2,Factor1,Tissue1,WT,,Input,Input

IP_WT_rep1,1,Factor1,Tissue1,WT,,IP,Input_WT_rep1

IP_WT_rep2,2,Factor1,Tissue1,WT,,IP,Input_WT_rep2

Input_KO_rep1,1,Factor1,Tissue1,KO,,Input,Input

Input_KO_rep2,2,Factor1,Tissue1,KO,,Input,Input

IP_KO_rep1,1,Factor1,Tissue1,KO,,IP,Input_KO_rep1

IP_KO_rep2,2,Factor1,Tissue1,KO,,IP,Input_KO_rep2

files csv file

SampleName,Filename_1_1,Filename_1_2

Input_WT_rep1,Input_WT_rep1_S1_L001_R1_001.fastq.gz,Input_WT_rep1_S1_L001_R2_001.fastq.gz

Input_WT_rep2,Input_WT_rep2_S2_L001_R1_001.fastq.gz,Input_WT_rep2_S2_L001_R2_001.fastq.gz

IP_WT_rep1,IP_WT_rep1_S3_L001_R1_001.fastq.gz,IP_WT_rep1_S3_L001_R2_001.fastq.gz

IP_WT_rep2,IP_WT_rep2_S4_L001_R1_001.fastq.gz,IP_WT_rep2_S4_L001_R2_001.fastq.gz

Input_KO_rep1,Input_KO_rep1_S5_L001_R1_001.fastq.gz,Input_KO_rep1_S5_L001_R2_001.fastq.gz

Input_KO_rep2,Input_KO_rep2_S6_L001_R1_001.fastq.gz,Input_KO_rep2_S6_L001_R2_001.fastq.gz

IP_KO_rep1,IP_KO_rep1_S7_L001_R1_001.fastq.gz,IP_KO_rep1_S7_L001_R2_001.fastq.gz

IP_KO_rep2,IP_KO_rep2_S8_L001_R1_001.fastq.gz,IP_KO_rep2_S8_L001_R2_001.fastq.gz

Before uploading, verify that:

• Every SampleName in files.csv exactly matches a SampleName in metadata.csv.

• FASTQ filenames exactly match the uploaded files, including the .fastq.gz extension.

• Each sample appears only once in each CSV file.

• Every IP sample references a valid Input sample through the ControlName column. If an IP sample does not have a corresponding Input control, set ControlName to NoControl.

7. Final Notes

Adhering to these guidelines ensures that your omics metadata can be processed reliably by Trovomics and the underlying R scripts. Properly formatted CSV files avoid errors, streamlines your analysis workflow, and reduces troubleshooting steps.

If you have any questions or encounter persistent validation failures, please consult our user support resources at support@trovomics.com

Thank you for helping us maintain a robust and efficient environment for your omics research. We look forward to supporting your scientific discoveries!()