From a4c1c0af8669a07fa8a08c4c164af45435ace3de Mon Sep 17 00:00:00 2001 From: rcsm17 Date: Thu, 25 Aug 2022 11:33:41 +0200 Subject: [PATCH] added docs --- dev_tool/create_hhnb_dev_client.py | 40 ++++++++++++++++++++++++++++++ dev_tool/create_metadata_file.py | 5 ++++ dev_tool/storage_cleaner.py | 6 +++++ efelg/tools/manage_json.py | 22 +++++++++++++++- 4 files changed, 72 insertions(+), 1 deletion(-) diff --git a/dev_tool/create_hhnb_dev_client.py b/dev_tool/create_hhnb_dev_client.py index 6d069708..071ac046 100755 --- a/dev_tool/create_hhnb_dev_client.py +++ b/dev_tool/create_hhnb_dev_client.py @@ -1,5 +1,10 @@ #! /usr/bin/python3 +""" +This python script is used to create a local OIDC client for the +Hodgkin-Huxley Neuron Builder web application in order to perform +the authentication process with the EBRAINS platform. +""" import requests import getpass @@ -9,6 +14,24 @@ def get_dev_token(username, password): + """ + Returns the developer token used to create the OIDC client. + This is got by making a request to the EBRAINS platform providing + the user's username and password passed as argoument of this function. + + Parameters + ---------- + username : str + username + password : str + password + + Returns + ------- + str + the user developer token + """ + r = requests.post( url='https://iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/token', auth=('developer', ''), @@ -31,6 +54,23 @@ def get_dev_token(username, password): def create_hhnb_dev_client(username, dev_token): + """ + Create an EBRAINS OIDC client to perform the authentication process + for the Hodgkin-Huxley Neuron Builder web application. The client + parameters are set by default for a local environment. + + Parameters + ---------- + username : str + username + dev_token : str + the user developer token + + Returns + ------- + dict + the client in a json format + """ client = { 'clientId': 'hhnb-%s-dev-local-client' % username, diff --git a/dev_tool/create_metadata_file.py b/dev_tool/create_metadata_file.py index 2b32657c..3eff6bbb 100644 --- a/dev_tool/create_metadata_file.py +++ b/dev_tool/create_metadata_file.py @@ -1,3 +1,8 @@ +""" +This script is used to create a a metadata file for a etrace. +""" + + import os import json diff --git a/dev_tool/storage_cleaner.py b/dev_tool/storage_cleaner.py index 9b5c13d0..525b3d01 100755 --- a/dev_tool/storage_cleaner.py +++ b/dev_tool/storage_cleaner.py @@ -1,5 +1,11 @@ #! /usr/bin/python3 +""" +This script is used to automatically clean the storage of the +Hodgkin-Huxley Neuron Builder backend. +""" + + import argparse import os import datetime diff --git a/efelg/tools/manage_json.py b/efelg/tools/manage_json.py index 695cda21..914f7389 100755 --- a/efelg/tools/manage_json.py +++ b/efelg/tools/manage_json.py @@ -12,6 +12,9 @@ # generate hash md5 code for the filename passed as parameter def md5(filename): + """ + Returns the md5 hash for the file. + """ hash_md5 = hashlib.md5() with open(filename, "rb") as f: @@ -21,7 +24,9 @@ def md5(filename): def get_traces_abf(filename): - + """ + Returns a tuple of features extracted from the ".abf" trace and its metadata. + """ data = neo.io.AxonIO(filename) metadata = get_metadata(filename) @@ -73,6 +78,9 @@ def get_traces_abf(filename): # read metadata file into a json dictionary def get_metadata(filename): + """ + Returns the metadata dictionaire by reading the metadata file. + """ filepath, name = os.path.split(filename) name_no_ext, extension = os.path.splitext(name) metadata_file = os.path.join(filepath, name_no_ext + '_metadata.json') @@ -85,6 +93,9 @@ def get_metadata(filename): # perform units conversions def perform_conversions_json(data): + """ + Convert some features values. + """ if ("stimulus_unit" in data) and (not data["stimulus_unit"].lower() in ["na", "unknown"]): a_pow = 1 stimlus_unit = data["stimulus_unit"].lower() @@ -131,6 +142,9 @@ def perform_conversions_json(data): def extract_data(filepath, metadata_dict=None): + """ + Returns the trace data in a json format. + """ if filepath.endswith(".abf"): sampling_rate, tonoff, traces, voltage_unit, stimulus_unit, voltage_correction, voltage_correction_unit = get_traces_abf(filepath) data = { @@ -188,6 +202,9 @@ def extract_data(filepath, metadata_dict=None): def create_file_name(data): + """ + Generate a file name for the relative cell. + """ filename_keys = [ "animal_species", "brain_structure", "cell_soma_location", "cell_type", "etype", "cell_id", "filename" ] @@ -195,6 +212,9 @@ def create_file_name(data): def update_file_name(data, metadata_dict): + """ + Update the file name for the relative cell. + """ metadata_keys = metadata_dict.keys() data["cell_id"] = metadata_dict["cell_name"] if "cell_name" in metadata_keys else metadata_dict["cell_id"] data["contributors_affiliations"] = metadata_dict["contributors"] if "contributors" in metadata_keys else metadata_dict["contributors_affiliations"]