MAJOR: solves problem related to ELABFTW_API_URL variable

if no value was specified for such variable (or .env was missing)
EAU would be set to None and get stuck in a prompt loop

solved by turning EAU into a required variable in APIHandler
(and editing a lot of code through all of src/)

.env.example

@@ -0,0 +1,4 @@
+api_key=""
+elabid=""
+ELABFTW_API_URL="https://elabftw.fisica.unina.it/api/v2"
+operative_unit="cnr-spin.na"

.gitignore

@@ -1,6 +1,15 @@
-# ignora log di h5tojson e jsontoh5
+# ignores bkp files of drawio
+.$*.bkp
+
+# ignores logs of h5tojson, jsontoh5
 *.log
 
+# ignores any output of main.py
+output/*.json
+output/*.h5
+output/*.nxs
+output/attachments/*.*
+
 # ---> Python
 # Byte-compiled / optimized / DLL files
 __pycache__/

docs/user-manual_01.adoc

@@ -0,0 +1,53 @@
+== Introduction
+// TO-DO: Grammar-check. I'm totally fried right now and can't seem to complete even a single proper
+*{software-family}* - short for _**e**LabFTW to Ne**X**us **Pars**er_ - is (hopefully) a family of specialized parsing software applications, mainly developed in Python, whose primary job is to automatically transform experimental metadata and data - originally stored as JSON objects inside an electronic lab notebook - into standardized, self-descriptive **NeXus files**.
+
+The software is designed to fetch "scattered" data (often distributed across multiple linked entries) from our eLNfootnote:[Acronym for "_electronic Lab Notebook_".] of choice - link:{elabftw-site}[**eLabFTW**^] - where the data is originally stored as JSON objects. It then parses the included metadata to resolve the full dataset which is then used to create a dictionary following a pre-established schema (dependent on the analysis or fabrication method, e.g., PLD, XRD, or RHEED), and finally uses said dictionary to produce an **HDF5/NeXus file** which complies with the **FAIR Principles** and the guidelines given within the context of the Italian PNRRfootnote:pnrr[PNRR stands for _National Recovery and Resilience Plan_.] **NFFA-DI**.
+
+Specifically, *{software-name}* is designed for *Pulsed Laser Deposition / PLD* fabrications.
+
+=== NFFA-DI and FAIR Principles
+PNRR (_Piano Nazionale di Ripresa e Resilienza_) is Italy's national recovery plan from the aftermaths of COVID-19. +
+*NFFA-DI* (_Nano Foundries and Fine Analysis - Digital Infrastructure_) is a project within this plan aimed at creating a distributed digital infrastructure for nanoscience and nanotechnology. In practice, NFFA-DI provides a unified cyber-platform for researchers to access advanced instrumentation, simulation tools, and data management services across multiple Italian research centers.
+
+Like most modern scientific projects NFFA-DI is _FAIR by design_, meaning it strives for total compliance to *FAIR Principles*. FAIR is the acronym of the four main characteristics all compliant projects should share:
+
+> * Findable: «Metadata and data should be easy to find for both humans and computers.»
+> * Accessible: «Once the user finds the required data, she/he/they need to know how they can be accessed, possibly including authentication and authorisation.»
+> * Interoperable: «The data usually need to be integrated with other data. In addition, the data need to interoperate with applications or workflows for analysis, storage, and processing.»
+> * Reusable: «Metadata and data should be well-described so that they can be replicated and/or combined in different settings.»
+> 
+> Source: link:{go-fair-site}[GO FAIR^]
+
+
+{software-name} contributes to NFFA-DI goals by enabling automated data harmonization: converting local PLD experiment records into a common, shareable format (NeXus) with a mutually agreed upon schema, thereby making the data interoperable across the entire NFFA-DI ecosystem.
+
+TIP: More info on NFFA-DI at link:{nffa-di-site}[nffa-di.it^].
+
+=== eLabFTW
+*eLabFTW* is an open-source, web-based electronic laboratory notebook and resource manager. It acts as a central digital hub for one or more laboratories, organizing information (as database entries) into two main constructs:
+
+* **Experiments**: They are the core feature of eLabFTW, can contain structured data (via custom JSON fields), unstructured text, timestamps, tags, links to files (attachments), and relations to database items.
+* **Resources** or **Items**: This is a separate, structured inventory for items like raw materials (targets, substrates), instruments (UHV machines) or samples. Each entry is built from customizable templates with defined metadata (e.g. for a substrate batch we have name, manufacturer, geometry, available pieces left...).
+
+Although separated into different database constructs, experiments and items all have their own unique, incremental internal ID, which we'll simply call *elabid* to distinguish it from other identifiers, with no academic utility but extremely important when dealing with eLabFTW from a developer's perspective.
+
+// method-specific
+In a software like eLabFTW where data can (and will) be spread out through multiple entries, a particularly useful feature is **linking**: the software allows you to link experiments or items with each other, using elabid's as identifiers. For a PLD deposition, you can link the experiment describing a single layer to the target used, the substrate, the PLD instrument and the sample produced itself (all of which are eLabFTW items). This creates a complete provenance graph which can be (not-so) easily resolved starting from the sample's metadata and a chain of HTTP requests.
+
+In this optic, {software-name} interacts with eLabFTW via its REST API (Application Programming Interface). It reads a starting sample's ID (the entry point), fetches the relevant JSON metadata, chains requests using the elabid's of the sample's linked resources and experiments, rebuilds the entire dataset and if available downloads attached instrument files (e.g., RHEED intensities, images) to package all of it into the final NeXus file.
+
+=== The output: HDF5 and NeXus files
+The output of {software-family} is an **HDF5 (Hierarchical Data Format ver. 5) file**, which is a powerful file format designed to store and organize large volumes of numerical data. It acts like a virtual file system inside a single file, using a hierarchical group/dataset structures in the same way a file system uses folders and files - with both elements having their own metadata; this way the file is self-describing, containing all relevant information like a small database. HDF5 also supports efficient slicing, compression and parallel I/O. The file extension of such format is `.h5`.
+
+On the other hand, *NeXus* is a common data standard [.underline]#built on top of HDF5#. It defines fixed conventions for naming groups, datasets and attributes, specifically for neutron, X-ray, and now materials science experiments. NeXus provides "application definitions" (like _NXpld_fabrication_ for PLD) that specify exactly which fields must/may appear. NeXus is also heavily promoted by _FAIRmat_, a German-based consortium, part of the NFDI, whose main mission is providing scientists «with a FAIR data infrastructure and the skills and tool they need to make the most of it»footnote:[As stated on their link:{fairmat-site}[website^].]. The file extension of such format is `.nxs`, but generally file viewers treat the two formats similarly.
+
+Last but not least, NeXus is also the format of choice for data sharing in the NFFA-DI guidelines. Which brings us to the reason why {software-family} exists.
+
+[#reading-nxs]
+==== Reading HDF5/NeXus files
+While writing an HDF5/NeXus file usually requires dedicated software and/or a good knowledge of programming and familiarity with specific libraries (like h5py), there are multiple ways to read these files even without such knowledge.
+
+One of such ways would be using the online NeXus file viewer of the NCNR (_NIST Center for Neutron Research_), available on their link:{ncnr-viewer}[website^]. The "_Browse..._" button at the bottom allows for uploading both h5 and nxs files, although drag and drop also works.
+
+Another similar but in my opinion more elegant online file viewer is the one hosted by the HDF5 Group: link:{hdf5-viewer}[MyHDF5^]. Other than the more modern appearance this viewer doesn't upload files to any remote server, with every operation happening locally in your browser; the drag and drop works better meaning you won't accidentally reload the page if you miss the dropping area, and the viewer also allows for opening multiple concurrent files, and downloading h5 files from URL.

docs/user-manual_02.adoc

@@ -0,0 +1,171 @@
+== Using the software
+WARNING: This software requires Python 3.12 or later. +
+The module *venv* and the package manager *pip* are also required.
+
+=== Downloading the source code
+IMPORTANT: Currently ({revdate}) the source code is hosted on a private Gitea instance, owned by {author}. +
+If the site is down for maintenance or temporarily unavailable please contact the webmaster via mailto:{email}[e-mail].
+
+// TO-DO: add link to direct download of package
+The source code can be acquired directly via *git*, or downloaded from the official repository on link:{repo-url}[Gitea D'Amico^].
+
+[source,bash,subs="verbatim,attributes"]
+----
+git clone {repo-url}.git {software-name}
+cd {software-name} # enter directory
+ls
+  LICENSE    docs/     output/           src/
+  README.md  glossary  requirements.txt  tests/
+----
+
+Optionally, you can access the code in the development branch by executing:
+[source,bash]
+----
+git checkout dev
+----
+
+=== Preparing the environment
+Before starting {software-name} {revnumber} requires a total of 6 modules to be installed, which are listed link:{repo-url}/src/branch/main/requirements.txt[here^]. Since installing a Python module system-wide is almost never a good idea, start by creating and activating a virtual environment.
+
+In the software folder, run:
+
+[source,bash]
+----
+# Calls venv module to create new Python virtual environment in .venv:
+python3 -m venv .venv
+# If command is successful, running ls should show a new .venv folder:
+ls -d .*
+  .venv
+# Activate venv:
+source .venv/bin/activate
+----
+
+.Most shells like Bash show very clearly when you're working inside a virtual environment.
+[#usage-venv]
+image::usage-venv.png[]
+
+At this point you're free to install the requirements through *pip*:
+[source,bash]
+----
+# Install from list in requirements.txt:
+pip install -r requirements.txt
+----
+
+Most of the warnings displayed by pip are safe and generally it's not dangerous to ignore them. +
+Unless pip exits abruptly returning an error, you environment is ready to work.
+
+=== Configuration through .env file
+// foggetaboutit
+Much like the previous step, configuring the software with your settings (API key, eLabFTW URL...) is something you do _una tantum_ and then usually forget about it.
+
+Inside the {software-name} folder there's a file called `.env.example`. Rename it removing ".example", then open it with your editor of choice. This is your *.env* (or *dotenv*) file.
+
+[source,bash]
+----
+mv .env.example .env
+vim .env
+# The file presents itself like this:
+ 1 | api_key=""
+ 2 | elabid=""
+ 3 | ELABFTW_API_URL="https://elabftw.fisica.unina.it/api/v2"
+ 4 | operative_unit="cnr-spin.na"
+----
+
+* *api_key* is your own personal eLabFTW API key. Generating one is an easy task explained in full detail below.
+* *elabid* is the elabid of the resource you'd like to select (your starting sample); this field can (and probably should) be left blank - in which case the application prompts you for an elabid on runtime, and your answer will not be stored meaning you can easily rerun the program with a different target.
+* *ELABFTW_API_URL* is the URL of your eLabFTW instance; if you're running this from the laboratories in Monte S. Angelo, Naples, you're probably leaving this field as it is.
+* *operative_unit* is the operative unit you ran your experiments from. It's only needed to compose the filename of the NeXus, which can be easily modified anytime later, and it's not necessary for creating the file itself.
+
+None of these fields are required, meaning you can technically skip this entire section. If any of the first three keys are blank or missing you will be prompted to provide the necessary info at runtime, and your answers will not be memorized - meaning e.g. you will have to provide your API key every time you run the program.
+
+NOTE: Do [.underline]#NOT# confuse .env with .venv: the first is a [.underline]#file# containing all the environmental variables you need to run {software-name} properly, the latter is a [.underline]#directory# containing your virtual environment with all the required modules.
+
+==== Generating an eLabFTW API key
+eLabFTW has its own link:{elabftw-apikey-docs}[API documentation^] on which you can rely. A new API key can be generated in the Settings → API Keys page by giving it a name and an access level:
+
+.Screenshot from our eLabFTW. The key must have a name and permissions. Naturally, the key you see here in clear has been invalidated.
+[#api-gen]
+image::usage-apigen.png[align=center,width=75%]
+
+The *name* of the key is a descriptor for you to remember why you created it in the first place - something like "parser_key01". The *permissions* can either be "_Read/Write_" or "_Read-Only_": in the first scenario the key may also be used to edit or create entries you own on eLabFTW, while read-only key only allow GET requests. {software-name} doesn't require writing permissions, so both options will do.
+
+[WARNING]
+.A few warnings.
+====
+* The key eLabFTW generates is [.underline]#only shown once#, then stored encrypted in the database. This means that after closing or refreshing the page the key [.underline]#is lost forever# if not saved on an external support. Which brings us to the second warning.
+* Store and protect your API key like you would your password, as [.underline]#it gives full/limited access to your account# exactly like your password, but without the protection given by 2FA/MFA. For this purpose there are many offline (like link:{keepass-site}[KeePass^]) or online (like link:{bitwarden-site}[BitWarden^]) **password managers**.
+* Your .env file is [.underline]#NOT# a safe place to _store_ your API key. Once pasted there be very careful who you share your files with, and be careful not to expose your key when sending your NeXus files to other computers. If you don't trust your awareness leave the api_key field blank and just paste your API key in the terminal every time you run {software-name}.
+====
+
+=== Running the program
+Open a terminal into the project folder. Before attempting to run the program:
+
+* Make sure your virtual environment is active, or if it isn't run: +
+`source .venv/bin/activate`
+* Make sure the required modules are installed, or if they aren't run:
+`pip install -r requirements.txt`
+* Make sure your .env file is properly set, or if it isn't make sure you know how to paste into the terminal the API key, the elabid of the required source and the URL of your eLabFTW instance (ending in `/api/v2`).
+
+When you're ready, run:
+[source,bash]
+====
+python3 src/main.py
+====
+
+If your .env file is completely filled out with valid values the only output you may read on the terminal are warnings or worst-case-scenario errors. Next chapter will cover all such cases. If your .env file lacks one or more values you will be asked to input the missing info at runtime.
+
+==== Entering missing values if prompted
+If you decide to run without a valid .env file (again, worst-case-scenario) you will be prompted to enter the required information directly into the terminal.
+
+.The difference between running {software-name} with no .env, and with a properly filled out .env. Same parameters, same output.
+[#usage-difference-dotenv]
+image::usage-difference-dotenv.png[]
+
+First and foremost you will be prompted for a valid API key. To paste your key in the terminal either right-click (_PowerShell_ and other terminal emulators), right-click > _Paste_, Ctrl + Shift + V (on most terminal emulators) or middle-click (Linux).
+
+Then you will be prompted for an elabid - which is a positive integer number. You can find your sample's elabid on eLabFTW, above the sample's name and before the sample's label and status. See xref:usage-elabid[xrefstyle="short"].
+
+Last but not least you will be prompted for a valid eLabFTW API endpoint URL. Such URL is composed by the base URL of your eLabFTW instance, closing with `/api/v2`. For instance: _++https://elabftw.fisica.unina.it/api/v2++_. +
+{software-name} {revnumber} will not validate such URL or return some very specific error.
+
+WARNING: Make sure the URL you paste doesn't end with a trailing slash. +
+++https://elabftw.fisica.unina.it/api/v2++ ✓ +
+++https://elabftw.fisica.unina.it/api/v2/++ ✗
+
+You won't be prompted for the operative unit, so that will require either setting up a .env or manually editing your NeXus files' names. The list of officially approved acronyms for the operative units can be consulted on NFFA-DI's link:{nffa-di-uo-acronyms}[official website^].
+
+.Where to find the elabid of a sample.
+[#usage-elabid]
+image::usage-elabid.png[]
+
+==== Retrieving and verifying your file
+By default the NeXus file will be saved in the `output/` folder. Currently ({revdate}) the software will also save a JSON dictionary with the full chain of all metadata collected on the sample. There is also an `attachments/` folder containing all the attachments downloaded during execution, which will be removed later on.
+
+The file will be recognizable by its name, which should already be in compliance with the following NFFA-DI naming guidelines:
+
+> «Each file generated in the context of a Proposal stored on OFED must use the following naming convention: ++nffa-di_[proposal_id]_[UO]_[UO_internal_id]++» - where _proposal_id_ is the approved ID of the research proposal, _UO_ is the link:{nffa-di-uo-acronyms}[official code^] of the operative unit, and «_UO_internal_id_ is a combination of the technique/instrument acronym and an Experiment ID freely decided». +
+> «Each file generated in the context of an In-house Research Project stored on OFED must use the following naming convention: nffa-di_[UO]_[project_id]_key, where the first part of the name adheres to the name of the bucket, while key is arbitrary.»
+>
+> Source: link:{nffa-di-rdp}[NFFA-DI Research Data Policy^]
+
+This means that the accepted filename for a NeXus file of a PLD, where proposal_id is _EXMPL01_, the operative unit is CNR-SPIN Naples and the sample's internal ID is _Na-26-012_ the filename will be:
+
+image::usage-name.png[]
+
+A NeXus file can be verified through one of the readers listed in xref:reading-nxs[xrefstyle="short"]. Pay attention to the following aspects:
+
+* Do I visualize the file correctly?
+* Does the file respect the fabrication method's schema?
+* Is every required field present? Do I read the same values on eLabFTW and in the NeXus file? Are the units of measurement present?
+* Can I visualize heatmaps and N-axis graphs correctly?
+
+If the answer to all previous questions is "Yes", then the output file is NFFA-DI compliant.
+
+////
+collect nxs file
+filename is: [paste link of guidelines here]
+output folder is: output/
+attachments will be in: output/attachments - to be removed
+???
+profit
+////

docs/user-manual_03.adoc

@@ -0,0 +1,3 @@
+== Troubleshooting
+
+WIP

docs/user-manual_main.adoc

@@ -0,0 +1,41 @@
+= {software-name} User Manual: eLabFTW to NeXus Parser for PLD Fabrications 
+:author: Emanuele D'Amico
+:description: eLabFTW to NeXus Parser for PLD Fabrications
+:doctype: book
+:email: emanuele+expars@damico.ing
+:imagesdir: images
+:keywords: nffa-di, elabftw, nexus, parser, data science, mdmc, naples, cnr-spin, cnr, spin institute, python, hdf5, cli
+:revdate: 2026-05-14
+:revnumber: v0.2.1
+:revremark: alpha untested
+:stem: latexmath
+:toc:
+// custom attributes
+:disclamer: I'm in no position to give anyone coding/development/programming/testing tips. The only tips I can give you are based on my personal knowledge of this specific project.
+:software-family: eXPars
+:software-name: {software-family}-PLD
+:repo-url: https://gitea.damico.ing/emanuele/eXParser-PLD
+:repo-ssh: ssh://git@gitea.damico.ing/emanuele/eXParser-PLD.git
+:elabftw-apikey-docs: https://doc.elabftw.net/docs/usage/api/#generating-a-key
+:elabftw-site: https://elabftw.net
+:nffa-di-site: https://nffa-di.it/en/about-us/project/
+:nffa-di-rdp: https://nffa-di.it/it/research-data-policy/#3.1
+:nffa-di-uo-acronyms: https://nffa-di.it/en/uo-acronyms-for-data-infrastructure-naming-convention
+:go-fair-site: https://www.go-fair.org/fair-principles/
+:fairmat-site: https://www.fairmat-nfdi.eu/fairmat/about-fairmat/consortium-fairmat#mission
+:keepass-site: https://keepassxc.org/
+:bitwarden-site: https://bitwarden.com/
+:ncnr-viewer: https://ncnr.nist.gov/ncnrdata/view/nexus-hdf-viewer.html
+:hdf5-viewer: https://myhdf5.hdfgroup.org/
+
+include::user-manual_01.adoc[]
+
+include::user-manual_02.adoc[]
+
+//include::user-manual_03.adoc[]
+
+///////////////////////////////////////////////////////////////////////////
+// Look out for "method-specific" comments I've left before sections
+// containing information about one method in particulare (e.g. PLD fab.)
+// because that needs to be edited when writing the user manuals of other
+// eXParser's

requirements.txt

@@ -1,2 +1,6 @@
 requests
 asyncio
+h5py
+pillow
+elabapi_python
+dotenv

src/APIHandler.py

@@ -1,41 +1,169 @@
-import requests
+import os, requests
+from dotenv import load_dotenv
+from getpass import getpass
+import elabapi_python as elabapi
+
 
 class APIHandler:
-    '''
+    """
-    Class to standardize the format of the headers of our http requests.
+    Class which handles all interactions with the eLabFTW API.
-    '''
+    It provides methods to retrieve data from the API and download attachments.
+    It relies minimally on the elabapi-python library, which is used only for downloading attachments
+    (since the API doesn't support downloading attachments AFAIK).
+
+    Args:
+        api_key: str:           A valid API key for the eLabFTW instance where the data is stored, with permissions to access the relevant entries.
+                                eLabFTW's API keys are well documented here: https://doc.elabftw.net/docs/usage/api/.
+                                If you don't have an API key and are uncapable of creating one, contact your eLabFTW administrator.
+                                Or RTFM and create one yourself, it's not that hard.
+        ELABFTW_API_URL: str:   Complete URL of the eLabFTW instance's root for the API endpoints.
+                                In full caps because it won't (shouldn't) be changed much.
+    """
+
     # TO-DO: remove static url.
-    def __init__(self, apikey="", ELABFTW_API_URL="https://elabftw.fisica.unina.it/api/v2"):
+    def __init__(self, api_key="", ELABFTW_API_URL=None):
-        '''Init method, apikey suggested but not required (empty by default).'''
+        """Init method, api_key suggested but not required (empty by default)."""
-        self.auth = {"Authorization" : apikey}
+        # if not ELABFTW_API_URL:
-        self.content = {"Content-Type" : "application/json"}
+        #    load_dotenv()
+        #    ELABFTW_API_URL = os.getenv("ELABFTW_API_URL") or input(
+        #        "Enter a valid eLabFTW API URL (ends with '/api/v2)': "
+        #    )
+        self.api_key = api_key
+        self.auth = {"Authorization": api_key}
+        self.content = {"Content-Type": "application/json"}
         self.header = {**self.auth, **self.content}
         self.elaburl = ELABFTW_API_URL
-    def get_entry_from_elabid(self, elabid, entryType="items"):
-        '''
-        Method which returns a resource's raw data (as dictionary) from its elabid and entry type.
 
-        Entry type can be either "experiments" or "items".
+    def get_entry_from_elabid(self, elabid, entryType="items"):
-        '''
+        """
-        # TO-DO: validation and error handling on entryType value.
+        Returns raw data (as dictionary) from its elabid and entry type.
+
+        Args:
+            elabid: int:     elabftw internal id of the selected resource.
+            entryType: str:  Resource type. Anything other than "experiments" or "items" WILL raise an error.
+        """
+        if entryType not in ["experiments", "items"]:
+            raise Exception(
+                "You can only download attachments from experiments or items."
+            )
+
         header = self.header
         response = requests.get(
-            headers = header,
+            headers=header, url=f"{self.elaburl}/{entryType}/{elabid}", verify=True
-            url = f"{self.elaburl}/{entryType}/{elabid}",
-            verify=True
         )
-        if response.status_code // 100 in [1,2,3]:
+
-            entry_data = response.json()
+        # Response is 5xx = server error:
-            return entry_data
+        if response.status_code // 100 == 5:
-        elif response.status_code // 100 == 4:
+            raise ConnectionError(
+                f"There's a problem on the server. Status code: {response.status_code}."
+            )
+
+        # Response is 4xx = client error:
+        if response.status_code // 100 == 4:
             match response.status_code:
-                case 401|403:
+                case 401 | 403:
-                    raise ConnectionError(f"Invalid API key or authentication method.")
+                    # Forbidden or unauthorized:
+                    raise ConnectionError(
+                        f"Invalid API key, authentication method or elabid. Check if an item with ID = {elabid} actually exists."
+                    )
                 case 404:
-                    raise ConnectionError(f"404: Not Found. This means there's no resource with this elabid (wrong elabid?) on your eLabFTW (wrong endpoint?).")
+                    # Lapalissian:
+                    raise ConnectionError(
+                        "404: Not Found. This means there's no resource with this elabid (wrong elabid?) on your eLabFTW (wrong endpoint?)."
+                    )
                 case 400:
-                    raise ConnectionError(f"400: Bad Request. This means the API endpoint you tried to reach is invalid. Did you tamper with the source code? If not, contact the developer.")
+                    # I genuinely have no idea:
+                    raise ConnectionError(
+                        "400: Bad Request. This means the API endpoint you tried to reach is invalid. Did you tamper with the source code? If not, contact the developer."
+                    )
                 case _:
-                    raise ConnectionError(f"HTTP request failed with status code: {response.status_code} (NOTE: 4xx means user's fault).")
+                    # For some fucking reason, this is the only error I actually get from the API...
-        else:
+                    raise ConnectionError(
-            raise ConnectionError(f"There's a problem on the server. Status code: {response.status_code}.")
+                        f"HTTP request failed with status code: {response.status_code} (NOTE: 4xx means user's fault)."
+                    )
+
+        entry_data = response.json()
+        return entry_data
+
+    def download_attachment_data(self, elabid, upload_id, entryType="experiments"):
+        """
+        Downloads a specific attachment of a certain eLabFTW experiment (default) or item.
+        Only returns its binary data. Use method download_attachment_to_disk to save to file.
+
+        NOTE: Output is a dictionary where:
+            * The key is the attachment's filename;
+            * The value is the attachment's binary data.
+
+        Args:
+            elabid: int:     eLabFTW internal ID of the selected resource.
+            upload_id: int:  eLabFTW internal ID of the selected upload.
+            entryType: str:  Resource type. Anything other than "experiments" or "items" WILL raise an error.
+        """
+        if entryType not in ["experiments", "items"]:
+            raise Exception(
+                "You can only download attachments from experiments or items."
+            )
+
+        config = elabapi.Configuration()
+        config.api_key["api_key"] = self.api_key
+        config.api_key_prefix["api_key"] = "Authorization"
+        config.host = self.elaburl
+        config.debug = False
+        api_client = elabapi.ApiClient(config)
+        api_client.set_default_header(
+            header_name="Authorization", header_value=self.api_key
+        )
+        uploads_api = elabapi.UploadsApi(api_client)
+
+        # Scans through the attachments and selects the one with corresponing ID.
+        attachment = {
+            upload.real_name: uploads_api.read_upload(
+                entryType, elabid, upload_id, format="binary", _preload_content=False
+            ).data
+            for upload in uploads_api.read_uploads(entryType, elabid)
+            if upload.id == upload_id
+        }
+
+        return attachment
+
+    def download_attachment_to_disk(
+        self,
+        elabid,
+        upload_id,
+        entryType="experiments",
+        dump_dir="output/attachments",
+        # persistent=True,
+    ):
+        """
+        Downloads a specific attachment of a certain eLabFTW experiment (default) or item.
+        Downloads their binary data through method download_attachments_data and dumps it to dump_dir.
+        Returns full path of the output file.
+
+        Args:
+            elabid: int:        eLabFTW internal ID of the selected resource.
+            upload_id: int:     eLabFTW internal ID of the selected upload.
+            entryType: str:     Resource type. Anything other than "experiments" or "items" WILL raise an error.
+            dump_dir: str:      Directory to which to save the attachments. Default is "output/attachments".
+            persistent: bool:   [Unused] Decides if the files will stay on disk after all operations are completed.
+                                If set to False, deletes the file upon exiting. Default = True.
+        """
+
+        if entryType not in ["experiments", "items"]:
+            raise Exception(
+                "You can only download attachments from experiments or items."
+            )
+
+        uploads = self.download_attachment_data(elabid, upload_id, entryType=entryType)
+        for file in uploads:
+            raw_data = uploads[file]
+            full_path = os.path.join(dump_dir, f"exp{elabid}-{file}")
+            with open(full_path, "wb") as f:
+                f.write(raw_data)
+        return full_path
+
+
+# Testing methods
+if __name__ == "__main__":
+    api_key = getpass("Paste API key here [no echo]: ")
+    handler = APIHandler(api_key=api_key)
+    handler.download_attachment_to_disk(elabid=58, upload_id=81)

src/classes.py

@@ -1,8 +1,10 @@
 import os, json, requests
+from getpass import getpass
 from APIHandler import APIHandler
 
+
 class Layer:
-    '''
+    """
     Layer(layer_data) - where layer_data is a Python dictionary.
 
     Meant to be used for eLabFTW Experiments of the "PLD Deposition" category.
@@ -10,21 +12,33 @@ class Layer:
     eLabFTW experiments contain most of the data required by the NeXus file - although every layer is on a different eLab entry;
     unfortunately, some data like the target's chemical formula must be retrieved through additional HTTP requests.
     Attributes 'target_elabid', 'rheed_system_elabid' and 'laser_system_elabid' contain elabid's for these resources, which are all items.
-    '''
+    """
+
     def __init__(self, layer_data):
+        """
+        Properties/Attributes:
+            Too many to list.
+        """
         try:
+            self.elabid = layer_data["id"]
+            self.operator = layer_data["fullname"]
             self.extra = layer_data["metadata_decoded"]["extra_fields"]
-            self.layer_number = self.extra["Layer Progressive Number"]["value"] # integer
+            self.uploads = layer_data["uploads"]  # dict
-            self.target_elabid = self.extra["Target"]["value"] # elabid
+            self.layer_number = self.extra["Layer Progressive Number"][
-            self.rheed_system_elabid = self.extra["RHEED System"]["value"] # elabid
+                "value"
-            self.laser_system_elabid = self.extra["Laser System"]["value"] # elabid
+            ]  # integer
-            self.start_time = layer_data.get("created_at")
+            self.target_elabid = self.extra["Target"]["value"]  # elabid
-            self.operator = layer_data.get("fullname")
+            self.laser_system_elabid = self.extra["Laser System"]["value"]  # elabid
-            self.description = layer_data.get("body")
+            self.chamber_elabid = self.extra["Chamber"]["value"]  # elabid
+            self.rheed_system_elabid = self.extra["RHEED System"]["value"]  # elabid
             self.deposition_time = self.extra["Duration"]["value"]
+            self.deposition_time_unit = self.extra["Duration"]["unit"]
             self.repetition_rate = self.extra["Repetition rate"]["value"]
+            self.repetition_rate_unit = self.extra["Repetition rate"]["unit"]
             try:
-                self.number_of_pulses = (float(self.deposition_time) * float(self.repetition_rate)).__floor__()
+                self.number_of_pulses = (
+                    float(self.deposition_time) * float(self.repetition_rate)
+                ).__floor__()
             except ValueError:
                 # Since number_of_pulses is required, if it can't be calculated raise error:
                 raise ValueError("""
@@ -32,16 +46,33 @@ class Layer:
     This has to be an error, since these fields are required by the NeXus standard.
     Please edit your eLabFTW entry and retry.
                 """)
-            self.temperature = self.extra["Heater temperature"]["value"] # Note: this field used to have a trailing space in its name
+            self.temperature = self.extra["Heater temperature"][
-            self.process_pressure = self.extra["Process pressure"]["value"] # Note: this field used to have a trailing space in its name
+                "value"
+            ]  # Note: this field used to have a trailing space in its name
+            self.temperature_unit = self.extra["Heater temperature"]["unit"]
+            self.process_pressure = self.extra["Process pressure"][
+                "value"
+            ]  # Note: this field used to have a trailing space in its name
+            self.process_pressure_unit = self.extra["Process pressure"]["unit"]
             self.heating_method = self.extra["Heating Method"]["value"]
             self.layer_thickness = self.extra["Thickness"]["value"]
+            self.layer_thickness_unit = self.extra["Thickness"]["unit"]
             self.buffer_gas = self.extra["Buffer gas"]["value"]
             self.heater_target_distance = self.extra["Heater-target distance"]["value"]
-            self.laser_fluence = self.extra["Laser Intensity"]["value"] # here fluence = intensity
+            self.heater_target_distance_unit = self.extra["Heater-target distance"][
+                "unit"
+            ]
+            self.laser_fluence = self.extra["Laser Intensity"][
+                "value"
+            ]  # here fluence = intensity
+            self.laser_fluence_unit = "J/(s cm^2)"
             self.laser_spot_area = self.extra["Spot Area"]["value"]
+            self.laser_spot_area_unit = "mm^2"
             try:
-                self.laser_energy = (float(self.laser_fluence) * float(self.laser_spot_area)).__round__(3)
+                self.laser_energy = (
+                    float(self.laser_fluence) * float(self.laser_spot_area) / 100
+                ).__round__(3)
+                self.laser_energy_unit = "J/s"
             except ValueError:
                 # Since laser_energy is NOT required, if it can't be calculated warn user but allow the software to continue execution:
                 print("""
@@ -50,53 +81,194 @@ class Layer:
     Setting Laser Energy to NoneType.
                 """)
                 # Placeholder
-                self.laser_energy = None
+                self.laser_energy = "N/A"
+                self.laser_energy_unit = "J/s"
             # Laser rasternig section
-            self.laser_rastering_geometry = self.extra["Laser Rastering Geometry"]["value"]
+            self.laser_rastering_geometry = self.extra["Laser Rastering Geometry"][
-            self.laser_rastering_positions = self.extra["Laser Rastering Position"]["value"]
+                "value"
-            self.laser_rastering_velocities = self.extra["Laser Rastering Speed"]["value"]
+            ]
+            self.laser_rastering_positions = self.extra["Laser Rastering Position"][
+                "value"
+            ]
+            self.laser_rastering_velocities = self.extra["Laser Rastering Speed"][
+                "value"
+            ]
             # Pre annealing section
             self.pre_annealing_ambient_gas = self.extra["Buffer gas Pre"]["value"]
             self.pre_annealing_pressure = self.extra["Process pressure Pre"]["value"]
-            self.pre_annealing_temperature = self.extra["Heater temperature Pre"]["value"]
+            self.pre_annealing_temperature = self.extra["Heater temperature Pre"][
+                "value"
+            ]
             self.pre_annealing_duration = self.extra["Duration Pre"]["value"]
+            self.pre_annealing_pressure_unit = self.extra["Process pressure Pre"][
+                "unit"
+            ]
+            self.pre_annealing_temperature_unit = self.extra["Heater temperature Pre"][
+                "unit"
+            ]
+            self.pre_annealing_duration_unit = self.extra["Duration Pre"]["unit"]
             # Post annealing section
             self.post_annealing_ambient_gas = self.extra["Buffer gas PA"]["value"]
             self.post_annealing_pressure = self.extra["Process pressure PA"]["value"]
-            self.post_annealing_temperature = self.extra["Heater temperature PA"]["value"]
+            self.post_annealing_temperature = self.extra["Heater temperature PA"][
+                "value"
+            ]
             self.post_annealing_duration = self.extra["Duration PA"]["value"]
+            self.post_annealing_pressure_unit = self.extra["Process pressure PA"][
+                "unit"
+            ]
+            self.post_annealing_temperature_unit = self.extra["Heater temperature PA"][
+                "unit"
+            ]
+            self.post_annealing_duration_unit = self.extra["Duration PA"]["unit"]
+
             # Rejected but suggested by the NeXus standard:
-            #self.laser_rastering_coefficients = None
+            # self.laser_rastering_coefficients = None
         except KeyError as k:
             # Some keys are not required and can be called through the .get() method - which is permissive and allows null values;
             # Other keys are required so if they can't be called (invalid or null) raise error and stop execution of the program:
-            raise KeyError(f"The provided dictionary lacks a \"{k}\" key. Check the deposition layer entry on eLabFTW and make sure you used the correct Experiment template.")
+            raise KeyError(
+                f'The provided dictionary lacks a "{k}" key. Check the deposition layer entry on eLabFTW and make sure you used the correct Experiment template.'
+            )
+        # Optional
+        self.start_time = layer_data.get("created_at") or None
+        self.description = layer_data.get("body") or None
+
+    def get_instruments(self, api_key, ELABFTW_API_URL):
+        """
+        Retruns a dictionary of all the instruments used to create the layer.
+        The format of the dictionary is:
+            {
+                "laser_system": str,
+                "deposition_chamber": str,
+                "rheed_system": str
+            }
+
+        Args:
+            api_key: str:           A valid API key for the eLabFTW instance where the data is stored, with permissions to access the relevant entries.
+                                    eLabFTW's API keys are well documented here: https://doc.elabftw.net/docs/usage/api/.
+                                    If you don't have an API key and are uncapable of creating one, contact your eLabFTW administrator.
+                                    Or RTFM and create one yourself, it's not that hard.
+            ELABFTW_API_URL: str:   URL for the API root endpoint of the eLabFTW instance. Ends with '/api/v2' - no trailing slash.
+        """
+        raw_lasersys_data = APIHandler(api_key, ELABFTW_API_URL).get_entry_from_elabid(
+            self.laser_system_elabid, entryType="items"
+        )
+        raw_chamber_data = APIHandler(api_key, ELABFTW_API_URL).get_entry_from_elabid(
+            self.chamber_elabid, entryType="items"
+        )
+        raw_rheedsys_data = APIHandler(api_key, ELABFTW_API_URL).get_entry_from_elabid(
+            self.rheed_system_elabid, entryType="items"
+        )
+        instruments_used = {
+            "laser_system": raw_lasersys_data.get("title") or None,
+            "deposition_chamber": raw_chamber_data.get("title") or None,
+            "rheed_system": raw_rheedsys_data.get("title") or None,
+        }
+        return instruments_used
+
+    def list_attachments(self):
+        """
+        Returns a dictionary of all the attachments linked to the layer, where:
+            * Each key is the attachment's progressive ID (0, 1...);
+            * Each value is a dictionary containing the attachment's elabid, filename, hashname and related experiment elabid (= self.elabid).
+
+        Data is already in layer_data, so the API key is unrequired. Same goes for:
+            * fetch_textual_uploads() - no arguments;
+            * fetch_images() - no arguments.
+
+        Exception: returns {} (empty dictionary) if no uploads/attachments on Layer.
+        """
+        # Remember: Layers are experiments, so we only need to look for attachments in the experiment endpoint.
+        if self.uploads == []:
+            return {}
+        attachments = {
+            self.uploads.index(attachment): {
+                "id": attachment["id"],
+                "filename": attachment["real_name"],
+                "hashname": attachment["long_name"],
+                "related_experiment": attachment["item_id"],
+            }
+            for attachment in self.uploads
+        }
+        return attachments
+
+    def fetch_textual_uploads(self):
+        """
+        Starting from the list of attachments, filters out and returns a list of the textual uploads linked to the layer, which can be either plain text, csv, tsv etc.
+        Returns only their names, so that the user may select which one to import into the NeXus file as a dataset.
+
+        It only looks for .txt, .csv and .tsv files, although it could be easily modified to include other formats.
+        It is also file extension-sensitive, so anything not ending with .txt, .csv or .tsv won't be retrieved.
+        That's because the API (v5.3.11) doesn't provide MIME Type or similar metadata on the attachments, so the only way to know if an attachment is an image or not is through its filename.
+        """
+        attachments = self.list_attachments()
+        textual_uploads = {
+            attachment: attachments[attachment]
+            for attachment in attachments
+            if attachments[attachment]["filename"][-4:] in (".txt", ".csv", ".tsv")
+        }
+        return textual_uploads
+
+    def fetch_images(self):
+        """
+        Starting from the list of attachments, filters out and returns a Starting from the list of attachments, filters out and returns a list of all the (PNG or BMP) images attached to the layer.
+        Hopefully one of them is a RHEED pattern.
+        Returns only their names, so that the user may select which one to import into the NeXus file as a RHEED acquisition.
+
+        It only looks for .png and .bmp files, although it could be easily modified to include other formats.
+        It is also file extension-sensitive, so anything not ending with .png or .bmp won't be retrieved, even if it's an actual image.
+        That's because the API (v5.3.11) doesn't provide MIME Type or similar metadata on the attachments, so the only way to know if an attachment is an image or not is through its filename.
+        """
+        attachments = self.list_attachments()
+        images = {
+            attachment: attachments[attachment]
+            for attachment in attachments
+            if attachments[attachment]["filename"][-4:] in (".png", ".bmp")
+        }
+        return images
+
 
 class Entrypoint:
-    '''
+    """
     Entrypoint(sample_data) - where sample_data is a Python dictionary.
 
     Meant to be used for eLabFTW Resources of the "Sample" category.
 
     The entrypoint is the starting point of the process of resolving the data chain.
     The entrypoint must be a dictionary containing the data of a sample, created directly from the JSON of the item endpoint on eLabFTW - which can be done through the function get_entry_from_elabid.
-    '''
+    """
+
     def __init__(self, sample_data):
+        """
+        Properties/Attributes:
+            * name: str:                        Name of the sample. Fairly important, and always present unless someone screws up REALLY bad.
+            * linked_items: dict:               Dictionary generated by eLabFTW containing metadata on the items linked to the entrypoint.
+            * batch_elabid: int:                eLabFTW internal id of the batch of the substrate used as the foundation of the sample.
+            * proposal: int:                    eLabFTW internal id of the proposal linked to the sample.
+            * linked_experiments: dict:         Dictionary generated by eLabFTW containing metadata on the experiments linked to the entrypoint.
+            * linked_experiments_elabid: list:  List of eLabFTW internal id's of the experiments linked to the entrypoint.
+        """
         try:
+            self.name = sample_data["title"]
             self.extra = sample_data["metadata_decoded"]["extra_fields"]
-            self.linked_items = sample_data["items_links"] # dict
+            self.linked_items = sample_data["items_links"]  # dict
-            self.batch_elabid = self.extra["Substrate batch"]["value"] # elabid
+            self.batch_elabid = self.extra["Substrate batch"]["value"]  # elabid
-            self.linked_experiments = sample_data["related_experiments_links"] # dict
+            self.proposal = self.extra["Proposal"].get("value") or None  # proposal
-            self.linked_experiments_elabid = [ i["entityid"] for i in self.linked_experiments ] # list of elabid
+            self.linked_experiments = sample_data["related_experiments_links"]  # dict
+            self.linked_experiments_elabid = [
+                i["entityid"] for i in self.linked_experiments
+            ]  # list of elabid
         except KeyError as k:
             # Some keys are not required and can be called through the .get() method - which is permissive and allows null values;
             # Other keys are required so if they can't be called (invalid or null) raise error and stop execution of the program:
-            raise KeyError(f"The provided dictionary lacks a \"{k}\" key. Check the sample entry on eLabFTW and make sure you used the correct Resource template.")
+            raise KeyError(
-        # Non-required attributes:
+                f'The provided dictionary lacks a "{k}" key. Check the sample entry on eLabFTW and make sure you used the correct Resource template.'
-        self.name = sample_data.get("title") or None # error prevention is more important than preventing empty fields here
+            )
+
 
 class Material:
-    '''
+    """
     Material(material_data) - where material_data is a Python dictionary.
 
     Meant to be used for eLabFTW Resources of either the "PLD Target" or the "Substrate" categories.
@@ -105,64 +277,199 @@ class Material:
         * Name and formula;
         * Shape and dimensions;
         * Misc.
-    '''
+    """
+
     def __init__(self, material_data):
+        """
+        Properties/Attributes:
+            * name: str:            Name of the material.
+            * compound_elabid: int: eLabFTW internal id of the compound.
+            * dimensions: str:      Dimensions of the material, in standard format.
+                                    The class recognizes the unit of measurement and acts consequently.
+            * dimensions_unit: str: Unit of measurement - either "mm x mm", "inches" or None.
+        """
         try:
-            self.name = material_data["title"] # required
+            self.name = material_data["title"]  # required
             self.extra = material_data["metadata_decoded"]["extra_fields"]
             self.compound_elabid = self.extra["Compound"]["value"]
-            self.dimensions = self.extra["Size"]["value"]
+            self.dimensions = str(
+                self.extra["Size"]["value"]
+            )  # strings have a .count() method
+            if self.dimensions.count("mm") == 2:
+                self.dimensions_unit = "mm x mm"
+            elif self.dimensions[-1] == '"':
+                self.dimensions_unit = "inches"
+            else:
+                self.dimensions_unit = None
         except KeyError as k:
             # Some keys are not required and can be called through the .get() method - which is permissive and allows null values;
             # Other keys are required so if they can't be called (invalid or null) raise error and stop execution of the program:
-            raise KeyError(f"The provided dictionary lacks a \"{k}\" key. Check the target/substrate entry on eLabFTW and make sure you used the correct Resource template.")
+            raise KeyError(
-    def get_compound_data(self, apikey):
+                f'The provided dictionary lacks a "{k}" key. Check the target/substrate entry on eLabFTW and make sure you used the correct Resource template.'
-        raw_compound_data = APIHandler(apikey).get_entry_from_elabid(self.compound_elabid, entryType="items")
+            )
+
+    def get_compound_data(self, apikey, ELABFTW_API_URL):
+        """
+        Returns a dictionary with the relevant data on the compound of which the material is made.
+        The format of the dictionary is:
+            {
+                "name": str,
+                "chemical_formula": str,
+                "cas_number": str
+            }
+
+        Args:
+            api_key: str:           A valid API key for the eLabFTW instance where the data is stored, with permissions to access the relevant entries.
+                                    eLabFTW's API keys are well documented here: https://doc.elabftw.net/docs/usage/api/.
+                                    If you don't have an API key and are uncapable of creating one, contact your eLabFTW administrator.
+                                    Or RTFM and create one yourself, it's not that hard.
+            ELABFTW_API_URL: str:   URL for the API root endpoint of the eLabFTW instance. Ends with '/api/v2' - no trailing slash.
+        """
+        raw_compound_data = APIHandler(apikey, ELABFTW_API_URL).get_entry_from_elabid(
+            self.compound_elabid, entryType="items"
+        )
         name = raw_compound_data["title"]
         extra = raw_compound_data["metadata_decoded"]["extra_fields"]
         formula = extra.get("Chemical formula")
-        cas = extra.get("CAS number ") or { "value": None }
+        cas = extra.get("CAS number ") or {"value": None}
         compound_data = {
-            "name" : name,
+            "name": name,
-            "chemical_formula" : formula.get("value"),
+            "chemical_formula": formula.get("value"),
-            "cas_number" : cas.get("value")
+            "cas_number": cas.get("value"),
         }
         return compound_data
-    def get_compound_formula(self, apikey):
+
-        formula = self.get_compound_data(apikey).get("chemical_formula")
+    def get_compound_formula(self, apikey, ELABFTW_API_URL):
+        """
+        Returns a string with the chemical formula of the compound.
+
+        Args:
+            api_key: str:           A valid API key for the eLabFTW instance where the data is stored, with permissions to access the relevant entries.
+                                    eLabFTW's API keys are well documented here: https://doc.elabftw.net/docs/usage/api/.
+                                    If you don't have an API key and are uncapable of creating one, contact your eLabFTW administrator.
+                                    Or RTFM and create one yourself, it's not that hard.
+            ELABFTW_API_URL: str:   URL for the API root endpoint of the eLabFTW instance. Ends with '/api/v2' - no trailing slash.
+        """
+        formula = self.get_compound_data(apikey, ELABFTW_API_URL).get(
+            "chemical_formula"
+        )
         return formula
 
+
 class Substrate(Material):
+    """
+    Substrate(material_data) - where material_data is a Python dictionary.
+
+    Inherits from Material and it's meant to be used exclusively for eLabFTW Resources of the "Substrate" category.
+    """
+
     def __init__(self, material_data):
+        """
+        Properties/Attributes common to all Materials:
+            * name: str:            Name of the material.
+            * compound_elabid: int: eLabFTW internal id of the compound.
+            * dimensions: str:      Dimensions of the material, in standard format.
+                                    The class recognizes the unit of measurement and acts consequently.
+            * dimensions_unit: str: Unit of measurement - either "mm x mm", "inches" or None.
+
+        Specific properties/attributes:
+            * orientation: str:
+            * miscut_angle: str:
+            * miscut_angle_unit: str:
+            * miscut_direction: str:
+            * thickness: str:
+            * thickness_unit: str:
+            * surface_treatment: str:
+            * manufacturer: str:
+            * batch_id: str:
+        """
         super().__init__(material_data)
         try:
             self.orientation = self.extra["Orientation"]["value"]
             self.miscut_angle = self.extra["Miscut Angle"]["value"]
+            self.miscut_angle_unit = self.extra["Miscut Angle"]["unit"]
             self.miscut_direction = self.extra["Miscut Direction"]["value"]
             # Not present (yet) on eLabFTW for Substrates:
-            self.thickness = None #self.extra["Thickness"]["value"]
+            self.thickness = ""  # self.extra["Thickness"]["value"]
+            self.thickness_unit = "μm"  # self.extra["Thickness"]["unit"]
             self.surface_treatment = self.extra["Surface treatment"]["value"]
             self.manufacturer = self.extra["Supplier"]["value"]
             self.batch_id = self.extra["Batch ID"]["value"]
         except KeyError as k:
-            raise KeyError(f"The provided dictionary lacks a \"{k}\" key - which is specific for substrates. Check the {self.name} substrate entry on eLabFTW and make sure you used the correct Resource template.")
+            raise KeyError(
+                f'The provided dictionary lacks a "{k}" key - which is specific for substrates. Check the {self.name} substrate entry on eLabFTW and make sure you used the correct Resource template.'
+            )
+
 
 class Target(Material):
+    """
+    Target(material_data) - where material_data is a Python dictionary.
+
+    Inherits from Material and it's meant to be used exclusively for eLabFTW Resources of the "PLD Target" category.
+    """
+
     def __init__(self, material_data):
+        """
+        Properties/Attributes common to all Materials:
+            * name: str:            Name of the material.
+            * compound_elabid: int: eLabFTW internal id of the compound.
+            * dimensions: str:      Dimensions of the material, in standard format.
+                                    The class recognizes the unit of measurement and acts consequently.
+            * dimensions_unit: str: Unit of measurement - either "mm x mm", "inches" or None.
+
+        Specific properties/attributes:
+            * thickness: str:
+            * thickness_unit: str:
+            * shape: str:
+            * solid_form: str:
+            * manufacturer: str:
+        """
         super().__init__(material_data)
         try:
             self.thickness = self.extra["Thickness"]["value"]
+            self.thickness_unit = self.extra["Thickness"]["unit"]
             self.shape = self.extra["shape"]["value"]
             self.solid_form = self.extra["Solid form"]["value"]
             self.manufacturer = self.extra["Supplier"]["value"]
         except KeyError as k:
-            raise KeyError(f"The provided dictionary lacks a \"{k}\" key - which is specific for PLD targets. Check the {self.name} target entry on eLabFTW and make sure you used the correct Resource template.")
+            raise KeyError(
+                f'The provided dictionary lacks a "{k}" key - which is specific for PLD targets. Check the {self.name} target entry on eLabFTW and make sure you used the correct Resource template.'
+            )
         # Non-required attributes:
         self.description = material_data.get("body") or ""
 
 
+class Proposal:
+    """
+    Proposal(proposal_data) - where proposal_data is a Python dictionary.
 
-if __name__=="__main__":
+    Recovers only the relevant info on a proposal linked to the entrypoint sample.
-    head = Header("MyApiKey-123456789abcdef")
+    Which currently is just its name.
-    print(f"Example header:\n\t{head.header}\n")
+
-    print("Warning: you're not supposed to be running this as the main program.")
+    If the name starts with "Proposal " (space included) that gets omitted from the output.
+    """
+
+    def __init__(self, proposal_data):
+        """
+        Properties/Attributes:
+            * name: str:    Name of the proposal.
+                            If the name starts with "Proposal " (space included) that gets omitted from the output.
+        """
+        if "Proposal " in proposal_data["title"]:
+            self.name = proposal_data["title"].replace("Proposal ", "")
+        else:
+            self.name = proposal_data["title"]
+
+
+if __name__ == "__main__":
+    # head = APIHandler("MyApiKey-123456789abcdef")
+    # print(f"Example header:\n\t{head.header}\n")
+    # print("Warning: you're not supposed to be running this as the main program.")
+    api_key = getpass("Paste API key here [no echo]: ")
+    ELABFTW_API_URL = input("Enter a valid eLabFTW API URL (ends with '/api/v2)': ")
+    handler = APIHandler(api_key, ELABFTW_API_URL)
+    exp58 = handler.get_entry_from_elabid(elabid=58, entryType="experiments")
+    layer58 = Layer(exp58)
+    print(layer58.list_attachments())
+    print(layer58.fetch_textual_uploads())
+    print(layer58.fetch_images())

src/functions.py

@@ -1,62 +0,0 @@
-"""
-Currently unused!
-"""
-import json, requests
-from APIHandler import APIHandler
-
-def get_entry_from_elabid(elabid, entryType="items"):
-    '''
-    Function which returns entrypoint data (as dictionary) from its elabid.
-    '''
-    header = APIHandler(apikey).dump
-    response = requests.get(
-        headers = header,
-        url = f"{ELABFTW_API_URL}/{entryType}/{elabid}",
-        verify=True
-    )
-    if response.status_code // 100 in [2,3]:
-        entry_data = response.json()
-        return entry_data
-    else:
-        raise ConnectionError(f"HTTP request failed with status code: {response.status_code}.")
-
-def get_sample_layers_data(elabid):
-    '''
-    Return the following data from every eLabFTW experiment linked
-    to a certain sample, identified by elabid.
-
-    - Title of the experiment
-    - Category (should check it's "PLD Deposition")
-    - Layer number - if present (PLD depositions)
-    - Deposition time - returns error if not present
-    - Repetition rate - returns error if not present
-    '''
-    # header = {
-    #     "Authorization": apikey,
-    #     "Content-Type": "application/json"
-    # }
-    sample_data = requests.get(
-        headers = header,
-        url = f"https://elabftw.fisica.unina.it/api/v2/items/{elabid}",
-        verify=True
-    ).json()
-    related_experiments = sample_data["related_experiments_links"]
-    result = []
-    for exp in related_experiments:
-        experiment_data = requests.get(
-            headers = header,
-            url = f"https://elabftw.fisica.unina.it/api/v2/experiments/{exp.get("entityid")}",
-            verify=True
-        ).json()
-        extra = experiment_data["metadata_decoded"]["extra_fields"]
-        result.append(
-            {"title": exp.get("title"),
-             "layer_number": extra.get("Layer Progressive Number").get("value"),
-             "category": exp.get("category_title"),
-             "deposition_time": extra.get("Duration").get("value"),
-             "repetition_rate": extra.get("Repetition rate").get("value")}
-        )
-    return result
-
-if __name__=="__main__":
-    print("Warning: you're not supposed to be running this as the main program.")

src/main.py

@@ -1,149 +1,916 @@
-import os, json, requests
+#!/usr/bin/env python3
+import os, json, requests, h5py
+import numpy as np
+from dotenv import load_dotenv
 from getpass import getpass
 from APIHandler import APIHandler
 from classes import *
+from PIL import Image
+# from schema import pld_deposition
 
 
 def call_entrypoint_from_elabid(elabid):
-    '''
+    """
-    Calls an entrypoint sample from eLabFTW using its elabid, then returns an object of the Entrypoint class.
+    Calls a sample from eLabFTW through its elabid, then returns an object of the Entrypoint class.
+    The Entrypoint serves as the starting point in the construction of the dataset.
 
     If the entry is not a sample (category_title not matching exactly "Sample") returns ValueError.
-    '''
+    It's most likely the first error you might encounter (with a valid API key).
-    try: 
+
-        sample_data = APIHandler(apikey).get_entry_from_elabid(elabid, entryType="items")
+    Arg: elabid: int    eLabFTW internal id of the selected resource.
+    """
+    try:
+        sample_data = APIHandler(api_key, ELABFTW_API_URL).get_entry_from_elabid(
+            elabid, entryType="items"
+        )
         if not sample_data.get("category_title") == "Sample":
-            raise ValueError("The resource you selected is not a sample, therefore it can't be used as an entrypoint.")
+            raise ValueError(
+                "The resource you selected is not a sample, therefore it can't be used as an entrypoint."
+            )
         sample_object = Entrypoint(sample_data)
     except ConnectionError as e:
         raise ConnectionError(e)
-    return sample_object # Entrypoint-class object
+    return sample_object  # Entrypoint-class object
+
 
 def call_material_from_elabid(elabid):
-    '''
+    """
     Calls a material from eLabFTW using its elabid, then returns an object of the Material class.
 
-    If the entry is neither a PLD Target or a Substrate batch returns ValueError. Such entries always have a category_title key with its value matching exactly "PLD Target" or "Substrate".
+    If the entry is neither a PLD Target or a Substrate batch returns ValueError.
+    Such entries always have a category_title key with its value matching exactly "PLD Target" or "Substrate".
     Because of an old typo, the value "Subtrate" (second 's' is missing) is also accepted.
-    '''
+
-    try: 
+    arg: elabid: int    eLabFTW internal id of the selected resource.
-        material_data = APIHandler(apikey).get_entry_from_elabid(elabid, entryType="items")
+    """
+    try:
+        material_data = APIHandler(api_key, ELABFTW_API_URL).get_entry_from_elabid(
+            elabid, entryType="items"
+        )
         material_category = material_data.get("category_title")
         # TO-DO: correct this typo on elabftw: Subtrate → Substrate.
         if not material_category in ["PLD Target", "Substrate", "Subtrate"]:
             print(f"Category of the resource: {material_category}.")
-            raise ValueError(f"The referenced resource (elabid = {elabid}) is not a material.")
+            raise ValueError(
+                f"The referenced resource (elabid = {elabid}) is not a material."
+            )
         elif material_category == "PLD Target":
             material_object = Target(material_data)
         else:
             material_object = Substrate(material_data)
     except ConnectionError as e:
         raise ConnectionError(e)
-    return material_object # Material-class object
+    return material_object  # Material-class object
+
 
 def call_layers_from_list(elabid_list):
-    '''
+    """
-    Calls a list of (PLD deposition) experiments from eLabFTW using their elabid - which means the input must be a list of integers instead of a single one - then returns a list of Layer-class objects.
+    Calls a list of (PLD deposition) experiments from eLabFTW through their elabid's, then returns a list of Layer-class objects.
 
-    If one of the entries is not related to a deposition layer (category_title not matching exactly "PLD Deposition") that entry is skipped, with no error raised.
+    If one of the entries is not related to a deposition layer (category_title not matching exactly "PLD Deposition")
-    '''
+    that entry is skipped, with no error raised.
+
+    Arg: elabid_list: list(int):    list of eLabFTW experiments.
+    """
     list_of_layers = []
     for elabid in elabid_list:
         try:
-            layer_data = APIHandler(apikey).get_entry_from_elabid(elabid, entryType="experiments")
+            layer_data = APIHandler(api_key, ELABFTW_API_URL).get_entry_from_elabid(
+                elabid, entryType="experiments"
+            )
             if not layer_data.get("category_title") == "PLD Deposition":
                 continue
             layer_object = Layer(layer_data)
-            list_of_layers.append(layer_object)        
+            list_of_layers.append(layer_object)
         except ConnectionError as e:
-            nums = [ layer.layer_number for layer in list_of_layers ]
+            nums = [layer.layer_number for layer in list_of_layers]
             nums.sort()
             print(f"LIST OF THE LAYERS PROCESSED (unordered):\n" + str(nums))
-            raise ConnectionError(f"An error occurred while fetching the experiment with elabid = {elabid}:\n" +
+            raise ConnectionError(
-                str(e) + f"\nPlease solve the problem before retrying." + "\n\n" +
+                f"An error occurred while fetching the experiment with elabid = {elabid}:\n"
-                f"Last resource attempted to call: {ELABFTW_API_URL}/experiments/{elabid}"
+                + str(e)
+                + f"\nPlease solve the problem before retrying."
+                + "\n\n"
+                + f"Last resource attempted to call at base url: /experiments/{elabid}"
             )
-    return list_of_layers # list of Layer-class objects
+    return list_of_layers  # list of Layer-class objects
+
+
+def call_proposal_from_elabid(elabid):
+    """
+    Calls a proposal item from eLabFTW using their elabid and creates a Proposal-class object.
+
+    Returns the proposal's name (method Proposal.name -> str)
+    If the name starts with "Proposal " (space included) that gets omitted from the output.
+
+    Arg: elabid: int    eLabFTW internal id of the selected resource.
+    """
+    try:
+        proposal_data = APIHandler(api_key, ELABFTW_API_URL).get_entry_from_elabid(
+            elabid, entryType="items"
+        )
+        proposal_category = proposal_data.get("category_title")
+        # TO-DO: correct this typo on elabftw: Subtrate → Substrate.
+        if (
+            "Proposal" not in proposal_category
+        ):  # to avoid that same old problem with trailing spaces
+            print(f"Category of the resource: {proposal_category}.")
+            raise ValueError(
+                f"The referenced resource (elabid = {elabid}) is not a proposal."
+            )
+        else:
+            proposal = Proposal(proposal_data)
+    except ConnectionError as e:
+        raise ConnectionError(e)
+    return proposal.name  # String
+
 
 def chain_entrypoint_to_batch(sample_object):
-    '''
+    """
-    Takes an Entrypoint-class object, looks at its .batch_elabid attribute and returns a Material-class object containing data on the substrate batch associated to the starting sample.
+    Takes an Entrypoint-class object, looks at its .batch_elabid attribute and retrieves data on the substrate batch associated to the starting sample.
+    Returns a Material-class object.
 
+    Arg: sample_object: Entrypoint:     Entrypoint-class object.
     Dependency: call_material_from_elabid.
-    '''
+    """
     material_elabid = sample_object.batch_elabid
     material_object = call_material_from_elabid(material_elabid)
     return material_object
 
+
 def chain_entrypoint_to_layers(sample_object):
-    '''
+    """
-    Takes an Entrypoint-class object, looks at its .linked_experiments_elabid attribute (list) and returns a list of Layer-class objects containing data on the deposition layers associated to the starting sample - using the function call_layers_from_list.
+    Takes an Entrypoint-class object, looks at its .linked_experiments_elabid attribute (list) and
-
+    retrieves data on the deposition layers associated to the starting sample.
-    The list is sorted by progressive layer number (layer_number attribute).
+    Returns a list of Layer-class objects, sorted by progressive layer number (layer_number attribute).
 
+    Arg: sample_object: Entrypoint:     Entrypoint-class object.
     Dependency: call_layers_from_list.
-    '''
+    """
-    linked_experiments_elabid = sample_object.linked_experiments_elabid # list of elabid
+    linked_experiments_elabid = (
+        sample_object.linked_experiments_elabid
+    )  # list of elabid
     layer_object_list = call_layers_from_list(linked_experiments_elabid)
     layer_object_list.sort(key=lambda x: x.layer_number)
     return layer_object_list
 
-def chain_layer_to_target(layer_object):
-    '''
-    Takes a Layer-class object, looks at its .target_elabid attribute and returns a Material-class object containing data on the PLD target used in the deposition of said layer.
 
+def chain_layer_to_target(layer_object):
+    """
+    Takes a Layer-class object, looks at its .target_elabid attribute and retrieves data on the PLD target used in the deposition of said layer.
+    Returns a Material-class object.
+
+    Arg: layer_object: Layer:   Layer-class object.
     Dependency: call_material_from_elabid.
-    '''
+    """
     target_elabid = layer_object.target_elabid
     material_object = call_material_from_elabid(target_elabid)
     return material_object
 
+
+def deduplicate_instruments_from_layers(layers):
+    """
+    For each layer gets the instruments used (laser, depo chamber and RHEED).
+    Creates three sets with all the instruments used regardless of the layer they've been used for.
+    Turns the sets into three strings (joined with commas), then returns a dictionary in the format:
+        {
+            "laser_system": "Laser A, Laser B...",
+            "deposition_chamber": "DC A, DC B...",
+            "rheed_system": RHEED A, RHEED B..."
+        }
+
+    Arg: layers: list(Layer):   List of Layer-class objects.
+    """
+    lasers = []
+    chambers = []
+    rheeds = []
+    elegant_dict = {}
+    for lyr in layers:
+        instruments = lyr.get_instruments(api_key, ELABFTW_API_URL)
+        lasers.append(instruments["laser_system"])
+        chambers.append(instruments["deposition_chamber"])
+        rheeds.append(instruments["rheed_system"])
+        elegant_dict[f"layer_{lyr.layer_number}"] = {
+            "laser_system": instruments["laser_system"],
+            "deposition_chamber": instruments["deposition_chamber"],
+            "rheed_system": instruments["rheed_system"],
+        }
+    ded_lasers = list(set(lasers))
+    ded_chambers = list(set(chambers))
+    ded_rheeds = list(set(rheeds))
+    elegant_dict["multilayer"] = {
+        # Keep key names human readable since they're used in the messages of the following errors
+        "laser_system": ", ".join(ded_lasers),
+        "deposition_chamber": ", ".join(ded_chambers),
+        "rheed_system": ", ".join(ded_rheeds),
+    }  # dictionary's name is a joke
+    return elegant_dict
+
+
+def select_rheed_data(layer):
+    """
+    Takes a Layer-class object and selects the attachments to use to create the RHEED dataset for the NeXus file.
+
+    There are two categories of attachments considered: text-files and pictures.
+    The only accepted formats are ".txt", ".csv" and ".tsv" for the first ones, and ".png" or ".bmp" for the others.
+    The function is extension-sensitive, and only one attachment for each category will be downloaded.
+
+    If there are more than one attachment for each category, the user is prompted to select one of them from a list.
+    If there are no attachments for a category the function will return {} (empty dictionary) for that category.
+
+    Returns the set: (rheed_data_file, rheed_image_file). Both variables are dictionaries in the following format:
+        {
+            "fullname": real_name (with extension),
+            "hashname": long_name (with extension),
+            "related_experiment": elabid
+        }
+    """
+
+    n = layer.layer_number
+    textual_uploads = layer.fetch_textual_uploads()
+    images = layer.fetch_images()
+
+    # Check for length. Three cases:
+    # 1. len is 0, no file of this category → return {}
+    # 2. len is more than 1, user must select
+    # 3. len is 1, God's in his heaven, all's right with the world
+    if len(textual_uploads) == 0:
+        rheed_data_file = {}
+    elif len(textual_uploads) > 1:
+        # prompt user to select from list
+        print(f"Attention: Layer {n} contains multiple TEXTUAL attachments.\n")
+        print("These are used to populate the 'RHEED intensities' dataset.")
+        print("=== USER INTERVENTION REQUIRED ===")
+        for id in textual_uploads:
+            print(f"{id} - {textual_uploads[id]}")
+        ans = None
+        while not type(ans) == int or not ans in range(0, len(textual_uploads)):
+            ans = (
+                input(
+                    "Select one of the attachments from the list (0, 1, ...) [default = 0]: "
+                )
+                or 0
+            )
+            if ans.isdigit():
+                ans = int(ans)
+            continue
+        rheed_data_file = textual_uploads[ans]  # still a dictionary
+    else:
+        rheed_data_file = textual_uploads[
+            next(iter(textual_uploads))
+        ]  # this prism of pork gets the value of the only key in the dictionary
+        # it's proof like no other that my code is human-generated, and that I suck at coding. It's hubris manifest.
+
+    # As above so below
+    if len(images) == 0:
+        rheed_image_file = {}
+    elif len(images) > 1:
+        # prompt user to select from list
+        print(f"Attention: Layer {n} contains multiple PNG/BMP attachments.\n")
+        print("These are used to create the RHEED heatmap.")
+        print("=== USER INTERVENTION REQUIRED ===")
+        for id in images:
+            print(f"{id} - {images[id]}")
+        ans = None
+        while not type(ans) == int or not ans in range(0, len(images)):
+            ans = (
+                input(
+                    "Select one of the attachments from the list (0, 1, ...) [default = 0]: "
+                )
+                or 0
+            )
+            if ans.isdigit():
+                ans = int(ans)
+            continue
+        rheed_image_file = images[ans]  # still a dictionary
+    else:
+        rheed_image_file = images[next(iter(images))]
+
+    return (rheed_data_file, rheed_image_file)
+
+
+def analyse_rheed_data(data):
+    """
+    Takes the content of a tsv file and returns a dictionary with timestamps and intensities.
+    The file should contain a 2D array composed of 4 columns - where the first column is a timestamp and the other three are RHEED intensities - and an unspecified number of rows.
+
+    -----
+    Time    Layer1_Int1     Layer1_Int2     Layer1_Int3
+    -----
+
+    Exceptions:
+        1. Distinct ValueErrors are raised if:
+            * The array is not 2-dimensional;
+            * The total number of columns does not equate at least 1+3 (= 4).
+        2. If the file has more than 4 columns the function prints a warning, then ignores the other columns.
+        3. No exception is made for files where the first column is not the time, or the others are not intensities.
+
+    Time is expressed in seconds, intensities are adimensional on 8 bits (min. 0, max. 255).
+
+    Written with help from DeepSeek.
+    """
+    # Verifying the format of the input file:
+    if data.ndim != 2:
+        raise ValueError(
+            f"Unexpected trace format: expected 2D array, got ndim = {data.ndim}."
+        )
+    n_cols = data.shape[1]  # 0 = rows, 1 = columns
+    if n_cols > 4:
+        print(
+            f"Warning! The input file (for Realtime Window Analysis) has {n_cols - 4} more than needed.\nOnly 4 columns will be considered - with the first representing time and the others representing RHEED intensities."
+        )
+    if n_cols < 4:
+        raise ValueError(
+            f"Insufficient number of columns: expected 4, got n_cols = {n_cols}."
+        )
+    # n_time_points = data.shape[0]
+
+    # Get time (all rows of col 0) as Float64:
+    time = data[:, 0].astype(
+        np.float64, copy=False
+    )  # copy=False suggested by LLM for mem. eff.
+
+    # Get intensities (all rows of cols 1,2,3) as Float32:
+    intensities = data[:, 1:4].astype(np.float32, copy=False)
+
+    return {
+        "time": np.transpose(time),
+        "intensity": np.transpose(intensities),
+    }
+
+
 def make_nexus_schema_dictionary(substrate_object, layers):
+    """
+    Main function, takes all the other functions to reconstruct the full dataset.
+    Takes a Substrate-class object (output of the chain_entrypoint_to_batch() function),
+    and a list of Layer-class objects (output of the chain_entrypoint_to_layers() function).
+
+    Returns dictionary with the same schema as the NeXus standard for PLD fabrications.
+
+    Args:
+        substrate_object: Substrate:    Substrate-class object.
+        layers: list(Layer):            List of Layer-class objects.
+    """
+    instruments = deduplicate_instruments_from_layers(layers)
     pld_fabrication = {
         "sample": {
             "substrate": {
                 "name": substrate_object.name,
-                "chemical_formula" : substrate_object.get_compound_formula(apikey),
+                "chemical_formula": substrate_object.get_compound_formula(
-                "orientation" : substrate_object.orientation,
+                    api_key, ELABFTW_API_URL
-                "miscut_angle" : substrate_object.miscut_angle,
+                ),
-                "miscut_direction" : substrate_object.miscut_direction,
+                "orientation": substrate_object.orientation,
-                "thickness" : substrate_object.thickness,
+                "miscut_angle": {
-                "dimensions" : substrate_object.dimensions,
+                    "value": substrate_object.miscut_angle,
-                "surface_treatment" : substrate_object.surface_treatment,
+                    "units": substrate_object.miscut_angle_unit,
-                "manufacturer" : substrate_object.manufacturer,
+                },
-                "batch_id" : substrate_object.batch_id,
+                "miscut_direction": substrate_object.miscut_direction,
+                "thickness": {
+                    "value": substrate_object.thickness,
+                    "units": substrate_object.thickness_unit,
+                },
+                "dimensions": substrate_object.dimensions,
+                "surface_treatment": substrate_object.surface_treatment,
+                "manufacturer": substrate_object.manufacturer,
+                "batch_id": substrate_object.batch_id,
             },
             "multilayer": {},
         },
+        "instruments_used": instruments["multilayer"],
+        "rheed_data": {},
     }
     multilayer = pld_fabrication["sample"]["multilayer"]
+    rheed_data = pld_fabrication["rheed_data"]
     for layer in layers:
         name = "layer_" + layer.layer_number
         target_object = chain_layer_to_target(layer)
         target_dict = {
             "name": target_object.name,
-            "chemical_formula" : target_object.get_compound_formula(apikey),
+            "chemical_formula": target_object.get_compound_formula(
-            "description" : target_object.description,
+                api_key, ELABFTW_API_URL
-            "shape" : target_object.shape,
+            ),
-            "dimensions" : target_object.dimensions,
+            "description": target_object.description,
-            "thickness" : target_object.thickness,
+            "shape": target_object.shape,
-            "solid_form" : target_object.solid_form,
+            "dimensions": target_object.dimensions,
-            "manufacturer" : target_object.manufacturer,
+            "thickness": {
+                "value": target_object.thickness,
+                "units": target_object.thickness_unit,
+            },
+            "solid_form": target_object.solid_form,
+            "manufacturer": target_object.manufacturer,
+            "batch_id": target_object.name,
             # TO-DO: currently not available:
-            # "batch_id" : target_object.batch_id,
         }
         multilayer[name] = {
-            "target": target_dict
+            "target": target_dict,
+            "start_time": layer.start_time,
+            "operator": layer.operator,
+            "description": layer.description,
+            "number_of_pulses": layer.number_of_pulses,
+            "deposition_time": {
+                "value": layer.deposition_time,
+                "units": layer.deposition_time_unit,
+            },
+            "temperature": {
+                "value": layer.temperature,
+                "units": layer.temperature_unit,
+            },
+            "heating_method": layer.heating_method,
+            "layer_thickness": {
+                "value": layer.layer_thickness,
+                "units": layer.layer_thickness_unit,
+            },
+            "buffer_gas": layer.buffer_gas,
+            "process_pressure": {
+                "value": layer.process_pressure,
+                "units": layer.process_pressure_unit,
+            },
+            "heater_target_distance": {
+                "value": layer.heater_target_distance,
+                "units": layer.heater_target_distance_unit,
+            },
+            "repetition_rate": {
+                "value": layer.repetition_rate,
+                "units": layer.repetition_rate_unit,
+            },
+            "laser_fluence": {
+                "value": layer.laser_fluence,
+                "units": layer.laser_fluence_unit,
+            },
+            "laser_spot_area": {
+                "value": layer.laser_spot_area,
+                "units": layer.laser_spot_area_unit,
+            },
+            "laser_energy": {
+                "value": layer.laser_energy,
+                "units": layer.laser_energy_unit,
+            },
+            "laser_rastering": {
+                "geometry": layer.laser_rastering_geometry,
+                "positions": layer.laser_rastering_positions,
+                "velocities": layer.laser_rastering_velocities,
+            },
+            "pre_annealing": {
+                "ambient_gas": layer.pre_annealing_ambient_gas,
+                "pressure": {
+                    "value": layer.pre_annealing_pressure,
+                    "units": layer.pre_annealing_pressure_unit,
+                },
+                "temperature": {
+                    "value": layer.pre_annealing_temperature,
+                    "units": layer.pre_annealing_temperature_unit,
+                },
+                "duration": {
+                    "value": layer.pre_annealing_duration,
+                    "units": layer.pre_annealing_duration_unit,
+                },
+            },
+            "post_annealing": {
+                "ambient_gas": layer.post_annealing_ambient_gas,
+                "pressure": {
+                    "value": layer.post_annealing_pressure,
+                    "units": layer.post_annealing_pressure_unit,
+                },
+                "temperature": {
+                    "value": layer.post_annealing_temperature,
+                    "units": layer.post_annealing_temperature_unit,
+                },
+                "duration": {
+                    "value": layer.post_annealing_duration,
+                    "units": layer.post_annealing_duration_unit,
+                },
+            },
+            "instruments_used": instruments[name],
         }
-    return json.dumps(pld_fabrication, indent=2)
+        rheed_data[name] = {
+            "layer_number": layer.layer_number,
+            "data": select_rheed_data(
+                layer
+            ),  # tuple: (rheed_data_file, rheed_image_file)
+        }
+    return pld_fabrication
 
-if __name__=="__main__":
+
-    # TO-DO: place the API base URL somewhere else. 
+def build_nexus_file(pld_fabrication, output_path="output/nffa-di_unnamed.h5"):
-    ELABFTW_API_URL = "https://elabftw.fisica.unina.it/api/v2"
+    """
-    apikey = getpass("Paste API key here: ")
+    The function which actually builds the NeXus file for *PLD DEPOSITIONS*.
-    elabid = input("Enter elabid of your starting sample [default= 1111]: ") or 1111
+    Saves the file in the specified directory.
-    data = APIHandler(apikey).get_entry_from_elabid(elabid)
+
+    Args:
+        pld_fabrication:    A dictionary with a specific schema, one only the function
+                            make_nexus_schema_dictionary should make.
+        output_path:        The full path to the output file, including filename complete with extension.
+                            It's a string, which should be produced with os.path.
+                            Default value is: "output/nffa-di_unnamed.h5" - which is NOT NFFA-DI compliant.
+    """
+    # NOTE: look at the mail attachment from Emiliano...
+    with h5py.File(output_path, "w") as f:
+        nx_pld_entry = f.create_group("pld_fabrication")
+        nx_pld_entry.attrs["NX_class"] = "NXentry"
+
+        # Sample section
+        nx_sample = nx_pld_entry.create_group("sample")
+        nx_sample.attrs["NX_class"] = "NXsample"
+        sample_dict = pld_fabrication["sample"]
+
+        # Substrate sub-section
+        nx_substrate = nx_sample.create_group("substrate")
+        nx_substrate.attrs["NX_class"] = "NXsubentry"
+        substrate_dict = sample_dict["substrate"]
+        try:
+            # Substrate fields (datasets)
+            nx_substrate.create_dataset("name", data=substrate_dict["name"])
+            nx_substrate.create_dataset(
+                "chemical_formula", data=substrate_dict["chemical_formula"]
+            )
+            nx_substrate.create_dataset(
+                "orientation", data=substrate_dict["orientation"]
+            )
+            nx_substrate.create_dataset(
+                "miscut_angle", data=substrate_dict["miscut_angle"]["value"]
+            )  # float
+            nx_substrate["miscut_angle"].attrs["units"] = substrate_dict[
+                "miscut_angle"
+            ]["units"]
+            nx_substrate.create_dataset(
+                "miscut_direction", data=substrate_dict["miscut_direction"]
+            )
+            nx_substrate.create_dataset(
+                "thickness", data=substrate_dict["thickness"]["value"]
+            )  # float/int
+            nx_substrate["thickness"].attrs["units"] = substrate_dict["thickness"][
+                "units"
+            ]
+            nx_substrate.create_dataset("dimensions", data=substrate_dict["dimensions"])
+            nx_substrate.create_dataset(
+                "surface_treatment", data=substrate_dict["surface_treatment"]
+            )
+            nx_substrate.create_dataset(
+                "manufacturer", data=substrate_dict["manufacturer"]
+            )
+            nx_substrate.create_dataset("batch_id", data=substrate_dict["batch_id"])
+        except TypeError as te:
+            # sooner or later I'll handle this too - not today tho
+            raise TypeError(te)
+
+        # Multilayer sub-section
+        nx_multilayer = nx_sample.create_group("multilayer")
+        nx_multilayer.attrs["NX_class"] = "NXsubentry"
+        multilayer_dict = sample_dict["multilayer"]
+        # Repeat FOR EACH LAYER:
+        for layer in multilayer_dict:
+            nx_layer = nx_multilayer.create_group(layer)
+            nx_layer.attrs["NX_class"] = "NXsubentry"
+            layer_dict = multilayer_dict[layer]
+            # Sub-groups of a layer
+            ## Target
+            nx_target = nx_layer.create_group("target")
+            nx_target.attrs["NX_class"] = "NXsample"
+            target_dict = layer_dict["target"]
+            ## Rastering and Annealing
+            nx_laser_rastering = nx_layer.create_group("laser_rastering")
+            nx_laser_rastering.attrs["NX_class"] = "NXprocess"
+            rastering_dict = layer_dict["laser_rastering"]
+            nx_pre_annealing = nx_layer.create_group("pre_annealing")
+            nx_pre_annealing.attrs["NX_class"] = "NXprocess"
+            pre_ann_dict = layer_dict["pre_annealing"]
+            nx_post_annealing = nx_layer.create_group("post_annealing")
+            nx_post_annealing.attrs["NX_class"] = "NXprocess"
+            post_ann_dict = layer_dict["post_annealing"]
+            nx_layer_instruments = nx_layer.create_group("instruments_used")
+            nx_layer_instruments.attrs["NX_class"] = "NXinstrument"
+            layer_instruments_dict = layer_dict["instruments_used"]
+
+            ## Target metadata
+            try:
+                nx_target.create_dataset("name", data=target_dict["name"])
+                nx_target.create_dataset(
+                    "chemical_formula", data=target_dict["chemical_formula"]
+                )
+                nx_target.create_dataset("description", data=target_dict["description"])
+                nx_target.create_dataset("shape", data=target_dict["shape"])
+                nx_target.create_dataset("dimensions", data=target_dict["dimensions"])
+                nx_target.create_dataset(
+                    "thickness", data=target_dict["thickness"]["value"]
+                )  # float/int
+                nx_target["thickness"].attrs["units"] = target_dict["thickness"][
+                    "units"
+                ]
+                nx_target.create_dataset("solid_form", data=target_dict["solid_form"])
+                nx_target.create_dataset(
+                    "manufacturer", data=target_dict["manufacturer"]
+                )
+                nx_target.create_dataset("batch_id", data=target_dict["batch_id"])
+            except TypeError as te:
+                raise TypeError(te)
+            ## Other layer-specific metadata
+            try:
+                nx_layer.create_dataset("start_time", data=layer_dict["start_time"])
+                nx_layer.create_dataset("operator", data=layer_dict["operator"])
+                nx_layer.create_dataset(
+                    "number_of_pulses", data=layer_dict["number_of_pulses"]
+                )
+                nx_layer.create_dataset(
+                    "deposition_time", data=layer_dict["deposition_time"]["value"]
+                )
+                nx_layer["deposition_time"].attrs["units"] = layer_dict[
+                    "deposition_time"
+                ]["units"]
+                nx_layer.create_dataset(
+                    "repetition_rate", data=layer_dict["repetition_rate"]["value"]
+                )
+                nx_layer["repetition_rate"].attrs["units"] = layer_dict[
+                    "repetition_rate"
+                ]["units"]
+                nx_layer.create_dataset(
+                    "temperature", data=layer_dict["temperature"]["value"]
+                )
+                nx_layer["temperature"].attrs["units"] = layer_dict["temperature"][
+                    "units"
+                ]
+                nx_layer.create_dataset(
+                    "heating_method", data=layer_dict["heating_method"]
+                )
+                nx_layer.create_dataset(
+                    "layer_thickness", data=layer_dict["layer_thickness"]["value"]
+                )
+                nx_layer["layer_thickness"].attrs["units"] = layer_dict[
+                    "layer_thickness"
+                ]["units"]
+                nx_layer.create_dataset("buffer_gas", data=layer_dict["buffer_gas"])
+                nx_layer.create_dataset(
+                    "process_pressure", data=layer_dict["process_pressure"]["value"]
+                )
+                nx_layer["process_pressure"].attrs["units"] = layer_dict[
+                    "process_pressure"
+                ]["units"]
+                nx_layer.create_dataset(
+                    "heater_target_distance",
+                    data=layer_dict["heater_target_distance"]["value"],
+                )
+                nx_layer["heater_target_distance"].attrs["units"] = layer_dict[
+                    "heater_target_distance"
+                ]["units"]
+                nx_layer.create_dataset(
+                    "laser_fluence", data=layer_dict["laser_fluence"]["value"]
+                )
+                nx_layer["laser_fluence"].attrs["units"] = layer_dict["laser_fluence"][
+                    "units"
+                ]
+                nx_layer.create_dataset(
+                    "laser_spot_area", data=layer_dict["laser_spot_area"]["value"]
+                )
+                nx_layer["laser_spot_area"].attrs["units"] = layer_dict[
+                    "laser_spot_area"
+                ]["units"]
+                nx_layer.create_dataset(
+                    "laser_energy", data=layer_dict["laser_energy"]["value"]
+                )
+                nx_layer["laser_energy"].attrs["units"] = layer_dict["laser_energy"][
+                    "units"
+                ]
+            except TypeError as te:
+                raise TypeError(te)
+            ## Rastering metadata
+            try:
+                nx_laser_rastering.create_dataset(
+                    "geometry", data=rastering_dict["geometry"]
+                )
+                nx_laser_rastering.create_dataset(
+                    "positions", data=rastering_dict["positions"]
+                )
+                nx_laser_rastering.create_dataset(
+                    "velocities", data=rastering_dict["velocities"]
+                )
+            except TypeError as te:
+                raise TypeError(te)
+            ## Annealing metadata
+            try:
+                nx_pre_annealing.create_dataset(
+                    "ambient_gas", data=pre_ann_dict["ambient_gas"]
+                )
+                nx_pre_annealing.create_dataset(
+                    "pressure", data=pre_ann_dict["pressure"]["value"]
+                )
+                nx_pre_annealing["pressure"].attrs["units"] = pre_ann_dict["pressure"][
+                    "units"
+                ]
+                nx_pre_annealing.create_dataset(
+                    "temperature", data=pre_ann_dict["temperature"]["value"]
+                )
+                nx_pre_annealing["temperature"].attrs["units"] = pre_ann_dict[
+                    "temperature"
+                ]["units"]
+                nx_pre_annealing.create_dataset(
+                    "duration", data=pre_ann_dict["duration"]["value"]
+                )
+                nx_pre_annealing["duration"].attrs["units"] = pre_ann_dict["duration"][
+                    "units"
+                ]
+            except TypeError as te:
+                raise TypeError(te)
+            try:
+                nx_post_annealing.create_dataset(
+                    "ambient_gas", data=post_ann_dict["ambient_gas"]
+                )
+                nx_post_annealing.create_dataset(
+                    "pressure", data=post_ann_dict["pressure"]["value"]
+                )
+                nx_post_annealing["pressure"].attrs["units"] = post_ann_dict[
+                    "pressure"
+                ]["units"]
+                nx_post_annealing.create_dataset(
+                    "temperature", data=post_ann_dict["temperature"]["value"]
+                )
+                nx_post_annealing["temperature"].attrs["units"] = post_ann_dict[
+                    "temperature"
+                ]["units"]
+                nx_post_annealing.create_dataset(
+                    "duration", data=post_ann_dict["duration"]["value"]
+                )
+                nx_post_annealing["duration"].attrs["units"] = post_ann_dict[
+                    "duration"
+                ]["units"]
+            except TypeError as te:
+                raise TypeError(te)
+            try:
+                nx_layer_instruments.create_dataset(
+                    "laser_system", data=layer_instruments_dict["laser_system"]
+                )
+                nx_layer_instruments.create_dataset(
+                    "deposition_chamber",
+                    data=layer_instruments_dict["deposition_chamber"],
+                )
+                nx_layer_instruments.create_dataset(
+                    "rheed_system", data=layer_instruments_dict["rheed_system"]
+                )
+            except TypeError as te:
+                raise TypeError(te)
+
+        # Instruments used section
+        nx_instruments = nx_pld_entry.create_group("instruments_used")
+        nx_instruments.attrs["NX_class"] = "NXinstrument"
+        instruments_dict = pld_fabrication["instruments_used"]
+        try:
+            nx_instruments.create_dataset(
+                "laser_system", data=instruments_dict["laser_system"]
+            )
+            nx_instruments.create_dataset(
+                "deposition_chamber", data=instruments_dict["deposition_chamber"]
+            )
+            nx_instruments.create_dataset(
+                "rheed_system", data=instruments_dict["rheed_system"]
+            )
+        except TypeError as te:
+            raise TypeError(te)
+
+        # RHEED data section
+        nx_rheed = nx_pld_entry.create_group("rheed_data")
+        nx_rheed.attrs["NX_class"] = "NXdata"
+
+        rheed_data = pld_fabrication["rheed_data"]
+        for layer in rheed_data:
+            nx_rheed_layer = nx_rheed.create_group(layer)
+
+            layer_dict = rheed_data[layer]
+            n = layer_dict["layer_number"]
+            rheed_data_file = layer_dict["data"][0]  # first in the tuple
+            rheed_image_file = layer_dict["data"][1]  # second in the tuple
+            handler = APIHandler(api_key, ELABFTW_API_URL)
+
+            # TO-DO: maybe make a dedicated function???
+            data_path = None
+            image_path = None
+
+            if rheed_data_file != {}:
+                try:
+                    elabid = rheed_data_file["related_experiment"]
+                    upload_id = rheed_data_file["id"]
+                except KeyError as ke:
+                    raise KeyError(
+                        f"Missing key in your file: {rheed_data_file.get('filename') or '<missing name>'}: {ke}"
+                    )
+                data_path = handler.download_attachment_to_disk(
+                    elabid=elabid, upload_id=upload_id
+                )
+
+            if rheed_image_file != {}:
+                try:
+                    upload_id = rheed_image_file["id"]
+                    elabid = rheed_image_file["related_experiment"]
+                except KeyError as ke:
+                    raise KeyError(
+                        f"Missing key in your file: {rheed_data_file.get('filename') or '<missing name>'}: {ke}"
+                    )
+                image_path = handler.download_attachment_to_disk(
+                    elabid=elabid, upload_id=upload_id
+                )
+
+            if data_path and os.path.isfile(data_path):
+                with open(data_path, "r") as o:
+                    osc = np.loadtxt(o, delimiter="\t")
+                try:
+                    rheed_osc = (
+                        analyse_rheed_data(data=osc) or None
+                    )  # analyze rheed data first, build the file later
+                except ValueError as ve:
+                    raise ValueError(
+                        f"Error with function analyse_rheed_data. {ve}\nPlease make sure the Realtime Window Analysis file is exactly 4 columns wide - where the first column represents time and the others are RHEED intensities."
+                    )
+                if rheed_osc is not None:
+                    # Time axis (needed?)
+                    t_ds = nx_rheed_layer.create_dataset("time", data=rheed_osc["time"])
+                    t_ds.attrs["units"] = "s"
+                    t_ds.attrs["long_name"] = "Time"
+
+                    # Intensity shape (n_layers, n_timepoints, 3)
+                    i_ds = nx_rheed_layer.create_dataset(
+                        "intensity", data=rheed_osc["intensity"]
+                    )
+                    i_ds.attrs["units"] = "a.u."
+                    i_ds.attrs["long_name"] = "RHEED Intensity"
+
+                    # NXdata attributes — NeXus 3.x notation
+                    nx_rheed_layer.attrs["signal"] = "intensity"
+                    nx_rheed_layer.attrs["axes"] = [
+                        ".",
+                        "time",
+                        ".",
+                    ]  # only time axis (1) is named
+                    nx_rheed_layer.attrs["time_indices"] = np.array([1], dtype=np.int32)
+
+            if image_path and os.path.isfile(image_path):
+                img = Image.open(image_path).convert("L")
+                heatmap_matrix = np.array(img, dtype=np.uint8)  # or None
+                # heatmap_matrix = heatmap_matrix.astype(np.float32) / 255.0  # toggle to normalize matrix values
+
+            if heatmap_matrix is not None:
+                heatmap = nx_rheed_layer.create_dataset(
+                    "diffraction_image", data=heatmap_matrix
+                )
+                heatmap.attrs["long_name"] = "Diffraction Image"
+                heatmap.attrs["units"] = "a.u."
+                heatmap.attrs["interpretation"] = "spectrum"
+    return
+    # TO-DO: ↓↓↓ comment cleanup ↓↓↓
+    #
+    # here's what we gon do: (to be read with the voice of Mike from Breaking Bad)
+    # 1. rheed_osc and heatmap_matrix are NOT given in input to the function so no need for checking that
+    # 2. loop through the layers, each with its elabid and metadata
+    # 2a. read said metadata for each layer, print list of txt and png files (dedicated Layer class methods)
+    # 2b. prompt the user for file choice (1 text file per layer - in tsv format, 1 picture file - either png [default] or bmp)
+    # 2c. download the chosen file
+    # 2d. with chosen file do analysis as before
+    # 3. the schema should be:
+    #   * /rheed_data
+    #       * /layer_n
+    #           * time (rheed_osc)
+    #           * intensity (rheed_osc)
+    #           * diffraction_image (heatmap_matrix)
+    # first problem is probably finding out how to recover the following meta from the original Layer object:
+    #   * Layer.elabid - integer
+    #   * Layer.fetch_textual_uploads() - dictionary
+    #   * Layer.fetch_images() - dictionary
+
+
+if __name__ == "__main__":
+    load_dotenv()
+    api_key = os.getenv("api_key") or getpass("Paste API key here: ", echo_char="*")
+    elabid = (
+        os.getenv("elabid")
+        or input("Enter elabid of your starting sample [default = 1111]: ")
+        or 1111
+    )
+    ELABFTW_API_URL = os.getenv("ELABFTW_API_URL") or input(
+        "Enter a valid eLabFTW API URL (ends with '/api/v2)': "
+    )
+    handler = APIHandler(api_key, ELABFTW_API_URL)
+    data = handler.get_entry_from_elabid(elabid)
     sample = Entrypoint(data)
-    substrate_object = chain_entrypoint_to_batch(sample) # Substrate-class object
+    sample_name = sample.name.strip().replace(
-    layers = chain_entrypoint_to_layers(sample) # list of Layer-class objects
+        " ", "-"
-    print(make_nexus_schema_dictionary(substrate_object, layers)) # debug
+    )  # returns error if no "title" or title is not str
+    operative_unit = os.getenv("operative_unit") or None
+    if operative_unit:
+        operative_unit = operative_unit.strip().replace(" ", "-")
+    if sample.proposal:
+        sample_proposal = call_proposal_from_elabid(sample.proposal)
+    else:
+        sample_proposal = None
+    substrate_object = chain_entrypoint_to_batch(sample)  # Substrate-class object
+    layers = chain_entrypoint_to_layers(sample)  # list of Layer-class objects
+    n_layers = len(layers)  # total number of layers on the sample
+    # print(make_nexus_schema_dictionary(substrate_object, layers)) # debug
+    fn_base = (
+        "nffa-di_"
+        + (f"{sample_proposal}_" if sample_proposal else "")
+        + (f"{operative_unit}_" if operative_unit else "")
+        + "PLD_"
+        + sample_name[:9]
+    )
+
+    result = make_nexus_schema_dictionary(substrate_object, layers)
+    with open(f"output/{fn_base}.json", "w") as f:
+        json.dump(result, f, indent=3)
+
+    build_nexus_file(result, output_path=f"output/{fn_base}.nxs")

src/schema/pld_deposition.py

@@ -0,0 +1,3 @@
+class Prova:
+    def __init__(self):
+        self.hello = "Hello world"