Part 3 – Filename Conventions and Formats

The full and simple filename conventions specified in Table 3.1 provide a consistent format for encoding key metadata into filenames, supporting traceability, metadata parsing, and long-term interoperability.

Each filename follows a defined format, built from metadata-coded segments with standardized prefixes (see Table 3.2). These are recommended filename standards designed for reliable parsing regardless of segment order, corresponding to required metadata fields described in Part 4. The spectrometer software will automatically append a measurement index (IDX) to the end of each filename—no additional text should be added after the IDX.

Filename formats differ slightly depending on the type of target material (i.e., targetClass; see Table 4.5). For white and black-background targets, the projectId (PI) and sessionId (SI) are key segments for traceability and the SI is also critical for linking to all associated tissue measurements via the tissue full filename. For tissues, the full filename convention also includes the minimum session-level, specimen-level, and tissue-level metadata needed for confident data aggregation.

A simplified filename convention may be used during measurement sessions to streamline data collection. However, projects should convert all filenames to the full format before archiving or sharing. When using the simplified format for local files, projects should maintain consistent file organization and take precautions to prevent ambiguity.

Filename Components

Table 3.2, below, defines the components of filenames and their direct links to metadata fields. Each segment of the filename follows a specific format, with a standardized prefix that links directly to a required metadata field (see Part 4. These components form the structured conventions shown in Table 3.1 and enable automatic parsing and alignment between spectral files and metadata records.

Table 3.2: Filename Components and Corresponding Metadata Fields.

Cross-reference Table 4.3 for further descriptions of metadata fields.

Code Metadata field Description Example
PI projectId Unique identifier for the spectral measurement project (Table 4.1). PIHUHcoca, PIFagales1
SN sessionId A unique identifier generated from date/time when the session begins (SNYYYYMMDDHHMM; (Table 4.1). SN202406180932
BG backgroundClass Enumerated code from Background Class Codes (Table 4.3). BGB, BGP, BGO
HC herbariumCode Herbarium acronym or collection identifier (Table 4.2). HCGH, HCINPA
SI specimenId Specimen ID (GUID, barcode, accession no., collector name + number; Table 4.2). SI03774853, SIThorne24070
TC targetClass Enumerated code from Target Class Codes (Table 4.3). TCAD, TCAB, TCW, TCP, TCB
TN targetTissueId Index tracking measured tissue units (e.g., 1, 2, …; Table 4.3). TN1, TN2
IDX measurementIndex Auto-appended by spectrometer software (Table 4.3). 0001, 0002
CC BY 4.0 — IHerbSpec Protocol. DOI: 10.5281/zenodo.15849668