Data Format in piva

This section discusses what it means for a data file to be recognizable and readable by piva.

Problem of Multiple File Formats

Within the ARPES community, it is common for each beamline and lab to use their own file formats and conventions. Consequently, handling these different files requires a dedicated script that converts them into a common format.

In piva, this task is managed by the data_loaders module, which implements specific Dataloaders for files from various sources and returns a standardized Dataset object.

The Dataset defines a data structure consistently used within piva and is understandable by all other piva modules.

See also

To open file formats not originally included in piva, you need to implement a loader that returns a Dataset. A detailed guide on how to do this can be found here.

Dataset structure

The file format used internally by piva is a simple structured object inheriting from the pydantic.BaseModel object. [1]

The following table provides an overview of the data structure definition:

attribute	type	description
data *	np.ndarray	Acquired data of dimension (l, m, n). Oriented as: l-scanned axis, m- analyzer axis, n-energy axis. When scan is a single cut (data are 2D), first dimension is equal to data[0, :, :] = np.array([0]).
xscale *	np.ndarray	Axis along the scanned direction, has length l. Units depend on the scan type. When scan type is a single cut (2D), it is set to np.array([1]).
yscale *	np.ndarray	Axis along the analyzer slit, has length m. Most likely in [deg].
zscale *	np.ndarray	Axis along the energy direction, has length m. Most likely in [eV].
ekin	np.ndarray | None	Energy axis in kinetic energy scale (if default scale is in binding energy).
kxscale	np.ndarray | None	Momentum axis (saved after conversion) along the scanned direction.
kyscale	np.ndarray | None	Momentum axis (saved after conversion) along the analyzer direction.
x	float | None	x position of the manipulator.
y	float | None	y position of the manipulator.
z	float | None	z position of the manipulator.
theta	float | None	theta angle of the manipulator; often referred as polar.
phi	float | None	phi angle of the manipulator; often referred as azimuth.
tilt	float | None	tilt angle of the manipulator.
temp	float | None	Temperature during the experiment.
pressure	float | None	Pressure during the experiment.
hv	float | None	Photon energy used during the experiment.
wf	float | None	Work function of the analyzer.
Ef	float | None	Correction for the Fermi level.
polarization	str | None	Photon polarization.
PE	int | None	Pass energy of the analyzer.
exit_slit	float | None	Exit (vertical) slit of the beamline; responsible for energy resolution.
FE	float | None	Front end of the beamline.
scan_type	str | None	Type of the measurement (e.g. cut, tilt scan, hv scan).
scan_dim	list | None	If scan other than cut, scanned dimensions as list: [start, stop, step].
acq_mode	str | None	Data acquisition mode.
lens_mode	str | None	Lens mode of the analyzer.
ana_slit	str | None	Slit opening of the analyzer.
defl_angle	float | None	Applied deflection angle.
n_sweeps	int | None	Number of sweeps.
DT	int | None	Analyzer dwell time during data acquisition, most likely in [miliseconds].
data_provenance	dict	Dataset logbook; contains information about original file and keeps track of functions called on the data.

Not all attributes are present or required for piva to display data. Attributes that are mandatory for the functioning of the DataViewers are marked with an asterisk (*). However, much of the other information is needed for processing routines, such as angle-to-k-space conversion.

[1]

The only thing one needs to know about this, is that it accepts arbitrary python objects to store as its attributes, making it function as a simple key - value container, like a python dictionary. The advantage with respect to a dictionary is that its attributes can be accessed simply through dot notation, i.e. container.attribute instead of container[‘attribute’].