How to Use the Reader¶
Input Files¶
The reader requires specific input files for its operation. These files are typically generated by the experiment instrument and include an ELN file with user-provided metadata or an ELN schema file to write your metadata via NOMAD. Below, we discuss the input files and how they are used in different situations.
The reader primarily requires three types of input files:
Raw Data File¶
The raw data file is generated by the instrument's software. These files may contain measured data, instrument setup, and some metadata, but not all required information may be present. The metadata and instrument setup information required by the NeXus application definition can be supplied via the ELN file.
Experiment bias spectroscopy
Saved Date 20.04.2023 14:55:09
User
Date
X (m) 153.514E-9
Y (m) -93.4937E-9
Z (m) 62.8795E-9
Z offset (m) 0E+0
Settling time (s) 2E-3
Integration time (s) 1E-3
Z-Ctrl hold TRUE
Final Z (m) N/A
Start time 20.04.2023 14:53:33
Filter type Gaussian
Order 15
Cutoff frq
Bias>Bias (V) -50E-3
Bias>Calibration (V/V) 1E+0
Bias>Offset (V) 0E+0
Bias Spectroscopy>Sweep Start (V) -50E-3
Bias Spectroscopy>Sweep End (V) 50E-3
Bias Spectroscopy>Num Pixel 2048
Bias Spectroscopy>Z Avg time (s) 50E-3
Bias Spectroscopy>Z offset (m) 0E+0
Bias Spectroscopy>1st Settling time (s) 5E-3
Bias Spectroscopy>Settling time (s) 2E-3
Bias Spectroscopy>Integration time (s) 1E-3
Bias Spectroscopy>End Settling time (s) 5E-3
Bias Spectroscopy>Z control time (s) 200E-3
Bias Spectroscopy>Max Slew rate (V/s) Inf
Bias Spectroscopy>backward sweep FALSE
Bias Spectroscopy>Z-controller hold TRUE
Bias Spectroscopy>Number of sweeps 10
Bias Spectroscopy>Channels Current (A);Temperature 1 (K);Bias (V);LI Demod 1 X (A);LI Demod 1 Y (A);LI Demod 2 X (A);LI Demod 2 Y (A)
Bias Spectroscopy>Reset Bias TRUE
Bias Spectroscopy>Record final Z FALSE
Bias Spectroscopy>Lock-In run FALSE
Current>Current (A) -266.337E-12
Current>Calibration (A/V) 1E-9
Current>Offset (A) -113.25E-15
Current>Gain LN 10^9
Kelvin Controller>Demodulation/Control signal OC M1 Freq. Shift (Hz)
Kelvin Controller>AC mode TRUE
Kelvin Controller>Bias modulation on/off FALSE
Kelvin Controller>Bias modulation frequency (Hz) 938E+0
Kelvin Controller>Bias modulation phase (deg) 0E+0
Kelvin Controller>Bias modulation amplitude (V) 500E-3
Kelvin Controller>Setpoint 0E+0
Kelvin Controller>Demodulation/Control amplitude 0E+0
Kelvin Controller>Kelvin Controller on/off FALSE
Kelvin Controller>Slope -1
Kelvin Controller>P gain 100E-3
Kelvin Controller>Time constant (s) 10E-3
Kelvin Controller>Bias upper limit (V) 10E+0
Kelvin Controller>Bias lower limit (V) -10E+0
Lock-in>Lock-in status ON
Lock-in>Modulated signal Bias (V)
Lock-in>Frequency (Hz) 1E+3
Lock-in>Amplitude 2E-3
Lock-in>Demodulated signal Current (A)
Lock-in>HP Filter Cutoff D1 (Hz) 9.71405E+0
Lock-in>HP Filter Cutoff D2 (Hz) 9.71405E+0
Lock-in>HP Filter Order D1 OFF
Lock-in>HP Filter Order D2 OFF
Lock-in>Harmonic D1 1
Lock-in>Harmonic D2 2
Lock-in>Reference phase D1 (deg) 103.281E+0
Lock-in>Reference phase D2 (deg) 40.6287E+0
Lock-in>LP Filter Cutoff D1 (Hz) 621.699E+0
Lock-in>LP Filter Cutoff D2 (Hz) 621.699E+0
Lock-in>LP Filter Order D1 OFF
Lock-in>LP Filter Order D2 OFF
Lock-in>Sync Filter D1 ON
Lock-in>Sync Filter D2 ON
NanonisMain>Session Path D:\Data\20230419
NanonisMain>SW Version Generic 5
NanonisMain>UI Release 7856
NanonisMain>RT Release 7856
NanonisMain>RT Frequency (Hz) 20E+3
NanonisMain>Signals Oversampling 10
NanonisMain>Animations Period (s) 20E-3
NanonisMain>Indicators Period (s) 300E-3
NanonisMain>Measurements Period (s) 500E-3
Oscillation Control>differential input TRUE
Oscillation Control>input 1/10 FALSE
Oscillation Control>Input Calibration (m/V) 120E-9
Oscillation Control>Input Range (m) 10.3268E-9
Oscillation Control>Center Frequency (Hz) 25.0228E+3
Oscillation Control>Range (Hz) 305.176E+0
Oscillation Control>Demod 1 Input 0
Oscillation Control>Demod 2 Input 0
Oscillation Control>Demod 3 Input 0
Oscillation Control>Demod 4 Input 0
Oscillation Control>Demod 1 Frequency 0
Oscillation Control>Demod 2 Frequency 0
Oscillation Control>Demod 3 Frequency 0
Oscillation Control>Demod 4 Frequency 0
Oscillation Control>Demod 1 Reference Phase (deg) 73.55E+0
Oscillation Control>Demod 2 Reference Phase (deg) 0E+0
Oscillation Control>Demod 3 Reference Phase (deg) 0E+0
Oscillation Control>Demod 4 Reference Phase (deg) 0E+0
Oscillation Control>Demod 1 Cut off frq (Hz) 777
Oscillation Control>Demod 2 Cut off frq (Hz) 1.55k
Oscillation Control>Demod 3 Cut off frq (Hz) 1.55k
Oscillation Control>Demod 4 Cut off frq (Hz) 1.55k
Oscillation Control>Demod 1 Harmonic 1
Oscillation Control>Demod 2 Harmonic 1
Oscillation Control>Demod 3 Harmonic 1
Oscillation Control>Demod 4 Harmonic 1
Oscillation Control>Demod 1 Filter Order 2
Oscillation Control>Demod 2 Filter Order 2
Oscillation Control>Demod 3 Filter Order 2
Oscillation Control>Demod 4 Filter Order 2
Oscillation Control>Phase P gain (Hz/rad) 1.74535E+0
Oscillation Control>Phase I gain (Hz/rad/s) 324.603E+0
Oscillation Control>Phase controller on FALSE
Oscillation Control>FrequencyShift (Hz) 0E+0
Oscillation Control>Amplitude Setpoint (m) 300E-12
Oscillation Control>Amplitude P gain (V/nm) 421.415E+6
Oscillation Control>Amplitude I gain (V/nm/s) 78.3758E+9
Oscillation Control>Amplitude controller on FALSE
Oscillation Control>Excitation (V) 200E-3
Oscillation Control>output divider 2
Oscillation Control>output off FALSE
Oscillation Control>output add FALSE
Oscillation Control>PLL-Setup Q-Factor 933E+0
Oscillation Control>PLL-Setup Demod. Bandwidth Amp (Hz) 50.9109E+0
Oscillation Control>PLL-Setup Demod. Bandwidth Pha (Hz) 100.001E+0
Oscillation Control>PLL-Setup amplitude/excitation (m/V) 9.009E-9
Piezo Configuration>Active Calib. LHe
Piezo Configuration>Calib. X (m/V) 3.8E-9
Piezo Configuration>Calib. Y (m/V) 3.8E-9
Piezo Configuration>Calib. Z (m/V) 900E-12
Piezo Configuration>HV Gain X 10
Piezo Configuration>HV Gain Y 10
Piezo Configuration>HV Gain Z 10
Piezo Configuration>Tilt X (deg) -1.59502
Piezo Configuration>Tilt Y (deg) -1.86705
Piezo Configuration>Curvature radius X (m) Inf
Piezo Configuration>Curvature radius Y (m) Inf
Piezo Configuration>2nd order corr X (V/m^2) 0E+0
Piezo Configuration>2nd order corr Y (V/m^2) 0E+0
Piezo Configuration>Drift X (m/s) 0E+0
Piezo Configuration>Drift Y (m/s) 0E+0
Piezo Configuration>Drift Z (m/s) 0E+0
Piezo Configuration>Drift correction status (on/off) FALSE
Scan>Scanfield 153.414E-9;-93.5414E-9;4E-9;4E-9;59E+0
Scan>series name Au_mica_2023_Y_A_diPAMY_154-211C_370C_1min_385C_30min_400C_1min_400C_30min_415_30min_430_30min_11min_30min_30min_20230419_
Scan>channels Current (A);Z (m);LI Demod 1 X (A);LI Demod 2 X (A);LI Demod 2 Y (A)
Scan>pixels/line 256
Scan>lines 256
Scan>speed forw. (m/s) 19.5312E-9
Scan>speed backw. (m/s) 19.5312E-9
Temperature 1>Temperature 1 (K) 2.4591E+0
Temperature 2>Temperature 2 (K) 518.113E+0
Z-Controller>Z (m) 62.8495E-9
Z-Controller>Controller name log Current
Z-Controller>Controller status OFF
Z-Controller>Setpoint 25E-12
Z-Controller>Setpoint unit A
Z-Controller>P gain 3.514E-12
Z-Controller>I gain 34.7921E-9
Z-Controller>Time const (s) 101E-6
Z-Controller>TipLift (m) 0E+0
Z-Controller>Switch off delay (s) 50E-3
[DATA]
Bias calc (V) Current (A) Temperature 1 (K) Bias (V) LI Demod 1 X (A) LI Demod 1 Y (A) LI Demod 2 X (A) LI Demod 2 Y (A) Current (A) [filt] Temperature 1 (K) [filt] Bias (V) [filt] LI Demod 1 X (A) [filt] LI Demod 1 Y (A) [filt] LI Demod 2 X (A) [filt] LI Demod 2 Y (A) [filt]
-5.0000001E-2 -1.4288776E-10 1.6252118E+0 -5.0000001E-2 -2.9149552E-12 -2.4001521E-12 3.1361282E-13 -1.8262286E-13 -1.4288776E-10 1.6252118E+0 -5.0000001E-2 -2.9149552E-12 -2.4001521E-12 3.1361282E-13 -1.8262286E-13
-4.9951147E-2 -1.4346191E-10 1.6252102E+0 -4.9951147E-2 -2.1446237E-12 -3.7221532E-12 2.7779610E-15 7.4294073E-14 -1.4283737E-10 1.6252118E+0 -4.9951147E-2 -2.8900049E-12 -2.4669932E-12 2.7973671E-13 -1.6016545E-13
-4.9902298E-2 -1.4369876E-10 1.6252074E+0 -4.9902298E-2 -3.1126282E-12 -2.9193852E-12 3.3682909E-13 -1.6808104E-13 -1.4278936E-10 1.6252117E+0 -4.9902298E-2 -2.8549446E-12 -2.5168639E-12 2.4648721E-13 -1.4606629E-13
-4.9853444E-2 -1.4269953E-10 1.6252105E+0 -4.9853444E-2 -2.4439749E-12 -3.6114013E-12 1.9321609E-13 3.9136714E-13 -1.4273145E-10 1.6252117E+0 -4.9853444E-2 -2.8326918E-12 -2.5816437E-12 2.0376618E-13 -1.2110958E-13
-4.9804594E-2 -1.4261047E-10 1.6252066E+0 -4.9804594E-2 -2.6221989E-12 -3.9465770E-12 -9.4475019E-14 -1.0480260E-13 -1.4267816E-10 1.6252116E+0 -4.9804594E-2 -2.7935152E-12 -2.6488798E-12 1.6995072E-13 -9.7163427E-14
-4.9755741E-2 -1.4316516E-10 1.6252112E+0 -4.9755741E-2 -2.4876841E-12 -2.9806431E-12 -2.7913430E-13 1.6931428E-13 -1.4260229E-10 1.6252116E+0 -4.9755741E-2 -2.7822991E-12 -2.6910390E-12 1.3847052E-13 -7.6341406E-14
-4.9706887E-2 -1.4259369E-10 1.6252110E+0 -4.9706887E-2 -2.7327786E-12 -3.0913913E-12 -7.9897535E-14 3.1888492E-13 -1.4255383E-10 1.6252115E+0 -4.9706887E-2 -2.7431282E-12 -2.7671955E-12 1.0305365E-13 -6.5633967E-14
-4.9658038E-2 -1.4291839E-10 1.6252106E+0 -4.9658038E-2 -3.0599520E-12 -3.5767652E-12 1.4754625E-13 2.2160633E-13 -1.4247856E-10 1.6252115E+0 -4.9658038E-2 -2.7447489E-12 -2.8158706E-12 6.9952826E-14 -5.2967010E-14
-4.9609184E-2 -1.4325488E-10 1.6252133E+0 -4.9609184E-2 -2.1475129E-12 -3.0740519E-12 1.0480270E-14 -5.3811529E-13 -1.4240342E-10 1.6252115E+0 -4.9609184E-2 -2.7114001E-12 -2.8732819E-12 4.8344490E-14 -4.0015293E-14
-4.9560335E-2 -1.4213530E-10 1.6252133E+0 -4.9560335E-2 -3.4582190E-12 -3.0836609E-12 -3.9569209E-14 -4.4774216E-14 -1.4231331E-10 1.6252114E+0 -4.9560335E-2 -2.7038020E-12 -2.9321107E-12 1.8490218E-14 -2.4028151E-14
... 2038 further data rows are omitted in this documentation excerpt; the complete file is in the repository.
{'/Experiment/value': 'bias spectroscopy',
'/Saved Date/value': '20.04.2023 14:55:09',
'/value': '[DATA]',
'/X/unit': 'm',
'/X/value': '153.514E-9',
'/Y/unit': 'm',
'/Y/value': '-93.4937E-9',
'/Z/unit': 'm',
'/Z/value': '62.8795E-9',
'/Z offset/unit': 'm',
'/Z offset/value': '0E+0',
'/Settling time/unit': 's',
'/Settling time/value': '2E-3',
'/Integration time/unit': 's',
'/Integration time/value': '1E-3',
}
A FLT file written by Bruker SPMLab (version 1.00) is a binary file that starts with an INI style text header; the image data follows the header directly after the byte given by the header key DataOffset. Each FLT file holds one channel (here Height, given by the header key DataName) of one scan direction (here FORWARD).
After parsing the raw data file it will be formatted as (only a small part of the formatted data is shown here; the channel name prefixes all data keys): {'/source_format': 'spmlabf',
'/Height/name': 'Height',
'/Height/data': 'array([[1.86168599e-06, 1.86174940e-06, ...]])',
'/Height/data/@unit': 'm',
'/Height/x_real': 1e-06,
'/Height/x_real/@unit': 'm',
'/Height/y_real': 1e-06,
'/Height/y_real/@unit': 'm',
'/Height/meta/Mode': 'Peak Force Tapping',
'/Height/meta/ScanDirection': 'FORWARD',
'/Height/meta/SetPoint': '0.030000',
'/Height/meta/SetPoint/@unit': 'V',
'/Height/header/Data Version/Program': 'SPMLab',
'/Height/header/Data Version/Version': '1.00',
'/Height/header/Data Parameters/DataName': 'Height',
'/Height/header/Data Parameters/DataID': 'SIG_TOPO',
}
A .spm file written by Bruker NanoScope (version 9.x, here a Dimension Icon) starts with an ASCII header - the \Key: value lines up to \*File list end - and continues with the binary image block of every recorded channel. One file therefore holds all channels in both scan directions, exposed as /<Channel>/forward and /<Channel>/backward (Trace becomes forward, Retrace becomes backward).
After parsing the raw data file it will be formatted as (only a small part of the formatted data is shown here): {'/Scan_list': ['Height_Sensor/forward', 'Height_Sensor/backward',
'Amplitude_Error/forward', 'Phase/backward', ...],
'/Height_Sensor/forward': 'array of shape (512, 512)',
'/Height_Sensor/backward': 'array of shape (512, 512)',
'/Phase/forward': 'array of shape (512, 512)',
'/Scan/Height_Sensor/forward/@2:Image_Data': 'S [ZSensor] "Height Sensor"',
'/Scan/Height_Sensor/forward/Line_Direction': 'Trace',
'/Scan/Height_Sensor/forward/Scan_Size': '20 20 ~m',
'/Scan/Height_Sensor/forward/Samps/line': '512',
'/Scanner_list/0/Scan_Size': '20000',
'/Scanner_list/0/Scan_Size/@unit': 'nm',
'/Scanner_list/0/X_Offset': '0',
'/Scanner_list/0/Aspect_Ratio': '1:1',
}
A .spm.txt file is the NanoScope ASCII export of a force ramp. Every line is wrapped in double quotes: a "\Key: value" header terminated by "\*Force file list end", followed by a tab-separated column header and the numeric columns. The extend (approach) and retract halves of the ramp carry the suffixes _Ex and _Rt, and the physical unit is part of the column name.
After parsing the raw data file it will be formatted as (only a small part of the formatted data is shown here; array units are stored under the /unit suffix): {'/Calc_Ramp_Ex_nm': 'array of shape (9728,)',
'/Calc_Ramp_Ex_nm/unit': 'nm',
'/Calc_Ramp_Rt_nm': 'array of shape (9728,)',
'/Defl_pN_Ex': 'array of shape (9728,)',
'/Defl_pN_Ex/unit': 'pN',
'/Height_Sensor_nm_Ex': 'array of shape (9728,)',
'/Height_Sensor_nm_Ex/unit': 'nm',
'/Force_file_list/0/Date': '03:44:35 PM Mon May 15 2023',
'/Ciao_scan_list/0/Samps/line': '512',
'/Equipment_list/0/Description': 'Dimension Icon',
}
ELN Schema File¶
A YAML schema file (with an extension .scheme.archive.yaml) contains the schema structure according to the NeXus application definition and some operational metadata for NOMAD. NOMAD reads this schema file and creates an archive file (with an extension .archive.json). Later, NOMAD renders a GUI representing the archive file, where users can fill metadata corresponding to the NeXus schema. NOMAD then generates a structured YAML file (another type of ELN file with an extension .yaml) that collects the user-provided data. The final ELN file (with an extension .yaml) is read by reader, and the data is written to the NeXus file. For a visualization of this process, follow the Drag and Drop Example in NOMAD in Use Reader in NOMAD.
In the tabbed window below, an example ELN schema file for an STS experiment is shown. The schema is designed according to the NeXus application definition NXsts. The schema file contains all required metadata fields that are not supplied by the raw file but are required by the NXsts application definition. Tabs from left to right show the schema file, the generated archive file, the graphical representation of the archive file in NOMAD, and the final ELN file (with the extension .yaml).
definitions:
name: "STS_ELN_Example"
eln:
label: "STS ELN Example"
sections:
ELN_for_STS:
base_sections:
- pynxtools.nomad.schema_packages.dataconverter.NexusDataConverter
- nomad.datamodel.data.EntryData
m_annotations:
template:
reader: spm
nxdl: NXsts
eln:
hide: []
label: "ELN for STS"
quantities:
default:
type: str
m_annotations:
eln:
component: StringEditQuantity
description: |
The name of the NXdata group that comes as child of the entry group for default plot visualization
to be displayed upon the entry of NeXus file.
definition:
type:
type_kind: Enum
type_data:
- NXsts
m_annotations:
eln:
component: EnumEditQuantity
description: |
Name of the definitions from NeXus app def designed for STS experiments, one can use
NXsts or NXspm, but NXsts is recommended.
experiment_technique:
type:
type_kind: Enum
type_data:
- STS
m_annotations:
eln:
component: EnumEditQuantity
description: |
Name of the technique used for the experiment, e.g. STS.
experiment_description:
type: str
m_annotations:
eln:
component: RichTextEditQuantity
description: |
Descriptive comments for this experiment, added by the experimenter in eln or
coming from the output file, e.g. Comment01 SYNC & Filter LP 8order WITHDRAW
600 steps, locked Au(111), 50pA, 100 mV set point, 1mV DCA, 973Hz,138
1st H, -84 2nd H.
identifier_experiment:
type: str
m_annotations:
eln:
component: StringEditQuantity
description: |
An unique identifier fot the experiment. e.g. the identifier
could be specific for a lab or experiment team.
identifier_collection:
type: str
m_annotations:
eln:
component: StringEditQuantity
description: |
An unique identifier of a collection. Use this
if the experiment if part of a collection of experiments
sub_sections:
User:
section:
m_annotations:
eln:
overview: true
quantities:
name:
type: str
m_annotations:
eln:
component: StringEditQuantity
description: |
Name of the user who performed the experiment.
affiliation:
type: str
shape: "*"
m_annotations:
eln:
component: StringEditQuantity
description: |
Affiliation of the user who performed the experiment.
email:
type: str
shape: "*"
m_annotations:
eln:
component: StringEditQuantity
description: |
List of emails from users who performed the experiment.
Instrument:
section:
m_annotations:
eln:
overview: true
sub_sections:
hardware:
section:
m_annotations:
eln:
overview: true
quantities:
name:
type: str
m_annotations:
eln:
component: StringEditQuantity
description: |
Name of the hardware. (e.g. Nanonis).
vendor:
type: str
m_annotations:
eln:
component: StringEditQuantity
description: |
Name of the manufacturer of the hardware (e.g. Nanonis).
model:
type: str
m_annotations:
eln:
component: StringEditQuantity
description: |
Version or model of the component named by the manufacturer (e.g. Generic 5e).
model_version:
type: str
m_annotations:
eln:
component: StringEditQuantity
description: |
If model has a distinguishable version (e.g. BP5e).
software:
section:
m_annotations:
eln:
overview: true
quantities:
vendor:
type: str
m_annotations:
eln:
component: StringEditQuantity
description: |
Name of the manufacturer of the software.
name:
type: str
m_annotations:
eln:
component: StringEditQuantity
description: |
Name of the software. (e.g. Nanonis).
model:
type: str
m_annotations:
eln:
component: StringEditQuantity
description: |
Version or model, required to choose correct file parser, of the component named
by the manufacturer (e.g. Generic 5e).
Note that model should be exactly the same as the one in the experiment file.
model_version:
type: str
m_annotations:
eln:
component: StringEditQuantity
description: |
If model has a distinguishable version (e.g. BP5e).
lockin_amplifier:
section:
m_annotations:
eln:
overview: true
quantities:
modulation_signal:
type: str
m_annotations:
eln:
component: StringEditQuantity
description: |
Type of the signal either in voltage or current.
flip_sign:
type: np.float64
m_annotations:
eln:
component: NumberEditQuantity
description: |
The sign (1 or -1) that defines the sign of the lock-in current.
The calibration procedure with retracted tip is normally performed
to compensate for the signal phase delay in SPM. The procedure
yields two possible solutions, this number should be equal to 1 or -1
depending on which solution is chosen (this concept mainly used in
STS experiments, e.g. in Nanonis machine).
Scan_environment:
section:
m_annotations:
eln:
overview: true
quantities:
head_temperature:
type: np.float64
unit: kelvin
m_annotations:
eln:
component: NumberEditQuantity
defaultDisplayUnit: K
description: |
Temperature of STM head. Note: At least one field from head_temperature,
cryo_bottom_temperature and cryo_shield_temperature must be provided.
cryo_bottom_temperature:
type: np.float64
unit: kelvin
m_annotations:
eln:
component: NumberEditQuantity
defaultDisplayUnit: K
description: |
Temperature of the cold tail of the cryostat. Note:
At least one field from head_temperature, cryo_bottom_temperature and cryo_shield_temperature must be provided.
cryo_shield_temperature:
type: np.float64
unit: kelvin
m_annotations:
eln:
component: NumberEditQuantity
defaultDisplayUnit: K
description: |
Temperature of liquid nitrogen shield. Note: At
least one field from head_temperature, cryo_bottom_temperature and cryo_shield_temperature must be provided.
Sample:
section:
m_annotations:
eln:
overview: true
quantities:
name:
type: str
m_annotations:
eln:
component: StringEditQuantity
description: |
Name of the sample.
chemical_formula:
type: str
m_annotations:
eln:
component: StringEditQuantity
description: |
The chemical formula specified using CIF conventions.
Abbreviated version of CIF standard:
* Only recognized element symbols may be used.
* Each element symbol is followed by a 'count' number. A count of '1' may be omitted.
* A space or parenthesis must separate each cluster of (element symbol + count).
* Where a group of elements is enclosed in parentheses, the multiplier for the
group must follow the closing parentheses. That is, all element and group
multipliers are assumed to be printed as subscripted numbers.
* Unless the elements are ordered in a manner that corresponds to their chemical
structure, the order of the elements within any group or moiety depends on
whether or not carbon is present.
* If carbon is present, the order should be:
- C, then H, then the other elements in alphabetical order of their symbol.
- If carbon is not present, the elements are listed purely in alphabetic order of their symbol.
* This is the *Hill* system used by Chemical Abstracts.
description:
type: str
m_annotations:
eln:
component: RichTextEditQuantity
description: |
Description of the sample or sample preparation.
sub_sections:
Sample_component:
section:
m_annotations:
eln:
overview: true
description: |
A sample component is a part of the sample that is of interest.
For example, a sample component could be a layer of a multilayer sample.
quantities:
name:
type: str
m_annotations:
eln:
component: StringEditQuantity
description: |
Name of the sample component.
identifier_component:
type: str
m_annotations:
eln:
component: StringEditQuantity
description: |
An unique identifier for the sample component.
chemical_formula:
type: str
m_annotations:
eln:
component: StringEditQuantity
description: |
The chemical formula specified using CIF conventions.
Abbreviated version of CIF standard:
* Only recognized element symbols may be used.
* Each element symbol is followed by a 'count' number. A count of '1' may be omitted.
* A space or parenthesis must separate each cluster of (element symbol + count).
* Where a group of elements is enclosed in parentheses, the multiplier for the
group must follow the closing parentheses. That is, all element and group
multipliers are assumed to be printed as subscripted numbers.
* Unless the elements are ordered in a manner that corresponds to their chemical
structure, the order of the elements within any group or moiety depends on
whether or not carbon is present.
* If carbon is present, the order should be:
- C, then H, then the other elements in alphabetical order of their symbol.
- If carbon is not present, the elements are listed purely in alphabetic order of their symbol.
* This is the *Hill* system used by Chemical Abstracts.
description:
type: str
m_annotations:
eln:
component: RichTextEditQuantity
description: |
Description of the sample component or sample preparation.
history:
section:
m_annotations:
eln:
overview: true
sub_sections:
Note:
section:
m_annotations:
eln:
overview: true
description: |
Notes about the sample history.
quantities:
description:
type: str
m_annotations:
eln:
component: RichTextEditQuantity
description: |
Title of an image or other details of the note.
quantities:
identifier_history:
type: str
m_annotations:
eln:
component: StringEditQuantity
description: |
Identifier for sample history.
{
"data": {
"m_def": "../upload/raw/sts.scheme.archive.yaml#/definitions/section_definitions/0",
"reader": "spm",
"nxdl": "NXsts",
"input_files": [
"config.json",
"Bias-Spectroscopy00015_20230420.dat"
],
"export": true,
"default": "current_filter_grad",
"definition": "NXsts",
"experiment_technique": "STS",
"experiment_description": "<p>The experiment with</p>\n<p>Bias: -50mA<br />Setpoint: 25pA</p>",
"identifier_experiment": "Au_mica_2023_Y_A_diPAMY_154-211C_370C_1min_385C_30min_400C_1min_400C_30min_415_30min_430_30min_11min_30min_30min_20230416_20230420",
"identifier_collection": "Au_mica_2023_Y_A_diPAMY_154-211C_370C_1min_385C_30min_400C_1min_400C_30min_415_30min_430_30min_11min_30min_30min_20230419",
"User": {
"name": "Yichen Jin",
"affiliation": [
"Rubel Mozumder",
"Dr. Cojal Gonzalez",
"Dr. Carlos-Andres Palma"
],
"email": [
"ycjin@physik.hu-berlin.de",
"rubel.mozumder@physik.hu-berlin.de",
"cojal@physik.hu-berlin.de",
"palma@physik.hu-berlin.de"
]
},
"Instrument": {
"hardware": {
"name": "Nanonis",
"vendor": "Nanonis",
"model": "Generic5",
"model_version": "5"
},
"software": {
"vendor": "Nanonis",
"name": "Nanonis",
"model": "Generic5",
"model_version": "5"
},
"lockin_amplifier": {
"modulation_signal": "Current",
"flip_sign": -1
},
"Scan_environment": {
"head_temperature": 10
}
},
"Sample": {
"name": "diPAMY",
"description": "<div>Substrate:</div>\n<div>Two layers stack: Au-Mica</div>",
"Sample_component": {
"name": "Au(Mica)",
"identifier_component": "Au(KAl3Si3O12H2)",
"description": "<div>Substrate:</div>\n<div>Two layers stack: Au-Mica</div>"
}
}
}
}
Sample:
name: diPAMY
history:
Note:
description: The experiment was run in Carlos' Lab.
Sample_component:
chemical_formula: Au(KAl3Si3O12H2)
description: 'Substrate:
Two layers stack: Au-Mica'
name: Au(Mica)
default: current_filter_grad
definition: NXsts
scan_mode: constant height
experiment_description: 'The experiment with
Bias: -50mA
Setpoint: 25pA'
Instrument:
hardware:
model: Generic5e
model/@version: 5
name: Nanonis
vendor: Nanonis
lockin_amplifier:
flip_sign: -1.0
modulation_signal: Current
Scan_environment:
head_temperature:
unit: K
value: 10.0
software:
model: Generic5e
model/@version: 5
name: Nanonis
vendor: Nanonis
experiment_technique: STS
identifier_collection: Au_mica_2023_Y_A_diPAMY_154-211C_370C_1min_385C_30min_400C_1min_400C_30min_415_30min_430_30min_11min_30min_30min_20230419_
identifier_experiment: Au_mica_2023_Y_A_diPAMY_154-211C_370C_1min_385C_30min_400C_1min_400C_30min_415_30min_430_30min_11min_30min_30min_20230416_20230420
User:
affiliation:
- Rubel Mozumder
- Dr. Cojal González, José David
- Dr. Carlos-Andres Palma
email:
- ycjin@physik.hu-berlin.de
- rubel.mozumder@physik.hu-berlin.de
- cojal@physik.hu-berlin.de
- palma@physik.hu-berlin.de
name: Yichen Jin
ELN YAML File¶
An ELN YAML file is similar to the YAML file (with an extension .yaml) generated by NOMAD from the ELN schema file (with the extension .scheme.archive.yaml). This ELN YAML file also contains the same structure as the application definition but is much simpler than the ELN Schema File. Such a file can be written by the user following the application definition NXsts without the help of NOMAD. This ELN file is only compatible with reader if the reader is invoked via the command-line interface (see Standalone Usages guide).
Sample:
name: diPAMY
history:
Note:
description: The experiment was run in Carlos' Lab.
Sample_component:
chemical_formula: Au(KAl3Si3O12H2)
description: 'Substrate:
Two layers stack: Au-Mica'
name: Au(Mica)
default: current_filter_grad
definition: NXsts
scan_mode: constant height
experiment_description: 'The experiment with
Bias: -50mA
Setpoint: 25pA'
Instrument:
hardware:
model: Generic5e
model/@version: 5
name: Nanonis
vendor: Nanonis
lockin_amplifier:
flip_sign: -1.0
modulation_signal: Current
Scan_environment:
head_temperature:
unit: K
value: 10.0
software:
model: Generic5e
model/@version: 5
name: Nanonis
vendor: Nanonis
experiment_technique: STS
identifier_collection: Au_mica_2023_Y_A_diPAMY_154-211C_370C_1min_385C_30min_400C_1min_400C_30min_415_30min_430_30min_11min_30min_30min_20230419_
identifier_experiment: Au_mica_2023_Y_A_diPAMY_154-211C_370C_1min_385C_30min_400C_1min_400C_30min_415_30min_430_30min_11min_30min_30min_20230416_20230420
User:
affiliation:
- Rubel Mozumder
- Dr. Cojal González, José David
- Dr. Carlos-Andres Palma
email:
- ycjin@physik.hu-berlin.de
- rubel.mozumder@physik.hu-berlin.de
- cojal@physik.hu-berlin.de
- palma@physik.hu-berlin.de
name: Yichen Jin
Config File¶
The config file carries mapping information from raw data to the NeXus Application Definition concepts. The config file follows certain rules for how the raw data will be processed and organized in the NeXus file. It is expected that lab users scrutinize the config file and modify it according to their needs. The file does not need to be modified for the underlying data model according to the application definitions, only for raw data paths.
{
"ENTRY[entry]": {
"@default": { "raw_path": "@default:current_filter" },
"definition": { "@version": "" },
"start_time": {
"raw_path": "/Start time/value"
},
"end_time": {
"raw_path": "/Saved Date/value"
},
"INSTRUMENT[instrument]": {
"lockin_amplifier": {
"modulation_status": {
"raw_path": "/Lock-in/Lock-in status/value"
},
"reference_frequency": {
"raw_path": "/Lock-in/Frequency/value",
"@units": "/Lock-in/Frequency/unit"
},
"modulation_signal": {
"raw_path": "@default:Current"
},
"demodulated_signal": {
"raw_path": "@default:Current"
},
"reference_amplitude": {
"raw_path": "/Lock-in/Amplitude/value",
"@units": "/Lock-in/Modulated signal/Bias/unit"
},
"demodulated_frequency": "",
"demodulated_amplitude": "",
"demodulator_channels": "",
"recorded_channels": "",
"active_channel": {
"raw_path": ""
},
"flip_sign": "",
"low_passN": [
{
"d1": {
"raw_path": "/Lock-in/LP Filter Cutoff D1/value",
"@units": "/Lock-in/LP Filter Cutoff D1/unit"
}
},
{
"d2": {
"raw_path": "/Lock-in/LP Filter Cutoff D2/value",
"@units": "/Lock-in/LP Filter Cutoff D2/unit"
}
}
],
"lp_filter_orderN": [
{
"d1": { "raw_path": "/Lock-in/LP Filter Order D1/value" },
"d2": { "raw_path": "/Lock-in/LP Filter Order D2/value" }
}
],
"high_passN": [
{
"d1": {
"raw_path": "/Lock-in/HP Filter Cutoff D1/value",
"@units": "/Lock-in/HP Filter Cutoff D1/unit"
}
},
{
"d2": {
"raw_path": "/Lock-in/HP Filter Cutoff D2/value",
"@units": "/Lock-in/HP Filter Cutoff D2/unit"
}
}
],
"hp_filter_orderN": [
{ "d1": { "raw_path": "/Lock-in/HP Filter Order D1/value" } },
{ "d2": { "raw_path": "/Lock-in/HP Filter Order D2/value" } }
],
"ref_offset_phaseN[ref_offset_phase_n]": [
{
"d1": {
"raw_path": "/Lock-in/Reference phase D1/value",
"@units": "/Lock-in/Reference phase D1/unit"
}
},
{
"d2": {
"raw_path": "/Lock-in/Reference phase D2/value",
"@units": "/Lock-in/Reference phase D2/unit"
}
}
],
"harmonic_orderN[harmonic_order_n]": [
{ "d1": { "raw_path": "/Lock-in/Harmonic D1/value" } },
{ "d2": { "raw_path": "/Lock-in/Harmonic D2/value" } }
],
"dc_offset_valueN": [
{
"d1": {
"raw_path": "",
"@units": ""
}
},
{
"d2": {
"raw_path": "",
"@units": ""
}
}
]
},
"real_time_controller": {
"fabrication": {
"model": {
"raw_path": "/NanonisMain/RT Release/value"
}
},
"frequency": {
"raw_path": "/NanonisMain/RT Frequency/value",
"@units": "/NanonisMain/RT Frequency/unit"
},
"acquisition_time": {
"raw_path": "/NanonisMain/Acquisition Period/value",
"@units": "/NanonisMain/Acquisition Period/unit"
},
"animation_time": {
"raw_path": "/NanonisMain/Animations Period/value",
"@units": "/NanonisMain/Animations Period/unit"
},
"measurement_time": {
"raw_path": "/NanonisMain/Measurements Period/value",
"@units": "/NanonisMain/Measurements Period/unit"
},
"indication_time": {
"raw_path": "/NanonisMain/Indicators Period/value",
"@units": "/NanonisMain/Indicators Period/unit"
}
},
"bias_spectroscopy_environment": {
"SPM_BIAS_SPECTROSCOPY[bias_spectroscopy]": {
"measurement_type": "",
"SPM_POSITIONER[spm_positioner]": {
"z_controller": {
"feedback_on": {
"raw_path": "/Z-Controller/Controller status/value"
},
"set_point": {
"raw_path": "/Z-Controller/Setpoint/value",
"@units": "/Z-Controller/Setpoint unit/value"
},
"tip_lift": {
"raw_path": "/Z-Controller/TipLift/value",
"@units": "/Z-Controller/TipLift/unit"
},
"z": {
"raw_path": "/Z-Controller/Z/value",
"@units": "/Z-Controller/Z/unit"
},
"K_i": {
"raw_path": "/Z-Controller/I gain/value"
},
"K_p": {
"raw_path": "/Z-Controller/P gain/value"
},
"D_t": {
"raw_path": "/Z-Controller/Time const/value",
"@units": "/Z-Controller/Time const/unit"
},
"controller_label": {
"raw_path": "/Z-Controller/Controller name/value"
},
"z_offset_value": {
"raw_path": "/Bias Spectroscopy/Z offset/value",
"@units": "/Bias Spectroscopy/Z offset/unit"
}
}
},
"BIAS_SWEEP[bias_sweep]": {
"#note": "This group will be handled in _construct_bias_sweep_grp.",
"scan_type": "",
"settling_time": {
"raw_path": "/Bias Spectroscopy/Settling time/value",
"@units": "/Bias Spectroscopy/Settling time/unit"
},
"first_settling_time": {
"raw_path": "/Bias Spectroscopy/1st Settling time/value",
"@units": "/Bias Spectroscopy/1st Settling time/unit"
},
"end_settling_time": {
"raw_path": "/Bias Spectroscopy/End Settling time/value",
"@units": "/Bias Spectroscopy/End Settling time/unit"
},
"max_slew_rate": {
"raw_path": "/Bias Spectroscopy/Max Slew rate/value",
"@units": "/Bias Spectroscopy/Max Slew rate/unit"
},
"final_z": "",
"total_spectroscopy_time": "",
"number_of_sweeps": {
"raw_path": "/Bias Spectroscopy/Number of sweeps/value"
},
"scan_region": {
"scan_range_bias": "",
"scan_offset_bias": {
"raw_path": ["/Bias/Offset/value"],
"@units": "/Bias/Offset/unit"
},
"scan_angleN[scan_angle_n]": "",
"scan_start_bias": {
"raw_path": "/Bias Spectroscopy/Sweep Start/value",
"@units": "/Bias Spectroscopy/Sweep Start/unit"
},
"scan_end_bias": {
"raw_path": "/Bias Spectroscopy/Sweep End/value",
"@units": "/Bias Spectroscopy/Sweep End/unit"
}
},
"linear_sweep": {
"scan_speed": "",
"scan_time": "",
"forward_speedN[forward_speed]": {
"raw_path": "/Scan/speed forw./value",
"@units": "/Scan/speed forw./unit"
},
"backward_speedN[backward_speed]": {
"raw_path": "/Scan/speed backw./value",
"@units": "/Scan/speed backw./unit"
},
"scan_points_bias": {
"raw_path": "/Bias Spectroscopy/Num Pixel/value"
},
"step_size_bias": "",
"reset_bias": "",
"backward_sweep": "",
"DATA[scan_data]": [
{
"data": {
"name": "current",
"raw_path": "/dat_mat_components/LI Demod 1 X/value",
"@units": "/dat_mat_components/LI Demod 1 X/unit",
"@long_name": "Lockin Demod 1X"
},
"0": {
"name": "voltage",
"raw_path": [
"/dat_mat_components/Bias calc/value",
"/dat_mat_components/Bias/value"
],
"@units": [
"/dat_mat_components/Bias calc/unit",
"/dat_mat_components/Bias/unit"
],
"@long_name": "Bias Voltage"
},
"title": { "raw_path": "@default:Lockin Signal 1X" },
"grp_name": "Lockin Demod 1X"
},
{
"data": {
"name": "Lockin Demod 1Y",
"raw_path": "/dat_mat_components/LI Demod 1 Y/value",
"@units": "/dat_mat_components/LI Demod 1 Y/unit"
},
"0": {
"name": "Bias Voltage",
"raw_path": [
"/dat_mat_components/Bias calc/value",
"/dat_mat_components/Bias/value"
],
"@units": [
"/dat_mat_components/Bias calc/unit",
"/dat_mat_components/Bias/unit"
]
},
"title": { "raw_path": "@default:Lockin Signal 1Y" },
"grp_name": "Lockin Demod 1Y"
},
{
"data": {
"name": "Lockin Demod 2X",
"raw_path": "/dat_mat_components/LI Demod 2 X/value",
"@units": "/dat_mat_components/LI Demod 2 X/unit"
},
"0": {
"name": "Bias Voltage",
"raw_path": [
"/dat_mat_components/Bias calc/value",
"/dat_mat_components/Bias/value"
],
"@units": [
"/dat_mat_components/Bias calc/unit",
"/dat_mat_components/Bias/unit"
]
},
"title": { "raw_path": "@default:Lockin Signal 2X" },
"grp_name": "Lockin Demod 2X"
},
{
"data": {
"name": "Lockin Demod 2Y",
"raw_path": "/dat_mat_components/LI Demod 2 Y/value",
"@units": "/dat_mat_components/LI Demod 2 Y/unit"
},
"0": {
"name": "Bias Voltage",
"raw_path": [
"/dat_mat_components/Bias calc/value",
"/dat_mat_components/Bias/value"
],
"@units": [
"/dat_mat_components/Bias calc/unit",
"/dat_mat_components/Bias/unit"
]
},
"title": { "raw_path": "@default:Lockin Signal 2Y" },
"grp_name": "Lockin Demod 2Y"
},
{
"data": {
"name": "Lockin Demod 1X_filter",
"raw_path": "/dat_mat_components/LI Demod 1 X [filt]/value",
"@units": "/dat_mat_components/LI Demod 1 X [filt]/unit"
},
"0": {
"name": "Bias Voltage",
"raw_path": [
"/dat_mat_components/Bias [filt]/value",
"/dat_mat_components/Bias calc/value",
"/dat_mat_components/Bias/value"
],
"@units": [
"/dat_mat_components/Bias calc/unit",
"/dat_mat_components/Bias/unit"
]
},
"title": { "raw_path": "@default:Lockin Demod 1X(filter)" },
"grp_name": "Lockin_Demod_1X_filter"
},
{
"data": {
"name": "Lockin Demod 1Y_filter",
"raw_path": "/dat_mat_components/LI Demod 1 Y [filt]/value",
"@units": "/dat_mat_components/LI Demod 1 Y [filt]/unit"
},
"0": {
"name": "Bias Voltage",
"raw_path": [
"/dat_mat_components/Bias [filt]/value",
"/dat_mat_components/Bias calc/value",
"/dat_mat_components/Bias/value"
],
"@units": [
"/dat_mat_components/Bias calc/unit",
"/dat_mat_components/Bias/unit"
]
},
"title": { "raw_path": "@default:Lockin Demod 1Y(filter)" },
"grp_name": "Lockin_Demod_1Y_filter"
},
{
"data": {
"name": "Lockin Demod 2X_filter",
"raw_path": "/dat_mat_components/LI Demod 2 X [filt]/value",
"@units": "/dat_mat_components/LI Demod 2 X [filt]/unit"
},
"0": {
"name": "Bias Voltage",
"raw_path": [
"/dat_mat_components/Bias [filt]/value",
"/dat_mat_components/Bias calc/value",
"/dat_mat_components/Bias/value"
],
"@units": [
"/dat_mat_components/Bias calc/unit",
"/dat_mat_components/Bias/unit"
]
},
"title": { "raw_path": "@default:Lockin Demod 2X(filter)" },
"grp_name": "Lockin_Demod_2X_filter"
},
{
"data": {
"name": "Lockin Demod 2Y_filter",
"raw_path": "/dat_mat_components/LI Demod 2 Y [filt]/value",
"@units": "/dat_mat_components/LI Demod 2 Y [filt]/unit"
},
"0": {
"name": "Bias Voltage",
"raw_path": [
"/dat_mat_components/Bias [filt]/value",
"/dat_mat_components/Bias calc/value",
"/dat_mat_components/Bias/value"
],
"@units": [
"/dat_mat_components/Bias calc/unit",
"/dat_mat_components/Bias/unit"
]
},
"title": { "raw_path": "@default:Lockin Demod 2Y(filter)" },
"grp_name": "Lockin_Demod_2Y_filter"
}
]
}
},
"CIRCUIT[circuit]": ""
},
"independent_controllers": "",
"measurement_sensors": ""
},
"current_sensorTAG[current_sensor]": {
"current": {
"raw_path": "/Current/Current/value",
"@units": "/Current/Current/unit"
},
"calibration": {
"calibration_parameters": {
"coefficient": {
"raw_path": "/Current/Calibration/value",
"@units": "/Current/Calibration/unit"
}
}
},
"offset_value": {
"raw_path": "/Current/Offset/value",
"@units": "/Current/Offset/unit"
},
"AMPLIFIER[amplifier]": {
"current_gain": { "raw_path": "" }
}
},
"piezo_sensor": {
"piezo_configuration": {
"calibration": {
"calibration_type": {
"raw_path": "@default:active"
},
"calibration_date": {
"raw_path": ""
},
"rangeN[range_n]": { "x": "", "y": "", "z": "" },
"calibration_parameters": {
"coefficientN[coefficient_n]": [
{
"x": {
"raw_path": "/Piezo Configuration/Calib. X/value",
"@units": "/Piezo Configuration/Calib. X/unit"
}
},
{
"y": {
"raw_path": "/Piezo Configuration/Calib. Y/value",
"@units": "/Piezo Configuration/Calib. Y/unit"
}
},
{
"z": {
"raw_path": "/Piezo Configuration/Calib. Z/value",
"@units": "/Piezo Configuration/Calib. Z/unit"
}
}
],
"second_order_correctionN[second_order_correction_n]": [
{
"x": {
"raw_path": "/Piezo Configuration/2nd order corr X/value",
"@units": "/Piezo Configuration/2nd order corr X/unit"
}
},
{
"y": {
"raw_path": "/Piezo Configuration/2nd order corr Y/value",
"@units": "/Piezo Configuration/2nd order corr Y/unit"
}
}
]
},
"driftN[drift_n]": [
{
"x": {
"raw_path": "/Piezo Configuration/Drift X/value",
"@units": "/Piezo Configuration/Drift X/unit"
}
},
{
"y": {
"raw_path": "/Piezo Configuration/Drift Y/value",
"@units": "/Piezo Configuration/Drift Y/unit"
}
},
{
"z": {
"raw_path": "/Piezo Configuration/Drift Z/value",
"@units": "/Piezo Configuration/Drift Z/unit"
}
}
],
"hv_gainN[hv_gain_n]": [
{ "x": { "raw_path": "/Piezo Configuration/HV Gain X/value" } },
{ "y": { "raw_path": "/Piezo Configuration/HV Gain Y/value" } },
{ "z": { "raw_path": "/Piezo Configuration/HV Gain Z/value" } }
],
"tiltN[tilt_n]": [
{
"x": {
"raw_path": "/Piezo Configuration/Tilt X/value",
"@units": "/Piezo Configuration/Tilt X/unit"
}
},
{
"y": {
"raw_path": "/Piezo Configuration/Tilt Y/value",
"@units": "/Piezo Configuration/Tilt Y/unit"
}
},
{
"z": {
"raw_path": "/Piezo Configuration/Tilt Z/value",
"@units": "/Piezo Configuration/Tilt Z/unit"
}
}
],
"drift_correction_status": {
"raw_path": [
"/Piezo Configuration/Drift correction status/value",
"/Piezo Calibration/Drift correction status/value"
]
}
},
"piezo_material": {
"curvature_radiusN": [
{
"x": {
"raw_path": "/Piezo Configuration/Curvature radius X/value",
"@units": "/Piezo Configuration/Curvature radius X/unit"
}
},
{
"y": {
"raw_path": "/Piezo Configuration/Curvature radius Y/value",
"@units": "/Piezo Configuration/Curvature radius Y/unit"
}
},
{
"z": {
"raw_path": "/Piezo Configuration/Curvature radius Z/value",
"@units": "/Piezo Configuration/Curvature radius Z/unit"
}
}
]
}
},
"SPM_POSITIONER[spm_positioner]": "",
"x": { "raw_path": "/X/value", "@units": "/X/unit" },
"y": { "raw_path": "/Y/value", "@units": "/Y/unit" },
"z": { "raw_path": "/Z/value", "@units": "/Z/unit" },
"AXISoffset_value[x_offset_value]": {
"x": "",
"y": "",
"z": ""
}
},
"sample_bias_voltage": {
"bias_voltage": {
"raw_path": "/Bias/Bias/value",
"@units": "/Bias/Bias/unit"
},
"calibration": {
"calibration_parameters": {
"coefficient": {
"raw_path": "/Bias/Calibration/value",
"@units": "/Bias/Calibration/unit"
}
}
}
},
"SCAN_ENVIRONMENT[scan_environment]": {
"identifier_environment": {
"raw_path": "/Scan/series name/value"
},
"cryo_bottom_temperature": { "@units": "" },
"cryo_shield_temperature": { "@units": "" },
"head_temperature": {
"raw_path": "/Temperature 1/Temperature 1/value",
"@units": "/Temperature 1/Temperature 1/unit"
},
"cryo_shield_temperature_sensor": "@default_link:/ENTRY[entry]/INSTRUMENT[instrument]/cryo_shield_temperature_sensor",
"cryo_bottom_temperature_sensor": "@default_link:/ENTRY[entry]/INSTRUMENT[instrument]/cryo_bottom_temperature_sensor",
"head_temperature_sensor": "@default_link:/ENTRY[entry]/INSTRUMENT[instrument]/head_temperature_sensor"
},
"cryo_shield_temperature_sensor": {
"temp_offset_value": "",
"TEMPERATUREchannel[temperature_channel]": "",
"calibration": {
"calibration_parameters": {
"coefficient": ""
}
},
"temperature_calibration": { "coefficients": "" },
"DATA[data]": ""
},
"cryo_bottom_temperature_sensor": {
"temp_offset_value": "",
"TEMPERATUREchannel[temperature_channel]": "",
"calibration": {
"calibration_parameters": {
"coefficient": ""
}
},
"temperature_calibration": { "coefficients": "" },
"DATA[data]": ""
},
"sample_temperature_sensor": {
"temp_offset_value": "",
"TEMPERATUREchannel[temperature_channel]": "",
"calibration": {
"calibration_parameters": {
"coefficient": ""
}
},
"temperature_calibration": { "coefficients": "" },
"DATA[data]": ""
},
"head_temperature_sensor": {
"temp_offset_value": "",
"TEMPERATUREchannel[temperature_channel]": "",
"calibration": {
"calibration_parameters": {
"coefficient": ""
}
},
"temperature_calibration": { "coefficients": "" },
"DATA[data]": [
{
"data": {
"name": "temperature1",
"raw_path": "/dat_mat_components/Temperature 1/value",
"@units": "/dat_mat_components/Temperature 1/unit"
},
"0": {
"name": "Bias Voltage",
"raw_path": [
"/dat_mat_components/Bias calc/value",
"/dat_mat_components/Bias/value"
],
"@units": [
"/dat_mat_components/Bias calc/unit",
"/dat_mat_components/Bias/unit"
],
"axis_ind": 0
},
"title": { "raw_path": "@default:Bias Spectroscopy Temperature1" },
"grp_name": "temperature1"
},
{
"data": {
"name": "temperature1_filter",
"raw_path": "/dat_mat_components/Temperature 1 [filt]/value",
"@units": "/dat_mat_components/Temperature 1 [filt]/unit"
},
"0": {
"name": "Bias Voltage",
"raw_path": [
"/dat_mat_components/Bias calc/value",
"/dat_mat_components/Bias/value"
],
"@units": [
"/dat_mat_components/Bias calc/unit",
"/dat_mat_components/Bias/unit"
],
"axis_ind": 0
},
"title": {
"raw_path": "@default:Bias Spectroscopy Temperature1(filter)"
},
"grp_name": "temperature1_filter"
}
]
}
},
"DATA[data]": [
{
"data": {
"name": "Current",
"raw_path": "/dat_mat_components/Current/value",
"@units": "/dat_mat_components/Current/unit"
},
"0": {
"name": "Bias Voltage",
"raw_path": [
"/dat_mat_components/Bias calc/value",
"/dat_mat_components/Bias/value"
],
"@units": [
"/dat_mat_components/Bias calc/unit",
"/dat_mat_components/Bias/unit"
]
},
"title": { "raw_path": "@default:Bias Spectroscopy" },
"grp_name": "current"
},
{
"data": {
"name": "Current Filter",
"raw_path": "/dat_mat_components/Current [filt]/value",
"@units": "/dat_mat_components/Current [filt]/unit"
},
"0": {
"name": "Bias Voltage",
"raw_path": [
"/dat_mat_components/Bias [filt]/value",
"/dat_mat_components/Bias calc/value",
"/dat_mat_components/Bias/value"
],
"@units": [
"/dat_mat_components/Bias calc/unit",
"/dat_mat_components/Bias/unit"
],
"axis_ind": 0
},
"title": { "raw_path": "@default:Bias Spectroscopy(filter)" },
"grp_name": "current_filter"
},
{
"data": {
"name": "Current Filter",
"raw_path": "/dat_mat_components/Current [filt]/value",
"@units": "/dat_mat_components/Current [filt]/unit"
},
"0": {
"name": "Bias Voltage",
"raw_path": [
"/dat_mat_components/Bias [filt]/value",
"/dat_mat_components/Bias calc/value",
"/dat_mat_components/Bias/value"
],
"@units": [
"/dat_mat_components/Bias calc/unit",
"/dat_mat_components/Bias/unit"
]
},
"title": { "raw_path": "@default:Bias Spectroscopy(filter)" },
"grp_name": "current_filter"
},
{
"data": {
"name": "Current Backward",
"raw_path": "/dat_mat_components/Current [bwd]/value",
"@units": "/dat_mat_components/Current [bwd]/unit"
},
"0": {
"name": "Bias Voltage",
"raw_path": [
"/dat_mat_components/Bias [filt]/value",
"/dat_mat_components/Bias calc/value",
"/dat_mat_components/Bias/value"
],
"@units": [
"/dat_mat_components/Bias calc/unit",
"/dat_mat_components/Bias/unit"
]
},
"title": { "raw_path": "@default:Bias Spectroscopy(Backward)" },
"grp_name": "current_backward"
}
],
"reproducibility_indicators": {
"current": "@default_link:/ENTRY[entry]/INSTRUMENT[instrument]/current_sensor/current",
"current_gain": "@default_link:/ENTRY[entry]/INSTRUMENT[instrument]/current_sensor/AMPLIFIER[amplifier]/current_gain",
"current_offset": "@default_link:/ENTRY[entry]/INSTRUMENT[instrument]/current_sensor/current_offset",
"bias_sweep": "@default_link:/ENTRY[entry]/INSTRUMENT[instrument]/bias_spectroscopy_environment/BIAS_SPECTROSCOPY[bias_spectroscopy]/BIAS_SWEEP[bias_sweep]",
"reference_frequency": "@default_link:/ENTRY[entry]/INSTRUMENT[instrument]/lockin_amplifier/reference_frequency",
"modulation_signal": "@default_link:/ENTRY[entry]/INSTRUMENT[instrument]/lockin_amplifier/modulation_signal"
},
"resolution_indicators": {
"head_temperature": "@default_link:/ENTRY[entry]/INSTRUMENT[instrument]/scan_environment/head_temperature",
"cryo_bottom_temperature": "@default_link:/ENTRY[entry]/INSTRUMENT[instrument]/scan_environment/cryo_bottom_temperature",
"cryo_shield_temperature": "@default_link:/ENTRY[entry]/INSTRUMENT[instrument]/scan_environment/cryo_shield_temperature",
"bias_sweep": "@default_link:/ENTRY[entry]/INSTRUMENT[instrument]/bias_spectroscopy_environment/BIAS_SPECTROSCOPY[bias_spectroscopy]/BIAS_SWEEP[bias_sweep]",
"reference_frequency": "@default_link:/ENTRY[entry]/INSTRUMENT[instrument]/lockin_amplifier/reference_frequency",
"modulation_signal": "@default_link:/ENTRY[entry]/INSTRUMENT[instrument]/lockin_amplifier/modulation_signal"
}
}
}
Modification Rules for config.json File¶
1. The simplest way to map NeXus concepts (fields and/or attributes) to the raw data file is to use a map from the concept name to a map object.
The field reference_frequency of lockin_amplifier group is mapped to an object containing "raw_path" and attributes e.g., "units", "demo_attr".
The "raw_path" refers to the path of raw data (e.g.,
2. Set default values for a concept (field and/or attribute) via the config file
A default value of a NeXus field modulation_signal field of lockin_amplifier can be set using the syntax "@default:<value>".
3. Use the config file to define variadic names for concepts like groups, fields, and attributes. In NeXus concepts, a part or the entire concept name can be modified while instantiating the objects, allowing multiple instances of the same concept.
Define variadic name for the group TEMPERATURE[temperature] of INSTRUMENT group using a map to one dimensional array of objects. Each element of the array is an object mapping from embedding part of name to the raw data paths or nested concepts. The example array leads two instances of TEMPERATURE[head_temperature_sensor] and TEMPERATURE[sample_temperature_sensor].
"INSTRUMENT[instrument]": {
"TEMPERATURE[temperature]": [
{"head_temperature_sensor":{
"CHANNEL_temp[channel_temp]": {
"raw_path": "/Temperature 1/Temperature 1/value",
"@units": "/Temperature 1/Temperature 1/unit"
}
}
},
{"sample_temperature_sensor": {
"CHANNEL_temp[channel_temp]": {
"raw_path": "/Temperature 2/Temperature 2/value",
"@units": "/Temperature 2/Temperature 2/unit"
}
}
}
]
}
Or, simply write multiple groups like they are independent of each other.
"INSTRUMENT[instrument]": {
"TEMPERATURE[head_temperature_sensor]": {
"CHANNEL_temp[channel_temp]": {
"raw_path": "/Temperature 1/Temperature 1/value",
"@units": "/Temperature 1/Temperature 1/unit"
}
},
"TEMPERATURE[sample_temperature_sensor]": {
"CHANNEL_temp[channel_temp]": {
"raw_path": "/Temperature 2/Temperature 2/value",
"@units": "/Temperature 2/Temperature 2/unit"
}
},
}
Define variadic name for the field second_order_correction_N[second_order_correction_n] of piezo_configuration group using one dimensional array of objects. Each element of an array is an object mapping embedding part to the raw data path. The array leads a field second_order_correction_N[second_order_correction_n] to two instances, second_order_correction_N[second_order_correction_x] and second_order_correction_N[second_order_correction_y].
"piezo_sensor": {
"piezo_configuration": {
"second_order_correction_N[second_order_correction_n]": [
{
"x": {
"raw_path": "/Piezo Configuration/2nd order corr X/value",
"@units": "/Piezo Configuration/2nd order corr X/unit"
}
},
{
"y": {
"raw_path": "/Piezo Configuration/2nd order corr Y/value",
"@units": "/Piezo Configuration/2nd order corr Y/unit"
}
}
],
}
}
Or, simply write multiple fields like they are independent of each other.
"piezo_sensor": {
"piezo_configuration": {
"second_order_correction_N[second_order_correction_x]": {
"raw_path": "/Piezo Configuration/2nd order corr X/value",
"@units": "/Piezo Configuration/2nd order corr X/unit"
},
"second_order_correction_N[second_order_correction_y]": {
"raw_path": "/Piezo Configuration/2nd order corr Y/value",
"@units": "/Piezo Configuration/2nd order corr Y/unit"
}
}
}
Similar to the field, a variadic attribute can have multiple instances. For sake of the explanation, let consider, configurationNAME[configuration_name] is a variadic attribute of the piezo_configuration group. This situation can be written in config file, attribute configurationNAME[configuration_name] will be modified with multiple instances as configurationNAME[configuration_name_x] and configurationNAME[configuration_name_y].
Or, simply write multiple attributes like they are independent of each other.
4. Write customized NXdata groups via the config file. It is often necessary for a user to annotate plots by defining the axis name and plot title.
The NXdata can represent multiple instances of plottable data. Each set is defined by an object in the array of DATA[data]. Each object contains data key referring the DATA field of NXdata base class, string of numbers (e.g., "0", "1") referring the index of the independent axis variable(s) for the data, title key for title field of NXdata group, and grp_name key defining the instance name of the NXdata group.
"DATA[data]": [
{
"data": {
"name": "Current",
"raw_path": "/dat_mat_components/Current/value",
"@units": "/dat_mat_components/Current/unit"
},
"0": {
"name": "Bias Voltage",
"raw_path": [
"/dat_mat_components/Bias calc/value",
"/dat_mat_components/Bias/value"
],
"@units": [
"/dat_mat_components/Bias calc/unit",
"/dat_mat_components/Bias/unit"
]
},
"title": { "raw_path": "@attribute:Bias Spectroscopy" },
"grp_name": "current"
},
{
"data": {
"name": "Current_filter",
"raw_path": "/dat_mat_components/Current [filt]/value",
"@units": "/dat_mat_components/Current [filt]/unit"
},
"0": {
"name": "Bias Voltage",
"raw_path": [
"/dat_mat_components/Bias [filt]/value",
"/dat_mat_components/Bias calc/value",
"/dat_mat_components/Bias/value"
],
"@units": [
"/dat_mat_components/Bias calc/unit",
"/dat_mat_components/Bias/unit"
]
},
"title": { "raw_path": "@attribute:Bias Spectroscopy(filter)" },
"grp_name": "Current_filter"
}
]
5. The nxformatter of pynxtools-spm has common functions, methods, and other programmatic tools that use the common rules in the config file as described above. The curated concepts should be written in the template object of pynxtools. However, there may be special cases where the generalized functions and methods do not work. In such cases, customized methods handle the special fields. To annotate which concepts or fields need special treatment, the config file has a key #note. The value of #note holds a human-readable description, e.g., the name of the method that handles the special case. The class variable _grp_to_func must have a map from the group name to the method name.
This group BIAS_SWEEP[bias_sweep] is considered as a group that should be handled in a special method called _construct_bias_sweep_grp. To annotate this special case and information, the key #note is used.
And the class variable _grp_to_func look like this:
Attribute Features of pynxtools-spm¶
There are some attribute features to handle raw data from specific vendor files.
1. In STM, for Omicron raw files, the SPM_SCAN_CONTROL[spm_scan_control_*] group is instantiated for individual scans, e.g., current_forward, current_backward, topography_forward, topography_backward, etc.
In convention SPM_SCAN_CONTROL[spm_scan_control_*] the replacing part is *. For each scan, the instance name shall be something like SPM_SCAN_CONTROL[spm_scan_control_current_forward]. As the name SPM_SCAN_CONTROL is fully replaceable, one can wish to define the instance name as he want, e.g, in the config file, SPM_SCAN_CONTROL[*] or SPM_SCAN_CONTROL[any_prefix_*_any_suffix] both are allowed but one asterisk wildcard * must be provided.
."SCAN_ENVIRONMENT[scan_environment]": {
"SPM_SCAN_CONTROL[spm_scan_control_*]": {
"#note": "Handled in function _construct_nxscan_controllers. With '*' it is possible to add scan names, e.g., current_backward.",
"scanTAG[scan_name]": {
"raw_path": ""
},
"meshSCAN[mesh_scan]": {
"backward_speedN[backward_speed_n]": {
"raw_path": "",
"@units": ""
},
},
},
}
2. In AFM, for Bruker SPMLab FLT raw files, the raw data keys are prefixed by the channel name of the file (e.g. /Height/meta/SetPoint for a file with DataName=Height). Since a config file cannot know that name in advance, the placeholder /CHANNEL/ is used in the raw_path entries and is replaced by the channel prefix of the file (e.g. /Height/) when the config file is loaded.
For a file with the header entry DataName=Height, the raw path /CHANNEL/meta/X Transfer Coefficient below is resolved to /Height/meta/X Transfer Coefficient. Use the placeholder in your own config file so that the same file works for every channel (e.g. Height, Adhesion).
Some Useful Tips¶
The code usages outside the reader is sometimes necessary for developers or users, especially when encountering errors or unexpected behavior.
1. The parsers in pynxtools-spm parse a raw data file and organize the data in a slash-separated dictionary. The slash-separated keys represent the hierarchical structure followed in the raw file. To investigate how the raw data is organized, you can use the following code snippets.
2. The aim of the nxformatter of pynxtools-spm is to curate the raw data and ELN data. Later, the curated data is stored in a template object of pynxtools. To investigate how the data is curated, you can use the following code snippets.
from pynxtools.dataconverter import helpers
from pynxtools.dataconverter.template import Template
from pynxtools_spm.nxformatters.nanonis.nanonis_dat_sts import NanonisDatSTS
nxdl_name = "NXsts"
if nxdl_root is None:
nxdl_root, _ = helpers.get_nxdl_root_and_path(nxdl=nxdl_name)
template = Template()
helpers.generate_template_from_nxdl(nxdl_root, template)
raw_file = "path/to/your/file.dat"
eln_file = "path/to/your/file.yaml"
config_file = "path/to/your/config.json"
formatter = NanonisDatSTS(template=template, raw_file=raw_file,
eln_file=eln_file, config_file=config_file)
curated_template: Template = formatter.get_nxformatted_template()
from pynxtools.dataconverter import helpers
from pynxtools.dataconverter.template import Template
from pynxtools_spm.nxformatters.nanonis.nanonis_sxm_stm import NanonisSxmSTM
nxdl_name = "NXstm"
if nxdl_root is None:
nxdl_root, _ = helpers.get_nxdl_root_and_path(nxdl=nxdl_name)
template = Template()
helpers.generate_template_from_nxdl(nxdl_root, template)
raw_file = "path/to/your/file.sxm"
eln_file = "path/to/your/file.yaml"
config_file = "path/to/your/config.json"
formatter = NanonisSxmSTM(template=template, raw_file=raw_file,
eln_file=eln_file, config_file=config_file)
curated_template: Template = formatter.get_nxformatted_template()
from pynxtools.dataconverter import helpers
from pynxtools.dataconverter.template import Template
from pynxtools_spm.nxformatters.omicron.omicron_sm4_stm import OmicronSM4STM
nxdl_name = "NXstm"
if nxdl_root is None:
nxdl_root, _ = helpers.get_nxdl_root_and_path(nxdl=nxdl_name)
template = Template()
helpers.generate_template_from_nxdl(nxdl_root, template)
raw_file = "path/to/your/file.sxm"
eln_file = "path/to/your/file.yaml"
config_file = "path/to/your/config.json"
formatter = OmicronSM4STM(template=template, raw_file=raw_file,
eln_file=eln_file, config_file=config_file)
curated_template: Template = formatter.get_nxformatted_template()
from pynxtools.dataconverter import helpers
from pynxtools.dataconverter.template import Template
from pynxtools_spm.nxformatters.nanonis.nanonis_sxm_afm import NanonisSxmAFM
nxdl_name = "NXafm"
if nxdl_root is None:
nxdl_root, _ = helpers.get_nxdl_root_and_path(nxdl=nxdl_name)
template = Template()
helpers.generate_template_from_nxdl(nxdl_root, template)
raw_file = "path/to/your/file.sxm"
eln_file = "path/to/your/file.yaml"
config_file = "path/to/your/config.json"
formatter = NanonisSxmAFM(template=template, raw_file=raw_file,
eln_file=eln_file, config_file=config_file)
curated_template: Template = formatter.get_nxformatted_template()
from pynxtools.dataconverter import helpers
from pynxtools.dataconverter.template import Template
from pynxtools_spm.nxformatters.bruker.bruker_flt_afm import BrukerFltAFM
nxdl_name = "NXafm"
if nxdl_root is None:
nxdl_root, _ = helpers.get_nxdl_root_and_path(nxdl=nxdl_name)
template = Template()
helpers.generate_template_from_nxdl(nxdl_root, template)
# A FLT file written by Bruker SPMLab (version 1.00).
raw_file = "path/to/your/file.FLT"
eln_file = "path/to/your/file.yaml"
# Optional: without it the default config
# `configs/bruker/bruker_flt_afm.json` of the package is used.
config_file = "path/to/your/config.json"
formatter = BrukerFltAFM(template=template, raw_file=raw_file,
eln_file=eln_file, config_file=config_file)
curated_template: Template = formatter.get_nxformatted_template()
from pynxtools.dataconverter import helpers
from pynxtools.dataconverter.template import Template
from pynxtools_spm.nxformatters.bruker.bruker_spm_afm import BrukerSpmAFM
nxdl_name = "NXafm"
if nxdl_root is None:
nxdl_root, _ = helpers.get_nxdl_root_and_path(nxdl=nxdl_name)
template = Template()
helpers.generate_template_from_nxdl(nxdl_root, template)
# A .spm file written by Bruker NanoScope (version 9.x).
raw_file = "path/to/your/file.spm"
eln_file = "path/to/your/file.yaml"
# Optional: without it the default config
# `configs/bruker/bruker_spm_afm.json` of the package is used.
config_file = "path/to/your/config.json"
formatter = BrukerSpmAFM(template=template, raw_file=raw_file,
eln_file=eln_file, config_file=config_file)
curated_template: Template = formatter.get_nxformatted_template()
from pynxtools.dataconverter import helpers
from pynxtools.dataconverter.template import Template
from pynxtools_spm.nxformatters.bruker.bruker_txt_afm import BrukerTxtAFM
nxdl_name = "NXafm"
if nxdl_root is None:
nxdl_root, _ = helpers.get_nxdl_root_and_path(nxdl=nxdl_name)
template = Template()
helpers.generate_template_from_nxdl(nxdl_root, template)
# The NanoScope ASCII export of a force ramp.
raw_file = "path/to/your/file.spm.txt"
eln_file = "path/to/your/file.yaml"
# Optional: without it the default config
# `configs/bruker/bruker_txt_afm.json` of the package is used.
config_file = "path/to/your/config.json"
formatter = BrukerTxtAFM(template=template, raw_file=raw_file,
eln_file=eln_file, config_file=config_file)
curated_template: Template = formatter.get_nxformatted_template()