Spectra Quickstart
XINA Structs includes dedicated support for spectra data files (or basically any numeric XY data plotting). Spectra data is stored in files attached to event records.
Getting Started
Once the Sandbox Quick Start Guide is complete, you can create a new project with the create project action:
Create Project
Then create a new model in that project:
Create Spectra Database
Finally, create a new event file database to hold the spectra. This is an example using many of the spectra-specific features:
{
"action": "struct_create",
"create": "event",
"type": "file",
"group": "project_name.model_name",
"name": "spectra",
"label": "Spectra",
"desc": "spectra",
"singular": "spectrum",
"plural": "spectra",
"teams": [ "sandbox", "sandbox_dev" ],
"fields": [
{
"name": "test_stage",
"label": "Test Stage",
"type": "asciivstring(64)",
"nul": true
},
{
"name": "group_id",
"label": "Group ID",
"type": "asciivstring(128)",
"nul": true
},
{
"name": "active_mo",
"label": "Active MO",
"type": "asciivstring(8)",
"nul": true
},
{
"name": "active_pa",
"label": "Active PA",
"type": "asciivstring(8)",
"nul": true
},
{
"name": "optical_axis",
"label": "Optical Axis",
"type": "asciivstring(8)",
"nul": true
},
{
"name": "osa_confs",
"label": "OSA Configurations",
"type": "asciivstring(8)",
"nul": true
},
{
"name": "pa_current_sp",
"label": "PA Current Setpoint",
"type": "float(8)",
"unit": "mA",
"nul": true
},
{
"name": "lom_temp",
"label": "LOM Temperature",
"type": "float(8)",
"unit": "C",
"nul": true
},
{
"name": "peak_wavelength",
"label": "Peak Wavelength",
"type": "float(8)",
"unit": "nm",
"nul": true
},
{
"name": "peak_amplitude",
"label": "Peak Amplitude",
"type": "float(8)",
"unit": "dBm",
"nul": true
},
{
"name": "sidemode_lo_wavelength",
"label": "Sidemode Lo Wavelength",
"type": "float(8)",
"unit": "nm",
"nul": true
},
{
"name": "sidemode_lo_amplitude",
"label": "Sidemode Lo Amplitude",
"type": "float(8)",
"unit": "dBm",
"nul": true
},
{
"name": "sidemode_hi_wavelength",
"label": "Sidemode Hi Wavelength",
"type": "float(8)",
"unit": "nm",
"nul": true
},
{
"name": "sidemode_hi_amplitude",
"label": "Sidemode Hi Amplitude",
"type": "float(8)",
"unit": "dBm",
"nul": true
}
],
"conf": {
"spectrum": {
"charts": {
"summary": {
"x": [
"t_start",
"t_end",
"$groupRelativeTime",
"$groupIndex",
"lom_temp",
"pa_current_sp",
"$id"
],
"y": [
"peak_wavelength",
"peak_amplitude",
"sidemode_lo_wavelength",
"sidemode_lo_amplitude",
"sidemode_hi_wavelength",
"sidemode_hi_amplitude"
]
},
"spectrum": {
"x": [
{
"field": "Wavelength (nm)",
"label": "Wavelength (nm)",
"source": "file"
},
{
"field": "Spectral Width About Peak (GHz)",
"label": "Spectral Width About Peak (GHz)",
"source": "file"
}
],
"y": [
{
"field": "Amplitude (dBm)",
"label": "Amplitude (dBm)",
"source": "file"
},
{
"field": "Out of Band (%)",
"label": "Out of Band (%)",
"source": "file"
}
]
}
},
"filters": [
{
"name": "fast",
"label": "Fast",
"desc": "Fast",
"color": "green",
"checks": [
{
"field": "optical_axis",
"value": "fast"
}
]
},
{
"name": "slow",
"label": "Slow",
"desc": "Slow",
"color": "red",
"checks": [
{
"field": "optical_axis",
"value": "slow"
}
]
},
{
"name": "narrow",
"label": "Narrow",
"desc": "Narrow",
"color": "purple",
"checks": [
{
"field": "osa_confs",
"value": "narrow"
}
]
},
{
"name": "wide",
"label": "Wide",
"desc": "Wide",
"color": "orange",
"checks": [
{
"field": "osa_confs",
"value": "wide"
}
]
}
],
"grouping": [
"t_start",
"group_id",
"test_stage",
"active_mo",
"active_pa",
"optical_axis",
"osa_confs",
"pa_current_sp"
]
}
}
}
There's a happening here, so we can unpack in sections.
Basic Database Parameters
{
"action": "struct_create",
"create": "event",
"type": "file",
"group": "project_name.model_name",
"name": "spectra",
"label": "Spectra",
"desc": "spectra",
"singular": "spectrum",
"plural": "spectra",
"teams": [ "sandbox", "sandbox_dev" ]
}
This is the basic database configuration. The "type": "file" indicates each record will have an associated file (the spectrum data). The "teams" determines which users have read/write access to the database, and may need to be different depending on the XINA environment.
Custom Fields
{
"fields": [
{
"name": "test_stage",
"label": "Test Stage",
"type": "asciivstring(64)"
},
{
"name": "group_id",
"label": "Group ID",
"type": "asciivstring(128)",
"nul": true
},
{
"name": "active_mo",
"label": "Active MO",
"type": "asciivstring(8)",
"nul": true
},
{
"name": "active_pa",
"label": "Active PA",
"type": "asciivstring(8)",
"nul": true
},
{
"name": "optical_axis",
"label": "Optical Axis",
"type": "asciivstring(8)",
"nul": true
},
{
"name": "osa_confs",
"label": "OSA Configurations",
"type": "asciivstring(8)",
"nul": true
},
{
"name": "pa_current_sp",
"label": "PA Current Setpoint",
"type": "float(8)",
"unit": "mA",
"nul": true
},
{
"name": "lom_temp",
"label": "LOM Temperature",
"type": "float(8)",
"unit": "C",
"nul": true
},
{
"name": "peak_wavelength",
"label": "Peak Wavelength",
"type": "float(8)",
"unit": "nm",
"nul": true
},
{
"name": "peak_amplitude",
"label": "Peak Amplitude",
"type": "float(8)",
"unit": "dBm",
"nul": true
},
{
"name": "sidemode_lo_wavelength",
"label": "Sidemode Lo Wavelength",
"type": "float(8)",
"unit": "nm",
"nul": true
},
{
"name": "sidemode_lo_amplitude",
"label": "Sidemode Lo Amplitude",
"type": "float(8)",
"unit": "dBm",
"nul": true
},
{
"name": "sidemode_hi_wavelength",
"label": "Sidemode Hi Wavelength",
"type": "float(8)",
"unit": "nm",
"nul": true
},
{
"name": "sidemode_hi_amplitude",
"label": "Sidemode Hi Amplitude",
"type": "float(8)",
"unit": "dBm",
"nul": true
}
}
}
These are the custom fields to include in the database, which will be used in addition to the default event database fields. A value for each field must be provided, unless "nul" is set to true.
Spectra Configuration
{
"conf": {
"spectrum": {
"charts": {
"summary": {
"x": [
"t_start",
"t_end",
"$groupRelativeTime",
"$groupIndex",
"lom_temp",
"pa_current_sp",
"$id"
],
"y": [
"peak_wavelength",
"peak_amplitude",
"sidemode_lo_wavelength",
"sidemode_lo_amplitude",
"sidemode_hi_wavelength",
"sidemode_hi_amplitude"
]
},
"spectrum": {
"x": [
{
"field": "Wavelength (nm)",
"label": "Wavelength (nm)",
"source": "file"
},
{
"field": "Spectral Width About Peak (GHz)",
"label": "Spectral Width About Peak (GHz)",
"source": "file"
}
],
"y": [
{
"field": "Amplitude (dBm)",
"label": "Amplitude (dBm)",
"source": "file"
},
{
"field": "Out of Band (%)",
"label": "Out of Band (%)",
"source": "file"
}
]
}
},
"filters": [
{
"name": "fast",
"label": "Fast",
"desc": "Fast",
"color": "green",
"checks": [
{
"field": "optical_axis",
"value": "fast"
}
]
},
{
"name": "slow",
"label": "Slow",
"desc": "Slow",
"color": "red",
"checks": [
{
"field": "optical_axis",
"value": "slow"
}
]
},
{
"name": "narrow",
"label": "Narrow",
"desc": "Narrow",
"color": "purple",
"checks": [
{
"field": "osa_confs",
"value": "narrow"
}
]
},
{
"name": "wide",
"label": "Wide",
"desc": "Wide",
"color": "orange",
"checks": [
{
"field": "osa_confs",
"value": "wide"
}
]
}
],
"grouping": [
"t_start",
"group_id",
"test_stage",
"active_mo",
"active_pa",
"optical_axis",
"osa_confs",
"pa_current_sp"
]
}
}
}
Finally, the "conf" object contains the information required for XINA to interpret the event database as a spectra database. This contains three sections.
Charts
The charts section contains two subsections, "summary", and "spectra". The summary chart is displayed on the top of the Spectra Tool and plots one data point per spectrum. The configuration specifies the fields which should be listed as selectable options for the X and Y axes. This can include any of the event database default fields and/or custom fields. It also may include macros, indicated by starting with the $ character. These add additional logic and are implemented in the spectra tool itself.
The spectra chart is displayed at the bottom of the tool, and plots the full set of data for each selected spectrum. The options for each axis must be defined here to be correctly located in the associated file.
Other Features
The "filters" section defines filter options that will appear on the spectra tool, and the "grouping" option defines which fields should be available as options to create spectra groupings in the summary chart. More info on other settings is available here.
Spectrum Data Files
The spectrum files may either use a JSON format or DSV format. More formats may be added in the future.