HABSlib: Python Library for EEG Analysis and Biomarker Evaluation

   1######################################################
   2# INTRO
   3
   4r"""
   5# HABSlib: Python Library for EEG Analysis and Biomarker Evaluation
   6
   7HABSlib is a versatile Python library designed to facilitate interaction with the HABS BrainOS API for comprehensive EEG data analysis and biomarker evaluation. 
   8Developed to support neuroscientific research and clinical applications, HABSlib simplifies the process of fetching, processing, and analyzing EEG data through a user-friendly interface.
   9
  10Key Features:
  11- **API Integration**: Connects with the BrainOS HABS API, allowing users to access EEG data and related services effortlessly.
  12- **Data Management**: Provides a robust interface for managing EEG datasets, including storage on the HABS servers.
  13- **Biomarker Evaluation**: Enables the analysis of EEG biomarkers, essential for diagnosing and monitoring neurological conditions.
  14- **Customizable Pipelines**: Users can create custom analysis pipelines tailored to specific research needs, ensuring flexibility and adaptability in various use cases.
  15
  16## Sessions
  17
  18The communications between the user and HABS BrainOS is based on a RESTful API (see doc) and structured into sessions.    
  19
  20A *Session* with the HABS BrainOS iinitiates with an handshake during which encryption keys are exchanged for the security of any following communication between the user and the server.
  21
  22### Simple sessions
  23
  24There are two general types of session: *real-time* and *off-line*.
  25
  26In setting a either a real-time or off-line session, the user provides the session metadata, such as their user_id, session_date, session type (all required), and additional notes depending on the nature of recordings.
  27
  28Then, in a real-time session, the user specifies the type of EEG DEVICE ('board') used, the duration of the EEG recording, and the frequency of server update. 
  29
  30In an off-line session, the user specifies a session id (referring to data already exisiting, either acquired live at some point in time, or from an uploaded file).    
  31The HABSlib can read EDF files (EDF file type only, for now, but it's growing) and sends it to the server.
  32
  33In these simple types of session, after the real-time or offline uploading, the data can be selected via the session_id for further processing.
  34
  35### Piped sessions
  36
  37There is another type of session, called *piped* session. This type of session is meant to help you organize the flow of analysis and make it reproducible.     
  38Usually, an analysis implies several steps over the raw data. BrainOS allows you to perform a growing number of predefined and parametrizable functions over the data, to filter, remove artifacts, and extract features. 
  39And you can do it without taking the output of one function and passing it to another. You can pipe (|) the output of one function into the next.
  40
  41This session type also is available as *real-time* and *off-line*. In the *real-time* version the EEG data is processed as per pipe by the server as soon as it is received, and the results are sent back to the user as soon as they are processed.    
  42"""
  43
  44import sys
  45import os
  46import base64
  47import requests
  48import json
  49import jsonschema
  50from jsonschema import validate
  51from jsonschema import exceptions
  52# from bson import json_util
  53
  54import numpy as np
  55
  56import time
  57from datetime import datetime
  58import uuid
  59import asyncio
  60import webbrowser
  61
  62from . import BASE_URL, VERSION
  63from . import BoardManager
  64
  65from cryptography.hazmat.primitives import hashes, serialization
  66from cryptography.hazmat.backends import default_backend
  67from . import store_public_key, load_public_key, generate_aes_key, encrypt_aes_key_with_rsa, encrypt_message, decrypt_message
  68
  69from pyedflib import highlevel
  70
  71from importlib.metadata import version
  72
  73
  74######################################################
  75# validate the metadata against a specified schema
  76def validate_metadata(metadata, schema_name, schemafile='metadata.json'):
  77    """
  78    Validate metadata against a given JSON schema.
  79
  80    Args:    
  81        **metadata** (*dict*): The metadata to be validated.    
  82        **schema_name** (*str*): The name of the schema to validate against. HABSlib currently supports the validation of Session metadata and User data.    
  83        **schemafile** (*str*, optional): The path to the JSON file containing the schemas. Defaults to 'metadata.json'.    
  84
  85    Returns:    
  86        *bool*: True if validation is successful, False otherwise.
  87
  88    Raises:    
  89        **FileNotFoundError**: If the schema file does not exist.     
  90        **json.JSONDecodeError**: If there is an error decoding the JSON schema file.     
  91        **exceptions.ValidationError**: If the metadata does not conform to the schema.     
  92        **Exception**: For any other errors that occur during validation.     
  93
  94    Example:
  95    ```
  96    metadata = {"name": "example", "type": "data"}
  97    schema_name = "example_schema"
  98    is_valid = validate_metadata(metadata, schema_name)
  99    if is_valid:
 100        print("Metadata is valid.")
 101    else:
 102        print("Metadata is invalid.")
 103    ```
 104    """
 105    print(metadata)
 106    try:
 107        with open(os.path.join(os.path.dirname(__file__), schemafile), 'r') as file:
 108            content = file.read()
 109            schemas = json.loads(content)
 110        schema = schemas[schema_name]
 111        validate(instance=metadata, schema=schema) #, format_checker=FormatChecker())
 112        print("Metadata validation successful!")
 113        return True
 114
 115    except json.JSONDecodeError as e:
 116        print("Failed to decode JSON:", e)
 117        return False
 118
 119    except exceptions.ValidationError as e:
 120        print("Validation error:", e)
 121        return False
 122
 123    except FileNotFoundError:
 124        print(f"No such file: {schemafile}")
 125        return False
 126
 127    except Exception as e:
 128        print("A general error occurred:", e)
 129        return False
 130
 131
 132def convert_datetime_in_dict(data):
 133    """
 134    Recursively converts all datetime objects in a dictionary to strings in ISO format.
 135
 136    Args:     
 137        **data** (*dict*): The dictionary containing the data.
 138
 139    Returns:     
 140        *dict*: The dictionary with datetime objects converted to strings.
 141    """
 142    for key, value in data.items():
 143        if isinstance(value, datetime):
 144            data[key] = value.isoformat()
 145        elif isinstance(value, dict):
 146            data[key] = convert_datetime_in_dict(value)
 147    return data
 148
 149
 150def head():
 151    """
 152    Every library should have a nice ASCII art :)
 153    Propose yours, there is a prize for the best one!
 154    """
 155    print()
 156    print("       HUMAN        AUGMENTED        BRAIN         SYSTEMS     ")
 157    print("   ----------------------------------------------------------- ")
 158    print("   ▒▒▒▒     ▒▒▒▒     ░▒▒▒▒▒░     ▒▒▒▒▒▒▒▒▒▒▒▒░   ░▒▒▒▒▒▒▒▒▒░   ")
 159    print("   ▒▒▒▒     ▒▒▒▒    ░▒▒▒▒▒▒▒░             ░▒▒▒▒ ░▒▒▒░     ░▒░  ")
 160    print("   ▒▒▒▒▒▒▒▒▒▒▒▒▒   ░▒▒▒▒ ▒▒▒▒░   ▒▒▒▒▒▒▒▒▒▒▒▒▒   ░▒▒▒▒▒▒▒▒▒░   ")
 161    print("   ▒▒▒▒     ▒▒▒▒  ░▒▒▒▒   ▒▒▒▒░  ▒▒▒▒     ░▒▒▒▒ ░▒░     ░▒▒▒░  ")
 162    print("   ▒▒▒▒     ▒▒▒▒ ░▒▒▒▒     ▒▒▒▒░ ▒▒▒▒▒▒▒▒▒▒▒▒░   ░▒▒▒▒▒▒▒▒▒░   ")
 163    print("   ----------------------------------------------------------- ")
 164    print("   version:", version("HABSlib"))
 165    print()
 166
 167
 168######################################################
 169def handshake(base_url, user_id):  
 170    """
 171    Perform a handshake with the server to exchange encryption keys for the current session.
 172
 173    This function performs the following steps:
 174    0. Performs login to the HABS server.
 175    1. Sends a GET request to the server to initiate an RSA handshake.
 176    2. Retrieves the server's public RSA key from the response.
 177    3. Generates a local AES key and stores it in the environment.
 178    4. Encrypts the AES key with the server's RSA key.
 179    5. Sends the encrypted AES key to the server to complete the AES handshake.
 180
 181    Args:      
 182        **base_url** (*str*): The base URL of the server's API.
 183        **user_id** (*str*): The user id (obtained through free registration with HABS)
 184
 185    Returns:     
 186        *bool*: True if the handshake is successful, None otherwise.
 187
 188    Raises:      
 189        **requests.RequestException**: If a request to the server fails.
 190
 191    Example:
 192    ```
 193    success = handshake("https://example.com")
 194    if success:
 195        print("Handshake completed successfully.")
 196    else:
 197        print("Handshake failed.")
 198    ```
 199    """
 200    head()
 201    global BASE_URL
 202    BASE_URL = base_url
 203    url = f"{BASE_URL}/api/{VERSION}/handshake_rsa"
 204    # response = requests.get(url)
 205    response = requests.get(url, headers={'X-User-ID':user_id}) # mongo _id for the user document. Communicated at user creation.
 206
 207    if response.status_code == 200:
 208        print("Handshake (RSA) successful.")
 209        api_public_key_pem = response.json().get('api_public_key')
 210        api_public_key = serialization.load_pem_public_key(
 211            api_public_key_pem.encode(),
 212            backend=default_backend()
 213        )
 214        os.environ['API_PUBLIC_KEY'] = api_public_key_pem
 215
 216        # Then we generate and store the AES key
 217        aes_key = generate_aes_key()
 218        # print("aes_key", aes_key)
 219        os.environ['AES_KEY'] = base64.b64encode( aes_key ).decode('utf-8')
 220
 221        encrypted_aes_key = encrypt_aes_key_with_rsa(aes_key, api_public_key)
 222        encrypted_aes_key_b64 = base64.b64encode(encrypted_aes_key).decode('utf-8')
 223        # print("encrypted_aes_key_b64",encrypted_aes_key_b64)
 224        aes_key_payload = {
 225            "encrypted_aes_key": encrypted_aes_key_b64
 226        }
 227        response = requests.post(f"{BASE_URL}/api/{VERSION}/handshake_aes", json=aes_key_payload, headers={'X-User-ID':user_id})
 228
 229        if response.status_code == 200:
 230            print("Handshake (AES) successful.")
 231            return True
 232        else:
 233            print("Handshake (AES) failed:", response.text)
 234            return None
 235    else:
 236        print("Handshake (RSA) failed:", response.text)
 237        return None
 238
 239
 240
 241######################################################
 242def set_user(user_id, first_name=None, last_name=None, role=None, group=None, email=None, age=None, weight=None, gender=None):
 243    """
 244    Creates a user by sending user data to the server.
 245
 246    This function performs the following steps:
 247    1. Constructs the user data dictionary.
 248    2. Validates the user data against the "userSchema".
 249    3. Encrypts the user data using the stored AES key.
 250    4. Sends the encrypted user data to the server.
 251    5. Handles the server's response.
 252
 253    Args:     
 254    **user_id** (*str*): The user id (obtained through free registration with HABS)
 255    **first_name** (*str*, optional): The user's first name.      
 256    **last_name** (*str*, optional): The user's last name.     
 257    **role** (*str*, required): The user's role (Admin, Developer, ... established at registration).     
 258    **group** (*str*, optional): The user's group (laboratory name, company name, ...).     
 259    **email** (*str*, required): The user's email address.     
 260    **age** (*int*, optional): The user's age.     
 261    **weight** (*float*, optional): The user's weight.     
 262    **gender** (*str*, optional): The user's gender.      
 263
 264    Returns:       
 265        *str*: The user ID if the user is successfully created/retrieved, None otherwise.
 266
 267    Example:
 268    ```
 269    user_id = set_user(first_name="John", last_name="Doe", email="john.doe@example.com", age=30, weight=70.5, gender="X")
 270    if user_id:
 271        print(f"User created/retrieved with ID: {user_id}")
 272    else:
 273        print("User creation failed.")
 274
 275    **NOTE**: In order to use this function, your role should be `Admin`
 276    ```
 277    """
 278    url = f"{BASE_URL}/api/{VERSION}/users"
 279    user_data = {
 280        "first_name": first_name, 
 281        "last_name": last_name, 
 282        "role": role, 
 283        "group": group, 
 284        "email": email, 
 285        "age": age, 
 286        "weight": weight, 
 287        "gender": gender
 288    }
 289    if validate_metadata(user_data, "userSchema"):
 290        _user = {
 291            "user_data": user_data
 292        }
 293        _user = json.dumps(_user).encode('utf-8')
 294        aes_key_b64 = os.environ.get('AES_KEY')
 295        aes_key_bytes = base64.b64decode(aes_key_b64)
 296        response = requests.post(
 297            url,
 298            data=encrypt_message(_user, aes_key_bytes),
 299            headers={'Content-Type': 'application/octet-stream', 'X-User-ID':user_id}
 300        )
 301
 302        if response.status_code == 201 or response.status_code == 208:
 303            print("User successfully created/retrieved.")
 304            user_id = response.json().get('user_id')
 305            return user_id
 306        else:
 307            print("User creation failed:", response.text)
 308            return None
 309    else:
 310        print("User creation failed.")
 311
 312
 313######################################################
 314def search_user_by_mail(user_id, email):
 315    """
 316    Search for a user by email.
 317
 318    This function sends a GET request to the server to search for a user by the provided email address.
 319
 320    Args:     
 321        **user_id** (*str*): The user id (obtained through free registration with HABS)
 322        **email** (*str*): The email address of the user to search for.
 323
 324    Returns:     
 325        *str*: The user ID if the user is found, None otherwise.
 326
 327    Example:
 328    ```
 329    user_id = search_user_by_mail("john.doe@example.com")
 330    if user_id:
 331        print(f"User found with ID: {user_id}")
 332    else:
 333        print("User not found.")
 334    ```
 335    """
 336    url = f"{BASE_URL}/api/{VERSION}/users?email={email}"
 337
 338    response = requests.get(url, headers={'X-User-ID':user_id}) # mongo _id for the user document. Communicated at user creation.
 339
 340    if response.status_code == 200:
 341        user_id = response.json().get('user_id')
 342        print("User found:", user_id)
 343        return user_id
 344    else:
 345        print("User not found.", response.text)
 346        return None
 347
 348
 349######################################################
 350def get_user_by_id(user_id):
 351    """
 352    Retrieve user data by user ID.
 353
 354    This function sends a GET request to the server to retrieve user data for the specified user ID.     
 355    The response data is decrypted using AES before returning the user data.
 356
 357    Args:     
 358        **user_id** (*str*): The unique identifier of the user to retrieve.
 359
 360    Returns:     
 361        *dict*: The user data if the user is found, None otherwise.
 362
 363    Example:
 364    ```
 365    user_data = get_user_by_id("1234567890")
 366    if user_data:
 367        print(f"User data: {user_data}")
 368    else:
 369        print("User not found.")
 370    ```
 371    """
 372    url = f"{BASE_URL}/api/{VERSION}/users/{user_id}"
 373
 374    response = requests.get(url, headers={'X-User-ID':user_id}) # mongo _id for the user document. Communicated at user creation.
 375
 376    if response.status_code == 200:
 377        print("User found.")
 378        encrypted_data = response.content 
 379        aes_key_b64 = os.environ.get('AES_KEY')
 380        aes_key_bytes = base64.b64decode(aes_key_b64)
 381        decrypted_json_string = decrypt_message(encrypted_data, aes_key_bytes)
 382        user_data = json.loads(decrypted_json_string)['user_data']
 383        return user_data
 384    else:
 385        print("User not found:", response.text)
 386        return None
 387
 388
 389######################################################
 390def set_session(metadata, user_id):
 391    """
 392    Create a new simple session.
 393
 394    This function sends a POST request to the server to create a new simple session using the provided metadata.
 395    The metadata is encrypted using AES before being sent to the server.
 396
 397    Args:     
 398        **metadata** (*dict*): A dictionary containing the session metadata. The only required metadata for the simple session are the user_id and a date.
 399        **user_id** (*str*): The user id (obtained through free registration with HABS)
 400
 401    Returns:      
 402        *str*: The unique identifier of the created session if successful, None otherwise.
 403
 404    Example:
 405    ```
 406    session_metadata = {
 407        "user_id": "1076203852085",
 408        "session_date": "2024-05-30T12:00:00Z"
 409    }
 410    session_id = set_session(session_metadata)
 411    if session_id:
 412        print(f"Session created with ID: {session_id}")
 413    else:
 414        print("Failed to create session.")
 415    ```
 416    """
 417    url = f"{BASE_URL}/api/{VERSION}/sessions"
 418    _session = metadata
 419    _session = json.dumps(_session).encode('utf-8')
 420    aes_key_b64 = os.environ.get('AES_KEY')
 421    aes_key_bytes = base64.b64decode(aes_key_b64)
 422    response = requests.post(
 423        url,
 424        data=encrypt_message(_session, aes_key_bytes),
 425        headers={'Content-Type': 'application/octet-stream', 'X-User-ID':user_id}
 426    )
 427
 428    if response.status_code == 200:
 429        print("Session successfully created.")
 430        # Extract the unique identifier for the uploaded data
 431        session_id = response.json().get('session_id')
 432
 433        # print("session_id: ",session_id)
 434        return session_id
 435    else:
 436        print("Session failed:", response.text)
 437        return None
 438
 439
 440######################################################
 441def get_data_by_id(data_id, user_id):
 442    """
 443    Retrieve raw data by its unique identifier from the server.
 444
 445    This function sends a GET request to fetch raw data associated with a specific identifier. It
 446    assumes that the data, if retrieved successfully, does not require decryption and is directly accessible.
 447
 448    Args:      
 449        **data_id** (*str*): The unique identifier for the data to be retrieved.
 450        **user_id** (*str*): The user id (obtained through free registration with HABS)
 451
 452    Returns:       
 453        **dict**: The raw data if retrieval is successful, None otherwise.
 454
 455    Example:
 456    ```
 457    data_id = "1234"
 458    raw_data = get_data_by_id(data_id)
 459    ... use the data
 460    ```
 461    """
 462    url = f"{BASE_URL}/api/{VERSION}/rawdata/{data_id}"
 463    
 464    # response = requests.get(url)
 465    response = requests.get(url, headers={'X-User-ID':user_id}) # mongo _id for the user document. Communicated at user creation.
 466
 467    if response.status_code == 200:
 468        print("Retrieved data successfully.")
 469        # decrypt
 470        return response.json().get('rawData')
 471    else:
 472        print("Failed to retrieve data:", response.text)
 473
 474
 475
 476######################################################
 477def find_sessions_by_user(user_id):
 478    """
 479    Retrieve session IDs associated with a given user.
 480
 481    This function sends a GET request to the API to retrieve all session IDs for a specified user.
 482    It expects the user ID to be passed as an argument and uses the user ID for authentication.
 483
 484    Args:
 485        user_id (str): The user ID (obtained through free registration with HABS).
 486
 487    Returns:
 488        list: A list of session IDs if the request is successful.
 489
 490    Raises:
 491        Exception: If the request fails or if there is an error in the response.
 492
 493    Example:
 494        >>> sessions = find_sessions_by_user("12345")
 495        >>> print(sessions)
 496        ["session1", "session2", "session3"]
 497
 498    Notes:
 499        Ensure that the environment variable `AES_KEY` is set to the base64 encoded AES key.
 500    """
 501    url = f"{BASE_URL}/api/{VERSION}/sessions/{user_id}"
 502
 503    response = requests.get(url, headers={'X-User-ID':user_id}) # mongo _id for the user document. Communicated at user creation.
 504
 505    if response.status_code == 200:
 506        print("User found.")
 507        encrypted_data = response.content 
 508        aes_key_b64 = os.environ.get('AES_KEY')
 509        aes_key_bytes = base64.b64decode(aes_key_b64)
 510        decrypted_json_string = decrypt_message(encrypted_data, aes_key_bytes)
 511        session_ids = json.loads(decrypted_json_string)['session_ids']
 512        return session_ids
 513    else:
 514        print("Failed to retrieve data:", response.text)
 515
 516
 517
 518######################################################
 519def get_data_by_session(session_id, user_id):
 520    """
 521    Retrieve raw data associated with a specific session identifier from the server.
 522
 523    This function sends a GET request to fetch all raw data linked to the given session ID. The data
 524    is returned in its raw form assuming it does not require decryption for usage.
 525
 526    Args:      
 527        **session_id** (*str*): The session identifier whose associated data is to be retrieved.
 528        **user_id** (*str*): The user id (obtained through free registration with HABS)
 529
 530    Returns:       
 531        *dict*: The raw data linked to the session if retrieval is successful, None otherwise.
 532
 533    Example:
 534    ```
 535    session_id = "abcd1234"
 536    session_data = get_data_by_session(session_id)
 537    if session_data:
 538        print("Data retrieved:", session_data)
 539    else:
 540        print("Failed to retrieve data.")
 541    ```
 542    """
 543    url = f"{BASE_URL}/api/{VERSION}/sessions/{session_id}/rawdata"
 544    
 545    # response = requests.get(url)
 546    response = requests.get(url, headers={'X-User-ID':user_id}) # mongo _id for the user document. Communicated at user creation.
 547    
 548    if response.status_code == 200:
 549        print("Retrieved data successfully.")
 550        # decrypt
 551        return response.json().get('data')
 552    else:
 553        print("Failed to retrieve data:", response.text)
 554
 555
 556
 557######################################################
 558def get_data_ids_by_session(session_id, user_id):
 559    """
 560    Retrieve a list of data IDs associated with a specific session from the server.
 561
 562    This function sends a GET request to fetch the IDs of all data entries linked to a specified session ID.
 563    The IDs are returned as a list. The function assumes the data does not require decryption for usage.
 564
 565    Args:      
 566        **session_id** (*str*): The session identifier for which data IDs are to be retrieved.
 567        **user_id** (*str*): The user id (obtained through free registration with HABS)
 568
 569    Returns:       
 570        *list*: A list of data IDs if retrieval is successful, None otherwise.
 571
 572    Example:
 573    ```
 574    session_id = "abcd1234"
 575    data_ids = get_data_ids_by_session(session_id)
 576    if data_ids:
 577        print("Data IDs retrieved:", data_ids)
 578    else:
 579        print("Failed to retrieve data IDs.")
 580    ```
 581    """
 582    url = f"{BASE_URL}/api/{VERSION}/sessions/{session_id}/ids"
 583    
 584    # response = requests.get(url)
 585    response = requests.get(url, headers={'X-User-ID':user_id}) # mongo _id for the user document. Communicated at user creation.
 586    
 587    if response.status_code == 200:
 588        print("Retrieved ids successfully.")
 589        # decrypt
 590        return response.json().get('ids')
 591    else:
 592        print("Failed to retrieve ids:", response.text)
 593
 594
 595
 596######################################################
 597def upload_data(metadata, timestamps, user_id, data, ppg_red, ppg_ir):
 598    """
 599    Uploads EEG (and PPG) data to the server along with associated metadata.
 600
 601    This function compiles different types of physiological data along with metadata into a single dictionary,
 602    encrypts the data, and then uploads it via a POST request. Upon successful upload, the server returns a
 603    unique identifier for the data which can then be used for future queries or operations.
 604
 605    Args:     
 606        **metadata** (*dict*): Information about the data such as subject details and session parameters.     
 607        **timestamps** (*list*): List of timestamps correlating with each data point.     
 608        **user_id** (*str*): The user id (obtained through free registration with HABS)
 609        **data** (*list*): EEG data points.     
 610        **ppg_red** (*list*): Red photoplethysmogram data points.     
 611        **ppg_ir** (*list*): Infrared photoplethysmogram data points.      
 612
 613    Returns:     
 614        *tuple*: A tuple containing the data ID of the uploaded data if successful, and None otherwise.
 615
 616    Notes:
 617        Ensure that timestamps has the same length of data last dimension.
 618
 619    Example:
 620    ```
 621    metadata = {"session_id": "1234", "subject_id": "001"}
 622    timestamps = [1597709184, 1597709185]
 623    data = [0.1, 0.2]
 624    ppg_red = [123, 124]
 625    ppg_ir = [125, 126]
 626    data_id, error = upload_data(metadata, timestamps, data, ppg_red, ppg_ir)
 627    if data_id:
 628        print("Data uploaded successfully. Data ID:", data_id)
 629    else:
 630        print("Upload failed with error:", error)
 631    ```
 632    """
 633    url = f"{BASE_URL}/api/{VERSION}/rawdata"
 634    _data = {
 635        "metadata": metadata,
 636        "timestamps": timestamps,
 637        "data": data,
 638        "ppg_red": ppg_red,
 639        "ppg_ir": ppg_ir
 640    }
 641    _data = json.dumps(_data).encode('utf-8')
 642
 643    # response = requests.post(url, json=_data)
 644    aes_key_b64 = os.environ.get('AES_KEY')
 645    aes_key_bytes = base64.b64decode(aes_key_b64)
 646    response = requests.post(
 647        url,
 648        data=encrypt_message(_data, aes_key_bytes),
 649        headers={'Content-Type': 'application/octet-stream', 'X-User-ID':user_id}
 650    )
 651    # response = requests.get(url, headers={'X-User-ID':USERID}) # mongo _id for the user document. Communicated at user creation.
 652
 653    if response.status_code == 200:
 654        print('.', end='', flush=True)
 655        # Extract the unique identifier for the uploaded data
 656        data_id = response.json().get('data_id')
 657        return data_id, None
 658    else:
 659        print("Upload failed:", response.text)
 660        return None
 661
 662
 663
 664######################################################
 665def acquire_send_raw(user_id, date, board, serial_number, stream_duration, buffer_duration, session_type="", tags=[], callback=None, extra=None):
 666    """
 667    Asynchronously acquires raw data from a specific EEG board and sends it to the server.
 668
 669    This function connects to an EEG board, initiates a data acquisition session, and sends the collected data
 670    to the server in real-time or near real-time. It ensures that all the data handled during the session
 671    is associated with a unique session ID and metadata that includes user and session details. The function
 672    will validate the session metadata before proceeding with data acquisition and sending.
 673
 674    Args:      
 675    **user_id** (*str*): The unique identifier of the user for whom the data is being collected.      
 676    **date** (*str*): The date of the session, used for metadata purposes.     
 677    **board** (*int*): Identifier for the EEG board from which data will be acquired.      
 678    **stream_duration** (*int*): Duration in seconds for which data will be streamed from the board.     
 679    **buffer_duration** (*int*): Time in seconds for how often the data is buffered and sent.     
 680
 681    Returns:     
 682    *str* or *bool*: The session ID if the operation is successful; False otherwise.
 683
 684    Raises:
 685    **ConnectionError**: If the board connection fails.      
 686    **ValidationError**: If the metadata does not comply with the required schema.
 687
 688    Example:
 689    ```
 690    session = acquire_send_raw('user123', '2021-06-01', 'MUSE_S', 300, 10)
 691    if session:
 692        print(f"Session successfully started with ID: {session}")
 693    else:
 694        print("Failed to start session")
 695    ```
 696    """
 697    # set session for the data
 698    # We set a session id for the current interaction with the API (even if we fail to get the board, it will be important to store the failure)
 699    session_metadata = {
 700      "user_id": user_id, # add user to the session for reference
 701      "session_date": date,
 702      "session_type": session_type,
 703      "session_tags": tags
 704    }
 705    session_id = set_session(metadata={**session_metadata}, user_id=user_id)
 706    print("\nSession initialized. You can visualize it here:\n ", "https://habs.ai/live.html?session_id="+str(session_id), "\n")
 707
 708    if validate_metadata(session_metadata, "sessionSchema"):
 709        asyncio.run( 
 710            _acquire_send_raw(user_id, session_id, board, serial_number, stream_duration, buffer_duration, callback, extra) 
 711        )
 712        return session_id
 713    else:
 714        print("Session initialization failed.")
 715        return False
 716
 717# async appendage
 718async def _acquire_send_raw(user_id, session_id, board, serial_number, stream_duration, buffer_duration, callback=None, extra=None):
 719    # get board
 720    board_manager = BoardManager(enable_logger=False, board_id=board, serial_number=serial_number, extra=extra)
 721    board_manager.connect()
 722
 723    board_manager.metadata['session_id'] = session_id # add session to the data for reference
 724
 725    # stream_duration sec, buffer_duration sec
 726    await board_manager.data_acquisition_loop(
 727        stream_duration=stream_duration, 
 728        buffer_duration=buffer_duration, 
 729        service=upload_data,
 730        user_id=user_id,
 731        callback=callback
 732    )
 733
 734
 735
 736######################################################
 737def send_file(user_id, date, edf_file, ch_nrs=None, ch_names=None, session_type="", tags=[]):
 738    """
 739    Uploads EEG data from a file to the server along with associated metadata.
 740
 741    This function compiles EEG data from an [EDF file](https://www.edfplus.info/downloads/index.html) along with metadata into a single dictionary,
 742    encrypts the data, and then uploads it via a POST request. Upon successful upload, the server returns a
 743    unique identifier for the session which can then be used for future queries or operations.
 744
 745    Args:    
 746    **user_id** (*str*): The unique identifier of the user for whom the data is being collected.     
 747    **metadata** (*dict*): Information about the data such as subject details and session parameters.     
 748    **date** (*str*): The date of the session, used for metadata purposes.     
 749    **edf_file** (*str*): name of an EDF file.      
 750    **ch_nrs** (*list of int*, optional): The indices of the channels to read. The default is None.     
 751    **ch_names** (*list of str*, optional): The names of channels to read. The default is None.     
 752
 753    Returns:     
 754        *tuple*: A tuple containing the session ID of the uploaded data if successful, and None otherwise.
 755
 756    Example:
 757    ```
 758    session = send_file('user123', '2021-06-01', 'nameoffile.edf')
 759    if session:
 760        print(f"Session successfully started with ID: {session}")
 761    else:
 762        print("Failed to start session")
 763    ```
 764    """
 765
 766    try:
 767        signals, signal_headers, header = highlevel.read_edf(edf_file, ch_nrs, ch_names)
 768
 769        max_time = signals.shape[1] / signal_headers[0]['sample_frequency']
 770        timestamps = np.linspace(header['startdate'].timestamp(), max_time, signals.shape[1])
 771
 772        session_metadata = {
 773          "user_id": user_id, # add user to the session for reference
 774          "session_date": header['startdate'].strftime("%m/%d/%Y, %H:%M:%S"),
 775          "session_type": session_type,
 776          "session_tags": tags
 777        }
 778        if validate_metadata(session_metadata, "sessionSchema"):
 779            session_id = set_session(metadata={**session_metadata}, user_id=user_id)
 780            metadata = {'session_id':session_id, **session_metadata, **convert_datetime_in_dict(header), **convert_datetime_in_dict(signal_headers[0])}
 781
 782            chunks = ((signals.size * signals.itemsize)//300000)+1
 783            timestamps_chunks = np.array_split(timestamps, chunks)
 784            signals_chunks = np.array_split(signals, chunks, axis=1)
 785            json_data = json.dumps(signals_chunks[0].tolist())
 786            size_in_bytes = sys.getsizeof(json_data)
 787            print("%d total bytes will be sent into %d chunks of %d bytes" % (signals.size * signals.itemsize, chunks, size_in_bytes))
 788
 789            for timestamps_chunk,signals_chunk in zip(timestamps_chunks, signals_chunks):
 790                upload_data(metadata, timestamps_chunk.tolist(), user_id, signals_chunk.tolist(), [], [])
 791
 792            return session_id
 793        else:
 794            return False
 795    except Exception as e:
 796        print("A general error occurred:", e)
 797        return False    
 798
 799
 800
 801######################################################
 802######################################################
 803def set_pipe(metadata, pipeline, params, user_id):
 804    """
 805    Configures and initiates a data processing pipeline for a session on the server.
 806
 807    This function sends metadata and processing parameters to a specified pipeline endpoint
 808    to create a data processing session. It encrypts the session data before sending to ensure
 809    security. The function checks the server response to confirm the session creation.
 810
 811    Args:     
 812    **metadata** (*dict*): A dictionary containing metadata about the session, typically including
 813                     details such as user ID and session date.       
 814    **pipeline** (*str*): The identifier for the processing pipeline to be used.      
 815    **params** (*dict*): Parameters specific to the processing pipeline, detailing how data should
 816                   be processed.      
 817    **user_id** (*str*): The user id (obtained through free registration with HABS)
 818
 819    Returns:       
 820        *str* or *None*: The session ID if the session is successfully created, or None if the operation fails.
 821
 822    Raises:     
 823        **requests.exceptions.RequestException**: An error from the Requests library when an HTTP request fails.      
 824        **KeyError**: If necessary keys are missing in the environment variables.
 825
 826    Example:
 827    ```
 828    session_metadata = {"user_id": "123", "session_date": "2024-06-03"}
 829    processing_params = {"filter_type": "lowpass", "cutoff_freq": 30}
 830    session_id = set_pipe(session_metadata, 'eeg_smoothing', processing_params)
 831    if session_id:
 832        print(f"Pipeline session created with ID: {session_id}")
 833    else:
 834        print("Failed to create pipeline session")
 835    ```
 836    """
 837    url = f"{BASE_URL}/api/{VERSION}/sessions/pipe/{pipeline}"
 838    _session = {
 839        "metadata": metadata,
 840        "processing_params": params,
 841    }
 842    _session = json.dumps(_session).encode('utf-8')
 843    aes_key_b64 = os.environ.get('AES_KEY')
 844    aes_key_bytes = base64.b64decode(aes_key_b64)
 845    response = requests.post(
 846        url,
 847        data=encrypt_message(_session, aes_key_bytes),
 848        headers={'Content-Type': 'application/octet-stream', 'X-User-ID':user_id}
 849    )
 850    if response.status_code == 200:
 851        print("Session successfully created.")
 852        # Extract the unique identifier for the uploaded data
 853        session_id = response.json().get('session_id')
 854        # print(session_id)
 855        return session_id
 856    else:
 857        print("Session failed:", response.text)
 858        return None
 859
 860
 861
 862######################################################
 863def upload_pipedata(metadata, timestamps, user_id, data, ppg_red, ppg_ir):
 864    """
 865    Uploads processed data to a specific session on the server.
 866
 867    This function is responsible for uploading various data streams associated with a session, including
 868    timestamps and physiological measurements such as PPG (Photoplethysmogram). The data is encrypted before
 869    sending to ensure confidentiality and integrity.
 870
 871    Args:        
 872    **metadata** (*dict*): Contains session-related metadata including the session ID.      
 873    **timestamps** (*list*): A list of timestamps corresponding to each data point.      
 874    **user_id** (*str*): The user id (obtained through free registration with HABS)
 875    **data** (*list*): The main data collected, e.g., EEG readings.      
 876    **ppg_red** (*list*): Red channel data from a PPG sensor.    
 877    **ppg_ir** (*list*): Infrared channel data from a PPG sensor.     
 878
 879    Returns:     
 880    *tuple*: A tuple containing the data ID if the upload is successful and the processed data, or None if the upload fails.
 881
 882    Raises:     
 883    **requests.exceptions.RequestException: An error from the Requests library when an HTTP request fails.
 884    **KeyError**: If necessary keys are missing in the environment variables.
 885
 886    Example:
 887    ```
 888    session_metadata = {"session_id": "12345"}
 889    timestamps = [1597709165, 1597709166, ...]
 890    data = [0.1, 0.2, ...]
 891    ppg_red = [12, 15, ...]
 892    ppg_ir = [20, 22, ...]
 893    data_id, processed_data = upload_pipedata(session_metadata, timestamps, data, ppg_red, ppg_ir)
 894    if data_id:
 895        print(f"Data uploaded successfully with ID: {data_id}")
 896    else:
 897        print("Failed to upload data")
 898    ```
 899    """
 900    url = f"{BASE_URL}/api/{VERSION}/pipedata/{metadata['session_id']}" # the metadata contain session_id to consistently pass it with each upload
 901
 902    _data = {
 903        "metadata": metadata,
 904        "timestamps": timestamps,
 905        "data": data,
 906        "ppg_red": ppg_red,
 907        "ppg_ir": ppg_ir
 908    }
 909    _data = json.dumps(_data).encode('utf-8')
 910    aes_key_b64 = os.environ.get('AES_KEY')
 911    aes_key_bytes = base64.b64decode(aes_key_b64)
 912    response = requests.post(
 913        url,
 914        data=encrypt_message(_data, aes_key_bytes),
 915        headers={'Content-Type': 'application/octet-stream', 'X-User-ID':user_id}
 916    )
 917
 918    if response.status_code == 200:
 919        print('.', end='', flush=True)
 920        # Extract the unique identifier for the uploaded data
 921        data_id = response.json().get('data_id')
 922        # Retrieve the processed data
 923        data = response.json().get('pipeData')
 924        return data_id, data
 925    else:
 926        print("Upload failed:", response.text)
 927        return None
 928
 929
 930######################################################
 931def acquire_send_pipe(pipeline, params, user_id, date, board, serial_number, stream_duration, buffer_duration, session_type="", tags=[], callback=None, extra=None):
 932    """
 933    Acquires data from a board, processes it according to a specified pipeline, and sends it to a server.
 934    This function handles setting up a session for data acquisition and processing, connects to a board, 
 935    and manages the data flow from acquisition through processing to uploading. It uses an asynchronous loop
 936    to handle the operations efficiently, suitable for real-time data processing scenarios.
 937
 938    Args:
 939    **pipeline** (*str*): Name of the processing pipeline to use.     
 940    **params** (*dict*): Parameters for the pipeline processing.      
 941    **user_id** (*str*): The user ID to which the session will be associated.      
 942    **date** (*str*): Date of the session for tracking purposes.      
 943    **board** (*int*): Identifier for the hardware board to use for data acquisition.      
 944    **stream_duration** (*int*): Duration in seconds to stream data from the board.     
 945    **buffer_duration** (*int*): Duration in seconds to buffer data before processing.      
 946    **callback** (*function*): Optional callback function to execute after data is sent.
 947
 948    Returns:    
 949        *str* or *bool*: The session ID if successful, False otherwise.
 950
 951    """
 952    # set session for the data
 953    # We set a session id for the current interaction with the API (even if we fail to get the board, it will be important to store the failure)
 954    session_metadata = {
 955      "user_id": user_id, # add user to the session for reference
 956      "session_date": date,
 957      "session_type": session_type,
 958      "session_tags": tags
 959    }
 960    if validate_metadata(session_metadata, "sessionSchema"):
 961        session_id = set_pipe(metadata={**session_metadata}, pipeline=pipeline, params=params, user_id=user_id)
 962        print("\nSession initialized. You can visualize it here:\n ", "https://habs.ai/bos/live.html?session_id="+str(session_id), "\n")
 963
 964        asyncio.run( 
 965            _acquire_send_pipe(pipeline, params, user_id, session_id, board, serial_number, stream_duration, buffer_duration, callback, extra) 
 966        )
 967        return session_id #, self.processed_data
 968    else:
 969        print("Session initialization failed.")
 970        return False
 971
 972# async appendage
 973async def _acquire_send_pipe(pipeline, params, user_id, session_id, board, serial_number, stream_duration, buffer_duration, callback=None, extra=None):
 974    # get board
 975    board_manager = BoardManager(enable_logger=False, board_id=board, serial_number=serial_number, extra=extra)
 976    board_manager.connect()
 977
 978    board_manager.metadata['session_id'] = session_id # add session to the data for reference
 979
 980    # stream_duration sec, buffer_duration sec
 981    await board_manager.data_acquisition_loop(
 982        stream_duration=stream_duration, 
 983        buffer_duration=buffer_duration, 
 984        service=upload_pipedata,
 985        user_id=user_id,
 986        callback=callback
 987    )
 988
 989
 990
 991
 992######################################################
 993def get_user_database(user_id):
 994    """
 995    Retrieve all user data by user ID.
 996
 997    This function sends a GET request to the server to dump all data stored for the specified user ID.     
 998    The response data is decrypted using AES before returning the user data.
 999
1000    Args:     
1001        **user_id** (*str*): The unique identifier of the user to retrieve.
1002
1003    Returns:     
1004        *None*: A zip file contaning all data as JSON files, None otherwise.
1005
1006    Example:
1007    ```
1008    user_data = get_user_database("1234567890")
1009    if user_data:
1010        print(f"User data: {user_data}")
1011    else:
1012        print("User not found.")
1013    ```
1014    """
1015    url = f"{BASE_URL}/api/{VERSION}/database/dump/{user_id}"
1016
1017    response = requests.get(url, headers={'X-User-ID': user_id}, stream=True)
1018
1019    if response.status_code == 200:
1020        # Open a local file with write-binary mode
1021        strtime = datetime.today().strftime("%Y%m%d_%H%M%S")
1022
1023        with open(f"brainos_{strtime}_dump.zip", 'wb') as file:
1024            # Write the response content to the file in chunks
1025            for chunk in response.iter_content(chunk_size=8192):
1026                file.write(chunk)
1027        print("Database dump saved successfully.")
1028        return True
1029    else:
1030        print("User not found:", response.text)
1031        return None
1032
1033
1034
1035
1036######################################################
1037def create_tagged_interval(user_id, session_id, eeg_data_id, start_time, end_time, tags, channel_ids=None):
1038    """
1039    Creates a tagged interval by sending the interval data to the server.
1040
1041    This function performs the following steps:
1042    1. Constructs the interval data dictionary.
1043    2. Validates the interval data against the "tagSchema".
1044    3. Sends the interval data to the server.
1045
1046    Args:
1047    **session_id** (*str*): The session id.
1048    **eeg_data_id** (*str*): The EEG data id.
1049    **start_time** (*str*): The start time of the interval in ISO 8601 format.
1050    **end_time** (*str*): The end time of the interval in ISO 8601 format.
1051    **tags** (*list*): List of tags, each tag is a dictionary containing a "tag" and "properties".
1052    **channel_ids** (*list*, optional): List of channel ids the tag applies to. If None, applies to all channels.
1053
1054    Returns:
1055        *str*: The interval ID if the interval is successfully created, None otherwise.
1056
1057    Example:
1058    ```
1059    interval_id = create_tagged_interval(
1060        session_id="session_123",
1061        eeg_data_id="eeg_data_456",
1062        start_time="2023-01-01T00:00:00Z",
1063        end_time="2023-01-01T00:05:00Z",
1064        tags=[{"tag": "seizure", "properties": {"severity": "high"}}]
1065    )
1066    if interval_id:
1067        print(f"Tagged interval created with ID: {interval_id}")
1068    else:
1069        print("Tagged interval creation failed.")
1070    ```
1071    """
1072    url = f"{BASE_URL}/api/{VERSION}/session/{session_id}/tag"
1073    interval_data = {
1074        "user_id": user_id,
1075        "session_id": session_id,
1076        "eeg_data_id": eeg_data_id,
1077        "start_time": start_time,
1078        "end_time": end_time,
1079        "tags": tags,
1080        "channel_ids": channel_ids if channel_ids else []
1081    }
1082    
1083    if validate_metadata(interval_data, "tagSchema"):
1084        response = requests.post(
1085            url,
1086            json=interval_data,
1087            headers={'Content-Type': 'application/json'}
1088        )
1089
1090        if response.status_code == 201:
1091            print("Tagged interval successfully created.")
1092            interval_id = response.json().get('interval_id')
1093            return interval_id
1094        else:
1095            print("Tagged interval creation failed:", response.text)
1096            return None
1097    else:
1098        print("Tagged interval creation failed due to validation error.")
1099
1100
1101
1102
1103
1104######################################################
1105def process_session_pipe(pipeline, params, user_id, date, existing_session_id, session_type="", tags=[]):
1106    """
1107    Process a session pipeline with specified parameters and metadata.
1108
1109    This function processes an existing session by applying a specified pipeline and parameters.
1110    It sends a POST request to the API with the session metadata and processing parameters,
1111    creating a new session based on the existing one.
1112
1113    Args:
1114        **pipeline** (*str*): The pipeline to be applied to the session.
1115        **params** (*dict*): The processing parameters for the pipeline.
1116        **user_id** (*str*): The user ID (obtained through free registration with HABS).
1117        **date** (*str*): The date of the session.
1118        **existing_session_id** (*str*): The ID of the existing session to be processed.
1119        **session_type** (*str*, optional): The type of the new session. Defaults to an empty string.
1120        **tags** (*list*, optional): A list of tags associated with the session. Defaults to an empty list.
1121
1122    Returns:
1123        tuple: A tuple containing the new session ID and the processed data if the request is successful.
1124        None: If the session creation fails.
1125        bool: False if the session metadata is invalid.
1126
1127    Example:
1128        >>> new_session_id, processed_data = process_session_pipe("my_pipeline", {"param1": "value1"}, "12345", "2023-07-03", "existing_session_001")
1129        >>> print(new_session_id, processed_data)
1130
1131    Notes:
1132        Ensure that the environment variable `AES_KEY` is set to the base64 encoded AES key.
1133
1134    Raises:
1135        Exception: If there is an error in the request or response.
1136
1137    """
1138    session_metadata = {
1139      "user_id": user_id, # add user to the session for reference
1140      "session_date": date, # .strftime("%m/%d/%Y, %H:%M:%S"),
1141      "existing_session_id": existing_session_id,
1142      "session_type": f"[On {existing_session_id}]: {session_type}", # type of the new session
1143      "session_tags": tags
1144    }
1145    if validate_metadata(session_metadata, "sessionSchema"):
1146        url = f"{BASE_URL}/api/{VERSION}/sessions/{existing_session_id}/pipe/{pipeline}"
1147        _session = {
1148            "metadata": session_metadata,
1149            "processing_params": params,
1150        }
1151        _session = json.dumps(_session).encode('utf-8')
1152        aes_key_b64 = os.environ.get('AES_KEY')
1153        aes_key_bytes = base64.b64decode(aes_key_b64)
1154        response = requests.post(
1155            url,
1156            data=encrypt_message(_session, aes_key_bytes),
1157            headers={'Content-Type': 'application/octet-stream', 'X-User-ID':user_id}
1158        )
1159        if response.status_code == 200:
1160            print("Session successfully created.")
1161            session_id = response.json().get('session_id')
1162            pipeData = response.json().get('pipeData')
1163            # print(session_id)
1164            return session_id, pipeData
1165        else:
1166            print("Session failed:", response.text)
1167            return None
1168
1169        return session_id # processed_data
1170    else:
1171        print("Session failed.")
1172        return False
1173
1174
1175
1176
1177######################################################
1178def train(session_id, params, user_id):
1179    """
1180    Sends a request to the server to train a machine learning algorithm on the data from a specified session.
1181
1182    Args:     
1183    **session_id** (*str*): The unique identifier of the session containing the data to be used for training.       
1184    **params** (*dict*): The parameters for the training process.
1185    **user_id** (*str*): The user id (obtained through free registration with HABS)
1186
1187    Returns:      
1188        *str* or *None*: The task ID if the request is successful, None otherwise.
1189
1190    This function sends the training parameters and session ID to the server, which initiates the training process.
1191    The response includes a task ID that can be used for future interactions related to the training task.
1192
1193    Example:
1194    ```
1195    train("session_12345", {"param1": "value1", "param2": "value2"})
1196    ```
1197    """
1198    url = f"{BASE_URL}/api/{VERSION}/train/{session_id}"
1199    _params = {
1200        "params": params,
1201    }
1202    _params = json.dumps(_params).encode('utf-8')
1203    aes_key_b64 = os.environ.get('AES_KEY')
1204    aes_key_bytes = base64.b64decode(aes_key_b64)
1205    response = requests.post(
1206        url,
1207        data=encrypt_message(_params, aes_key_bytes),
1208        headers={'Content-Type': 'application/octet-stream', 'X-User-ID':user_id}
1209    )
1210    # response = requests.get(url, headers={'X-User-ID':USERID}) # mongo _id for the user document. Communicated at user creation.
1211
1212    if response.status_code == 200:
1213        task_id = response.json().get('task_id')
1214        print("Published. For future interactions, use task_id:",task_id)
1215        return task_id
1216    else:
1217        print("Publish failed:", response.text)
1218        return None
1219
1220
1221
1222
1223######################################################
1224def infer(data_id, params, user_id):
1225    """
1226    Sends a request to the server to perform machine learning inference based on a previously trained model, given the data ID.
1227
1228    Args:     
1229    **data_id** (*str*): The unique identifier of the data to be used for inference.      
1230    **params** (*dict*): The parameters for the inference process.
1231    **user_id** (*str*): The user id (obtained through free registration with HABS)
1232
1233    Returns:
1234    *str* or *None*: The task ID if the request is successful, None otherwise.
1235
1236    This function sends the inference parameters and data ID to the server, which initiates the inference process.
1237    The response includes a task ID that can be used for future interactions related to the inference task.
1238
1239    Example:
1240    ```
1241    infer("data_12345", {"param1": "value1", "param2": "value2"})
1242    ```
1243    """
1244    url = f"{BASE_URL}/api/{VERSION}/infer/{data_id}"
1245    _params = {
1246        "params": params,
1247    }
1248    _params = json.dumps(_params).encode('utf-8')
1249    # response = requests.post(url, json=_params)
1250    aes_key_b64 = os.environ.get('AES_KEY')
1251    aes_key_bytes = base64.b64decode(aes_key_b64)
1252    response = requests.post(
1253        url,
1254        data=encrypt_message(_params, aes_key_bytes),
1255        headers={'Content-Type': 'application/octet-stream', 'X-User-ID':user_id}
1256    )
1257    # response = requests.get(url, headers={}) # mongo _id for the user document. Communicated at user creation.
1258    
1259    if response.status_code == 200:
1260        task_id = response.json().get('task_id')
1261        print("Published. For future interactions, use task_id:",task_id)
1262        return task_id
1263    else:
1264        print("Publish failed:", response.text)
1265        return None