################################################################################
#  FAIRaman – Project and Experiment-Level Metadata Template
#  Version : 1.1  |  Compatible with FAIRaman v0.1.1+
#  GitHub  : https://github.com/Maugeri-Nanomed-Lab/FAIRaman
#
#  PURPOSE
#  -------
#  This file defines metadata that is COMMON TO ALL SPECTRA in the dataset.
#  All fields here are applied uniformly to every spectrum loaded by FAIRaman.py.
#  It covers the PROJECT (Investigation) and ENTRY (Assay) layers of the schema.
#
#  For per-spectrum SAMPLE metadata (sample_id, donor_id, diagnosis, etc.) use
#  the companion Excel file:  FAIRaman_metadata_template.xlsx  (sheet: DATA)
#
#  USE RULES
#  ------------
#  • Lines starting with '#' are comments – ignored by FAIRaman.py
#  • Each field follows the pattern:   field_name: value
#  • Leave the value EMPTY (field_name: ) if the information is not available
#  • Dates must follow ISO 8601:  YYYY-MM-DD  or  YYYY-MM-DDTHH:MM:SS
#  • Do NOT delete field lines – the parser expects the full schema
#  • ENTRY/data descriptors (spectral_count, nx, ny, n_wavenumbers) are derived
#    automatically from the dataset shape and are NOT listed here
#
################################################################################


################################################################################
#  GROUP 1 – PROJECT  (ISA: Investigation)
#  Stored in HDF5 group:  /PROJECT  (NXcollection)
################################################################################

# [M] Short human-readable name for this study / dataset
project_name: 

# [M] Unique identifier for the project (e.g. grant number, internal code)
project_id: 

# [R] Funding source(s), comma-separated
funding: 

# [R] Governance reference(s), comma-separated
governance_reference: 

# [M] Full name of the primary responsible author / data steward
author: 

# [R] Persistent identifier of the author (ORCID preferred)
#     Format:  0000-0000-0000-0000
author_id: 

# [M] Data license governing reuse of this dataset
#     Recommended values:
#       CC BY 4.0          – Attribution
#       CC BY-NC 4.0       – Attribution, Non-Commercial
#       CC0 1.0            – Public Domain
#       proprietary        – restricted use, contact author
data_license: 

# [M] Accessibility status of the dataset
#     Allowed values: open | restricted | embargoed | closed
accessibility: 

# [R] Comma-separated (or semicolon-separated) keywords describing the content
#     Example: breast cancer, FFPE, Raman spectroscopy, diagnosis
keywords: 


################################################################################
#  GROUP 2 – ENTRY  (ISA: Assay – acquisition parameters)
#  Stored in HDF5 group:  /ENTRY  (NXentry, definition NXraman)
#  These fields describe the acquisition common to ALL spectra in this file.
################################################################################

# [M] Type of experiment, per the NXraman application definition
experiment_type: 

# [R] Acquisition mode of the measurement
#     Allowed values: single | map | timeseries
run_type: 

# [R] Nature of the data encoded
#     Allowed values: experimental | simulated | derived
data_type: 

# Note: ENTRY.title and ENTRY.start_time are autogenerated per spectrum
#       from the source file and do not need to be set here.


################################################################################
#  GROUP 2a – ENTRY / measurement
#  Stored in HDF5 group:  /ENTRY/measurement  (NXcollection)
################################################################################

# [R] Integration time of a single acquisition (numeric value only)
exposure_time: 

# [R] Unit in which exposure_time is expressed  (e.g. sec)
exposure_time_units: 

# [R] Material of the support on which the sample is deposited  (e.g. CaF2)
substrate: 

# [R] Number of consecutive acquisitions co-added into the final spectrum
accumulation_count: 


################################################################################
#  GROUP 2b – ENTRY / instrument
#  Stored in HDF5 group:  /ENTRY/instrument  (NXinstrument)
#  These fields describe the Raman system used for ALL spectra in this file.
#  If different spectra used different instruments, use per-spectrum Excel fields.
################################################################################

# [M] Instrument name / model
#     If commercial: Manufacturer + Model  (e.g. Renishaw inVia Qontor)
#     If custom-built: describe optical components
instrument_name: 


################################################################################
#  GROUP 2c – ENTRY / instrument / laser
#  Stored in HDF5 group:  /ENTRY/instrument/laser  (NXsource)
################################################################################

# [M] Excitation laser wavelength in nm  (numeric value only)
laser_wavelength: 

# [M] Unit for laser wavelength  (always: nm)
wavelength_units: 

# [M] Excitation laser power
laser_power: 

# [M] Unit for laser wavelength  (always: nm)
laser_power_units: 

# [R] Fraction of nominal laser power transmitted to the sample
#     (neutral-density / notch filtering)  e.g. 100%, 10%
laser_filter: 


################################################################################
#  GROUP 2d – ENTRY / instrument / optical_system
#  Stored in HDF5 group:  /ENTRY/instrument/optical_system  (NXoptics)
################################################################################

# [R] Lens (objective) used to collect light
#     Format: Manufacturer, Magnification, NA, Immersion
#     Example: Leica, 50x, 0.75, air
lens: 


################################################################################
#  END OF FILE
#  Save this file and load it in FAIRaman.py as the common metadata TXT.
################################################################################
