The Oxynet Python package repository

🌍
We require world-wide coordinated actions for timely diagnostics.
🏥
Oxynet research project contributes with more equitable health care services.
💻
Oxynet is a set of tools for automatic interpretation of cardiopulmonary exercising tests data.

Visit the website »
Overleaf · Web app · Pypi · Docs

(back to top)

Pyoxynet is a collection of algorithms developed in the context of the Oxynet project. All the algorithms are constituted by deep neural networks, i.e. models conceived to process cardiopulmonary exercise test data (CPET).

All the models are Keras models trained and tested with Tensorflow. Starting from version 0.1.5, Pyoxynet offers flexible deployment options with TFLite as the recommended inference engine for production environments due to its lightweight footprint and optimized performance.

To date, mainly two type of models are implemented:

• The inference model: it takes some CPET data as input and it provides an estimation of the exercise intensity domains
• The generator model: it generates new synthetic CPET data

There is no need to clone this repo if you don't want to. You can just install the public Python package or call the public Flask-Pyoxynet service from a web app, a terminal on a server or from your browser.

⚠️ Important: Starting from version 0.1.5, pyoxynet requires Python 3.10 and NumPy < 2.0 for optimal performance with TensorFlow Lite support.

Pyoxynet now offers three installation options to match your specific needs:

Perfect for data processing and analysis without model inference:

pip install pyoxynet

Lightweight model inference with ~90% smaller footprint than full TensorFlow:

pip install "pyoxynet[tflite]" --extra-index-url https://google-coral.github.io/py-repo/

Complete TensorFlow support for model training and advanced features:

pip install "pyoxynet[full]"

You can also install directly from the repository:

pip install git+https://github.com/andreazignoli/pyoxynet.git#subdirectory=pyoxynet

• Faster deployment: Reduced package size and installation time
• Better performance: TFLite optimized inference for production environments
• Flexibility: Choose only the dependencies you need
• API compatibility: Internal API uses TFLite for lightweight, fast predictions

NumPy Compatibility Issue: If you encounter errors like "_ARRAY_API not found" or "numpy.core.multiarray failed to import" when using TFLite, install NumPy 1.x:

pip install "numpy<2"

This occurs because tflite-runtime was compiled against NumPy 1.x and is not yet compatible with NumPy 2.x. The app's requirements.txt automatically handles this by pinning to numpy==1.26.4.

(back to top)

Data required for the inference include oxygen uptake (VO2), exhaled CO2 (VCO2), minute ventilation (VE), end tidal O2 (PetO2) and CO2(PetCO2), and ventilatory equivalents (VEVO2 and VEVCO2):

Oxynet inference models work on data over-sampled on a sec-by-sec basis. When dealing with breath-by-breath data, linear interpolation at 1 second is appropriate in my experience (little error is introduced). When dealing with averaged 5-by-5 second data or 10-by-10 second data, cubic interpolation is more appropriate in my experience. Pyoxynet however, can implement a number of interpolation algorithm to process raw data as well as data already processed.

In case there is no access to VCO2 data, a different solution has been implemented (although validation has not been published) considering the following inputs:

If you want to see how Pyoxynet can work on sample data:

import pyoxynet

# Load the TFL model
tfl_model = pyoxynet.load_tf_model(n_inputs=5, past_points=40, model='CNN')

# Make inference on a random input
pyoxynet.test_pyoxynet(tfl_model)

For more examples, please refer to the package Documentation

(back to top)

Pyoxynet also implements a Conditional Generative Adversarial Network, which has been trained to generate deceptive CPET data. As per the inference model, the generator is saved in a TFLite model file. Calling the related function and obtain a fake CPET data sample can be done as follows:

from pyoxynet import *
# Call the generator
generator = load_tf_generator()
# Generate a Pandas df with fake CPET data inside
df = generate_CPET(generator, plot=True)
# Call Oxynet for inference on fake data
test_pyoxynet(input_df=df)

Fake data provided during the generation include oxygen uptake (VO2), exhaled CO2 (VCO2), minute ventilation (VE), heart rate (HR), respiratory frequency (RF), and end tidal O2 (PetO2) and CO2(PetCO2) (generation therefore does not provide and ventilatory equivalents):

Importantly, given that RF data is generated, a complete breath-by-breath dataset can be generated. In the gif below, different epochs/steps of the training process are presented for the Conditional Adversarial Neural Network available in Pyoxynet.

(back to top)

A Flask inference/generation app called Flask-Pyoxynet has been deployed on Heroku using containerized deployment with Docker. The app runs the lightweight TFLite version of Pyoxynet for optimal performance and reduced resource usage.

It is possible therefore to call Flask-Pyoxynet from a terminal, and provide data in json format or in csv format. In case of json format you can have:

curl -X POST https://pyoxynet-lite-app-b415901c79ab.herokuapp.com/read_json_ET -d @test_data.json

But if you have your file in csv format you can type:

curl -X POST -F 'file=@YOUR_CSV_FILE.csv' https://pyoxynet-lite-app-b415901c79ab.herokuapp.com/curl_csv

It is possible to check the required keys of the json dictionary in app/test_data/test_data.json. Alternatively, it is possible to directly check the generated example at this address. It is also possible to directly retrieve generated data in json format at this address. The app can also be used as test to check how realistic the fake examples.

👉 TRY THE APP HERE 👈

• Create web app for inference
• Create web app for data crowd-sourcing
• Create website
• Create Python package
  • Implement inference
  • Implement generation
• Develop Flask-app
• Run Docker on AWS
• Develop GUI for generation
  • Improve GUI
  • ----

See the open issues for a full list of proposed features (and known issues).

(back to top)

There are challenges that transcend both national and continental boundaries and providing people with universal access to good quality health care is one of them. Emerging technologies in the field of AI and the availability of vast amounts of data can offer big opportunities to stimulate innovation and develop solutions.

Oxynet wants to become a tool for a quick and encompassing diagnosis of medical conditions with cardiopulmonary exercise tests (CPET) and promote accurate and timely clinical decisions, ultimately reducing the costs associated with current evaluation errors and delays.

The main building blocks of Oxynet are:

• A network of experts in the field of CPET
• A large crowd sourced data set
• An AI algorithm able to approximate human cognition in the analysis of CPET

We are interested in creating more research opportunities with other Universities and Departments, hospitals and clinics, medical doctors and physiologists (also operating in intensive care units), companies involved in the development (including patenting and validation) and in the commercialization of medical devices (e.g. metabolic carts and medical software).

We want to bring together key actors from across sectors to jointly implement our R&D road map and: support the research activities financially (including scholarships for research fellows or publication fees for open access journals), provide intellectual contribution for scientific publications or grant application, share data for testing/developing new algorithms, develop web-based applications (e.g. crowd sourcing applications, automatic interpretation of new data, websites for communicating the outcomes of the project), conduct market and patent analyses, and validate the algorithms for clinical settings.

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated. If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give Pyoxynet a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)

Andrea Zignoli - @andrea_zignoli - andrea.zignoli@unitn.it

Repository project link: Pyoxynet

(back to top)

You can read more about the rationale and the technology behind the Oxynet project at the following links:

• Research paper about the application of the collective intelligence concept to the automatic interpretation of CPET with AI techniques
• Review paper on the AI technologies applied to exercise cardiopulmonary and metabolic data processing
• Research implementing an LSTM neural networks to the estimation of VO2 during cycling exercise (regressor)
• Research implementing an LSTM neural networks to the estimation of the intensity domain during incremental exercise (classifier)
• Research implementing a crowd sourcing and CNN inference to the problem of determining the intensity domain during incremental exercise (classifier)
• Research generating synthetic CPET data with conditional GANs
• Research from regression to generation to explanation
• LinkedIn article about the Oxynet project
• Blog article about the problem of adopting AI models in the interpretation of CPET data
• Medium Story about how to use the Python package to make an inference on a generic CPET file
• Medium Story about how to use the Python package with a generic CPET file about how to use the Python package to generate a fake-but-realistic CPET file

(back to top)

The followings are valuable source of knowledge and inspiration for both the Pyoxynet and Oxynet projects:

• TFLite inference
• Amazon Lightsail
• Flask
• Uniplot Python library
• Machine Learning Mastery cGAN
• Exercise Threshold

(back to top)

All content found on this website, including: text, images, tables, or other formats are created for informational purposes only. The information provided by this software is not intended to be a substitute for professional medical advice, diagnosis, or treatment. Always seek the advice of your physician or other qualified health provider with any questions you may have regarding a medical condition. Never disregard professional medical advice or delay in seeking it because of something has been provided by this software.

(back to top)