xpstrace: XPS trace file parser
This module handles the reading and processing of X-ray photoelectron spectroscopy
data, including determining the uncertainties of the signal (y-axis), and explicitly
populating the points in the energy axis (E).
Usage
Available since yadg-4.1. The parser supports the following parameters:
- pydantic model dgbowl_schemas.yadg.dataschema_5_0.step.XPSTrace
Parser for XPS traces.
Show JSON schema
{ "title": "XPSTrace", "description": "Parser for XPS traces.", "type": "object", "properties": { "tag": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Tag" }, "parser": { "const": "xpstrace", "title": "Parser" }, "input": { "$ref": "#/$defs/Input" }, "extractor": { "$ref": "#/$defs/Phi_spe" }, "parameters": { "anyOf": [ { "$ref": "#/$defs/Parameters" }, { "type": "null" } ], "default": null }, "externaldate": { "anyOf": [ { "$ref": "#/$defs/ExternalDate" }, { "type": "null" } ], "default": null } }, "$defs": { "ExternalDate": { "additionalProperties": false, "description": "Supply timestamping information that are external to the processed file.", "properties": { "using": { "anyOf": [ { "$ref": "#/$defs/ExternalDateFile" }, { "$ref": "#/$defs/ExternalDateFilename" }, { "$ref": "#/$defs/ExternalDateISOString" }, { "$ref": "#/$defs/ExternalDateUTSOffset" } ], "title": "Using" }, "mode": { "default": "add", "enum": [ "add", "replace" ], "title": "Mode", "type": "string" } }, "required": [ "using" ], "title": "ExternalDate", "type": "object" }, "ExternalDateFile": { "additionalProperties": false, "description": "Read external date information from file.", "properties": { "file": { "$ref": "#/$defs/dgbowl_schemas__yadg__dataschema_5_0__externaldate__ExternalDateFile__Content" } }, "required": [ "file" ], "title": "ExternalDateFile", "type": "object" }, "ExternalDateFilename": { "additionalProperties": false, "description": "Read external date information from the file name.", "properties": { "filename": { "$ref": "#/$defs/dgbowl_schemas__yadg__dataschema_5_0__externaldate__ExternalDateFilename__Content" } }, "required": [ "filename" ], "title": "ExternalDateFilename", "type": "object" }, "ExternalDateISOString": { "additionalProperties": false, "description": "Read a constant external date using an ISO-formatted string.", "properties": { "isostring": { "title": "Isostring", "type": "string" } }, "required": [ "isostring" ], "title": "ExternalDateISOString", "type": "object" }, "ExternalDateUTSOffset": { "additionalProperties": false, "description": "Read a constant external date using a Unix timestamp offset.", "properties": { "utsoffset": { "title": "Utsoffset", "type": "number" } }, "required": [ "utsoffset" ], "title": "ExternalDateUTSOffset", "type": "object" }, "Input": { "additionalProperties": false, "description": "Specification of input files/folders to be processed by the :class:`Step`.", "properties": { "folders": { "items": { "type": "string" }, "title": "Folders", "type": "array" }, "prefix": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Prefix" }, "suffix": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Suffix" }, "contains": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Contains" }, "exclude": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Exclude" } }, "required": [ "folders" ], "title": "Input", "type": "object" }, "Parameters": { "additionalProperties": false, "description": "Empty parameters specification with no extras allowed.", "properties": {}, "title": "Parameters", "type": "object" }, "Phi_spe": { "additionalProperties": false, "properties": { "filetype": { "enum": [ "phi.spe", "marda:phi-spe" ], "title": "Filetype", "type": "string" }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Timezone" }, "locale": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Locale" }, "encoding": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Encoding" } }, "required": [ "filetype" ], "title": "Phi_spe", "type": "object" }, "dgbowl_schemas__yadg__dataschema_5_0__externaldate__ExternalDateFile__Content": { "additionalProperties": false, "properties": { "path": { "title": "Path", "type": "string" }, "type": { "title": "Type", "type": "string" }, "match": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Match" } }, "required": [ "path", "type" ], "title": "Content", "type": "object" }, "dgbowl_schemas__yadg__dataschema_5_0__externaldate__ExternalDateFilename__Content": { "additionalProperties": false, "properties": { "format": { "title": "Format", "type": "string" }, "len": { "title": "Len", "type": "integer" } }, "required": [ "format", "len" ], "title": "Content", "type": "object" } }, "additionalProperties": false, "required": [ "parser", "input", "extractor" ] }
- Config:
extra: str = forbid
- field parser: Literal['xpstrace'] [Required]
Formats
The filetypes currently supported by the parser are:
ULVAC PHI Multipak XPS traces (
phi.spe), seephispe
Provides
The raw data is stored, for each timestep, using the following format:
datatree.DataTree:
{{ trace_name }} !!xr.Dataset
coords:
uts: !!float
E: !!float # binding energies (eV)
data_vals:
y: (uts, E) # signal
Module Functions
- yadg.parsers.xpstrace.process(*, filetype, **kwargs)
Unified x-ray photoelectron spectroscopy parser. Forwards
kwargsto the worker functions based on the suppliedfiletype.This parser processes XPS scans in signal(energy) format.
- Parameters:
filetype (
str) – Discriminator used to select the appropriate worker function.- Return type:
Submodules
phispe: Processing of ULVAC PHI Multipak XPS traces.
The IGOR .spe import script by jjweimer was pretty helpful for writing this parser.
File Structure of .spe Files
These binary files actually contain an ASCII file header, delimited by “SOFH “ and “EOFH “.
The binding energies corresponding to the datapoints in the later part of the file can be found from the “SpectralRegDef” entries in this header. Each of these entries look something like:
2 2 F1s 9 161 -0.1250 695.0 675.0 695.0 680.0 0.160000 29.35 AREA
This maps as follows:
2 trace_number
2 trace_number (again?)
F1s name
9 atomic_number
161 num_datapoints
-0.1250 step
695.0 start
675.0 stop
695.0 ?
680.0 ?
0.160000 dwell_time
29.35 e_pass
AREA description (?)
After the file header, the binary part starts with a short data header (offsets given from start of data header):
0x0000 group # Data group number.
0x0004 num_traces # Number of traces in file
0x0008 trace_header_size # Combined lengths of all trace headers.
0x000c data_header_size # Length of this data header.
After this follow num_traces trace headers that are each structured
something like this:
0x0000 trace_number # Number of the trace.
0x0004 bool_01 # ???
0x0008 bool_02 # ???
0x000c trace_number_again # Number of the trace. Again?
0x0010 bool_03 # ???
0x0014 num_datapoints # Number of datapoints in trace.
0x0018 bool_04 # ???
0x001c bool_05 # ???
0x0020 string_01 # ???
0x0024 string_02 # ???
0x0028 string_03 # ???
0x002c int_02 # ???
0x0030 string_04 # ???
0x0034 string_05 # ???
0x0038 y_unit # The unit of the datapoints.
0x003c int_05 # ???
0x0040 int_06 # ???
0x0044 int_07 # ???
0x0048 data_dtype # Data type for datapoints (f4 / f8).
0x004c num_data_bytes # Unsure about this one.
0x0050 num_datapoints_tot # This one as well.
0x0054 int_10 # ???
0x0058 int_11 # ???
0x005c end_of_data # Byte offset of the end-of-data.
After the trace headers follow the datapoints. After the number of datapoints there is a single 32bit float with the trace’s dwelling time again.
Uncertainties
The uncertainties of "E" are taken as the step-width of
the linearly spaced energy values.
The uncertainties "s" of "y" are currently set to a constant
value of 12.5 counts per second as all the signals in the files seen so
far only seem to take on values in those steps.
TODO
https://github.com/dgbowl/yadg/issues/13
Determining the uncertainty of the counts per second signal in XPS traces from the phispe parser should be done in a better way.
Code author: Nicolas Vetsch
- yadg.parsers.xpstrace.phispe.camel_to_snake(s)
Converts CamelCase strings to snake_case.
From https://stackoverflow.com/a/1176023
- Parameters:
s (
str) – The CamelCase input string.- Returns:
The snake_case equivalent of s.
- Return type:
str
- yadg.parsers.xpstrace.phispe.process(*, fn, **kwargs)
Processes ULVAC-PHI Multipak XPS data.
- Parameters:
fn (
str) – The file containing the data to parse.- Returns:
Returns a
datatree.DataTreecontaining axarray.Datasetfor each XPS trace present in the input file.- Return type: