From 686f869d10d704e35edd59aee69feb24b7c25d412b1f837cc2ff6b4f1397c95d Mon Sep 17 00:00:00 2001 From: emanuele Date: Wed, 13 May 2026 12:12:32 +0200 Subject: [PATCH] documents all the functions/classes/methods (by hand) no AI used, it took more than I'm willing to admit but it's done --- src/APIHandler.py | 38 ++++++++-------- src/classes.py | 110 ++++++++++++++++++++++++++++++++++++++++++++++ src/main.py | 74 ++++++++++++++++++++++--------- 3 files changed, 182 insertions(+), 40 deletions(-) diff --git a/src/APIHandler.py b/src/APIHandler.py index 534c376..6a25525 100644 --- a/src/APIHandler.py +++ b/src/APIHandler.py @@ -11,19 +11,19 @@ class APIHandler: (since the API doesn't support downloading attachments AFAIK). Args: - api_key: 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: Complete URL of the eLabFTW instance's root for the API endpoints. - In full caps because it won't (shouldn't) be changed much. + 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, api_key="", ELABFTW_API_URL="https://elabftw.fisica.unina.it/api/v2" ): - """Init method, apikey suggested but not required (empty by default).""" + """Init method, api_key suggested but not required (empty by default).""" self.api_key = api_key self.auth = {"Authorization": api_key} self.content = {"Content-Type": "application/json"} @@ -34,9 +34,9 @@ class APIHandler: """ Returns raw data (as dictionary) from its elabid and entry type. - args: - elabid: elabftw internal id of the selected resource. - entryType: Resource type. Anything other than "experiments" or "items" WILL raise an error. + 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( @@ -91,9 +91,9 @@ class APIHandler: * The value is the attachment's binary data. Args: - elabid: eLabFTW internal ID of the selected resource. - upload_id: eLabFTW internal ID of the selected upload. - entryType: Resource type. Anything other than "experiments" or "items" WILL raise an error. + 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( @@ -136,12 +136,12 @@ class APIHandler: Returns full path of the output file. Args: - elabid: eLabFTW internal ID of the selected resource. - upload_id: eLabFTW internal ID of the selected upload. - entryType: Resource type. Anything other than "experiments" or "items" WILL raise an error. - dump_dir: Directory to which to save the attachments. Default is "output/attachments". - persistent: [Unused] Decides if the files will stay on disk after all operations are completed. - If set to False, deletes the file upon exiting. + 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"]: diff --git a/src/classes.py b/src/classes.py index c3d41f9..ef5f83c 100644 --- a/src/classes.py +++ b/src/classes.py @@ -15,6 +15,10 @@ class Layer: """ def __init__(self, layer_data): + """ + Properties/Attributes: + Too many to list. + """ try: self.elabid = layer_data["id"] self.operator = layer_data["fullname"] @@ -131,6 +135,20 @@ class Layer: self.description = layer_data.get("body") or None def get_instruments(self, api_key): + """ + 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 + } + + Arg: 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. + """ raw_lasersys_data = APIHandler(api_key).get_entry_from_elabid( self.laser_system_elabid, entryType="items" ) @@ -220,6 +238,15 @@ class Entrypoint: """ 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.extra = sample_data["metadata_decoded"]["extra_fields"] self.linked_items = sample_data["items_links"] # dict @@ -239,6 +266,7 @@ class Entrypoint: self.name = ( sample_data.get("title") or None ) # error prevention is more important than preventing empty fields here + # although I don't think it's even possible to fuck up this bad... class Material: @@ -254,6 +282,14 @@ class Material: """ 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.extra = material_data["metadata_decoded"]["extra_fields"] @@ -275,6 +311,20 @@ class Material: ) def get_compound_data(self, apikey): + """ + 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 + } + + Arg: 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. + """ raw_compound_data = APIHandler(apikey).get_entry_from_elabid( self.compound_elabid, entryType="items" ) @@ -295,7 +345,32 @@ class Material: 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"] @@ -315,7 +390,28 @@ class Substrate(Material): 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"] @@ -332,7 +428,21 @@ class Target(Material): class Proposal: + """ + Proposal(proposal_data) - where proposal_data is a Python dictionary. + + Recovers only the relevant info on a proposal linked to the entrypoint sample. + Which currently is just its name. + + 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: diff --git a/src/main.py b/src/main.py index 9e2bf5f..61e5d63 100755 --- a/src/main.py +++ b/src/main.py @@ -11,9 +11,13 @@ from PIL import Image 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). + + Arg: elabid: int eLabFTW internal id of the selected resource. """ try: sample_data = APIHandler(api_key).get_entry_from_elabid( @@ -33,8 +37,11 @@ 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. + + arg: elabid: int eLabFTW internal id of the selected resource. """ try: material_data = APIHandler(api_key).get_entry_from_elabid( @@ -58,9 +65,12 @@ def call_material_from_elabid(elabid): 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: @@ -87,6 +97,14 @@ def call_layers_from_list(elabid_list): 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).get_entry_from_elabid( elabid, entryType="items" @@ -109,8 +127,10 @@ def call_proposal_from_elabid(elabid): 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 @@ -120,10 +140,11 @@ def chain_entrypoint_to_batch(sample_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. - - The list is sorted by progressive layer number (layer_number attribute). + 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. + 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 = ( @@ -136,8 +157,10 @@ def chain_entrypoint_to_layers(sample_object): 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. + 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 @@ -147,9 +170,16 @@ def chain_layer_to_target(layer_object): def deduplicate_instruments_from_layers(layers): """ - Takes a list of Layer-class objects and for each layer gets the instruments used (laser, depo chamber and RHEED), returns dictionary with one item per category. This means that if more layers share the same instruments it returns a dictionary with just their names as strings (no lists or sub-dictionaries). + 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..." + } - If different layers have different instruments (e.g. laser systems) the user is prompted to only select one. + Arg: layers: list(Layer): List of Layer-class objects. """ lasers = [] chambers = [] @@ -259,11 +289,6 @@ def select_rheed_data(layer): return (rheed_data_file, rheed_image_file) -def download_rheed_data(): - - return - - def analyse_rheed_data(data): """ Takes the content of a tsv file and returns a dictionary with timestamps and intensities. @@ -273,13 +298,15 @@ def analyse_rheed_data(data): Time Layer1_Int1 Layer1_Int2 Layer1_Int3 ----- - Distinct ValueErrors are raised if: - * The array is not 2-dimensional; - * The total number of columns does not equate exactly 1+3 (= 4). + 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). - # TO-DO: complete this description... Written with help from DeepSeek. """ # Verifying the format of the input file: @@ -319,6 +346,10 @@ def make_nexus_schema_dictionary(substrate_object, layers): 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 = { @@ -462,7 +493,8 @@ def build_nexus_file(pld_fabrication, output_path="output/nffa-di_unnamed.h5"): Saves the file in the specified directory. Args: - pld_fabrication: + 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.