Adds XPS example files and completes tutorial docs

docs/tutorial/converting-data-to-nexus.md

@@ -1,15 +1,11 @@
 # Converting research data to NeXus
 
-!!! danger "Work in progress"
-
-    This part of the documentation is still being written and it might be confusing or incomplete.
-
 ## Who is this tutorial for?
 
-The document is for people who want to standardize their research data by converting their research data into 
+The document is for people who want to standardize their research data by converting their research data into
 a NeXus standardized format.
 We cover the basic principles and common principles of NeXus, here.
-For a more detailed description on the general principles of NeXus we recommend reading our 
+For a more detailed description on the general principles of NeXus we recommend reading our
 [learning page for NeXus](../learn/nexus-primer.md) or the [official NeXus user manual](https://manual.nexusformat.org/user_manual.html).
 
 ## What should you should know before this tutorial?
@@ -27,36 +23,41 @@ You will have
 
 We use a Python tool to make converting our research data easier. This has a number of [readers](https://github.com/FAIRmat-NFDI/pynxtools/tree/master/pynxtools/dataconverter/readers) that support multiple file formats. You can browse the separate folders to find the reader that might work for you. A generic reader is the [JSON Map Reader](https://github.com/FAIRmat-NFDI/pynxtools/tree/master/pynxtools/dataconverter/readers/json_map).
 
-We will use the [XPS Reader](https://github.com/FAIRmat-NFDI/pynxtools/tree/master/pynxtools/dataconverter/readers/xps) with Vamas (.vms) files as an example. 
+We will use the [XPS Reader](https://github.com/FAIRmat-NFDI/pynxtools/tree/master/pynxtools/dataconverter/readers/xps) with a [SpecsLabProdigy](https://www.specs-group.com/nc/specs/products/detail/prodigy/) file (.sle) as an example.
 
 #### Steps
 
-1. Download the example files from here:
-2. Install [pynxtools](https://github.com/FAIRmat-NFDI/pynxtools/tree/master?tab=readme-ov-file#installation)
-3. Verify you can run the ```dataconverter``` in a terminal window. Open a terminal with the Python environment where you installed ```pynxtools```. Then type the following:
+1. Download the example files from here: [Example files](https://download-directory.github.io/?url=https%3A%2F%2Fgithub.com%2FFAIRmat-NFDI%2Fpynxtools%2Ftree%2Fdocumentation%2Fexamples%2Fxps)
+2. **Extract** the zip and copy the files in your current working directory. You can find the working directory by typing the following in your terminal:
 ```console
-dataconverter --help
+pwd
 ```
-4. Copy the example files to your working directory. You can find the working directory by typing the following in your terminal:
+3. Install [pynxtools](https://github.com/FAIRmat-NFDI/pynxtools/tree/master?tab=readme-ov-file#installation)
 ```console
-pwd
+pip install git+https://github.com/FAIRmat-NFDI/pynxtools.git
+```
+4. Verify you can run the ```dataconverter``` in a terminal window. Open a terminal with the Python environment where you installed ```pynxtools```. Then type the following:
+```console
+dataconverter --help
 ```
 
 ## Converting the example files
 
-!!! **we might need a part to explain how to find an appdef to use and link to documents on creating an appdef**
-
 Once you have your files copied into the working directory. Your directory structure should look like this:
 ```
-- file1.vms
-- otherfile.vms
+├── README.md
+├── EX439_S718_Au.sle
+├── params.yaml
+└── eln_data_sle.yaml
 ```
 
-Next, you will run the conversion routine:
+Next, you will run the conversion routine from your Python environment:
 ```console
-dataconverter --reader xps 
+dataconverter --params-file params.yaml
 ```
 
-This will create a file called ```output.nxs``` in your current directory.
+Here we use a params.yaml parameter file to configure the converter. You can try out [other examples from pynxtools](https://github.com/FAIRmat-NFDI/pynxtools/tree/documentation/examples)
+
+This will create a file called ```Au_25_mbar_O2_no_align.nxs``` in your current directory.
 
 **Congrats! You now have a FAIR NeXus file!**

examples/xps/README.md

@@ -0,0 +1,22 @@
+# XPS Reader
+
+## What is this reader?
+
+This reader supports converting X-ray photoelectron spectroscopy into a NeXus formatted file. The application definiton it follows is [NXmpes](https://fairmat-nfdi.github.io/nexus_definitions/classes/contributed_definitions/NXmpes.html#nxmpes).
+
+## Supported file formats
+The reader decides which parser to use based on the file extension of the files provided. For the main XPS files, the following file extensions are supported:
+- .sle: [SpecsLabProdigy](https://www.specs-group.com/nc/specs/products/detail/prodigy/) files, propietary format of SPECS GmbH (v1.6)
+- .xml: SpecsLab 2files, XML format from SPECS GmbH (v1.6)
+- .vms: VAMAS files, ISO standard data transfer format ([ISO 14976](https://www.iso.org/standard/24269.html)), both in regular and irregular format
+- .xy: SpecsLabProdigy export format in XY format (including all export settings)
+- .txt:
+  - exported by [Scienta Omicron](https://scientaomicron.com/en) instruments
+  - exported by [CasaXPS](https://www.casaxps.com/) analysis software
+
+```console
+user@box:~$ dataconverter --params-file params.yaml
+```
+
+## Contact person in FAIRmat for this reader
+Lukas Pielsticker

examples/xps/eln_data_sle.yaml

@@ -0,0 +1,165 @@
+definition:
+  value: NXmpes
+  version: 1.0
+title: EX439_S718_Au in 25 mbar O2
+start_time: 2022-04-08T11:47:02.0200Z
+end_time: 2022-04-08T14:52:26.0400Z
+entry_identifier: EX439
+experiment_institution: Max Planck Institute for Chemical Energy Conversion
+experiment_facility: Surface and Interface Analysis Group
+experiment_laboratory: Near-Ambient Pressure XPS Lab
+program_name: SpecsLabProdigy
+user:
+  name: Lukas Pielsticker
+  affiliation: Max Planck Institute for Chemical Energy Conversion
+  address: Lukas Pielsticker
+  orcid: 0000-0001-9361-8333
+  email: [email protected]
+Instrument:
+  device_information:
+    vendor: SPECS GmbH
+    model: Custom NAP-XPS instrument
+    identifier: null
+  energy_resolution:
+    type: calibrated
+    resolution:
+      value: 0.2
+      unit: eV
+  source_probe:
+    type: Fixed Tube X-ray
+    probe: photon
+    device_information:
+      vendor: SPECS GmbH
+      model: µFOCUS 500
+      identifier: null
+  beam_probe:
+    distance:
+      value: 0.0
+      unit: mm
+  Electronanalyser:
+    description: hemispherical
+    device_information:
+      vendor: SPECS GmbH
+      model: PHOIBOS 150 NAP
+      identifier: null
+    Collectioncolumn:
+      scheme: angular dispersive
+      device_information:
+        vendor: SPECS GmbH
+        model: PHOIBOS 150 NAP
+        identifier: null
+    Energydispersion:
+      scheme: hemispherical
+      diameter:
+        unit: mm
+        value: 150
+      device_information:
+        vendor: SPECS GmbH
+        model: PHOIBOS 150
+        identifier: null
+    Detector:
+      amplifier_type: channeltron
+      detector_type: Multi-anode   
+      device_information:
+        vendor: Surface Concept GmbH
+        model: 1D-DLD detector
+        identifier: null
+  Manipulator:
+    device_information:
+      vendor: SPECS GmbH
+      model: 5-axis manipulator
+      identifier: null
+    temperature_sensor:
+      name: type K thermocouple
+      measurement: temperature
+      attached_to: sample
+      type: type K thermocouple
+      value:
+        value: 298.0
+        unit: K
+    sample_heater:
+      name: Coherent Compact Evolution IR Diode LASER (DILAS)
+      physical_quantity: temperature
+      type: IR diode laser
+      heater_power:
+        value: 0.0
+        unit: W
+      Pid:
+        setpoint:
+          value: 298.0
+          unit: K
+    cryostat:
+      name: null
+      physical_quantity: null
+      type: null
+      Pid:
+        setpoint: null
+    drain_current_amperemeter:
+      name: Amperemeter 1.0
+      measurement: current
+      type: wire
+      value:
+        value: 0.1
+        unit: nA
+    sample_bias_voltmeter:
+      name: XPS sample voltmeter
+      measurement: voltage
+      attached_to: sample
+      type: oscilloscope
+      value:
+        value: 0.0
+        unit: V
+    sample_bias_potentiostat:
+      name: XPS sample potentiostat
+      physical_quantity: voltage
+      type: potentiostat
+      Pid:
+        setpoint:
+          value: 0.0
+          unit: V
+  pressure_gauge:
+    name: Atmion
+    measurement: pressure
+    type: hot-filament ionization gauge
+    value:
+      value: 0.000000001
+      unit: mbar
+    value_log:
+      value:
+        value: null
+        unit: null
+  flood_gun:
+    name: FG 22/35
+    physical_quantity: current
+    type: low energy electron source
+    current:
+      value: 0.0
+      unit: A
+    current_log:
+      value:
+        value: null
+        unit: null
+Sample:
+  name: Polycristalline Au foil
+  sample_id: S718
+  atom_types: Au
+  physical_form: foil
+  situation: vacuum
+  Substance:
+    name: Au
+    molecular_mass:
+      value: 196.96657
+      unit: g/mol
+    cas_number: 7440-57-5
+    molecular_formula_hill: Au
+  sample_history:
+    sample_preparation:
+      start_time: 2022-04-08T11:25:00.200Z
+      end_time: 2022-04-08T11:45:00.200Z
+      description: sputter cleaned with Ar ions for 20 min
+      method: Ar sputtering
+    PHYSICAL_PROCESS[sample_loading]:
+      start_time: 2022-04-08T11:02:00.0200Z
+      end_time: 2022-04-08T11:03:00.0200Z
+      description: loaded in the endstation and transferred to analysis chamber
+      method: vacuum transfer

examples/xps/params.yaml

@@ -0,0 +1,8 @@
+dataconverter:
+  reader: xps
+  nxdl: NXmpes
+  input-file:
+    - EX439_S718_Au.sle
+    - eln_data_sle.yaml
+  remove_align: True
+  output: Au_25_mbar_O2_no_align.nxs