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)

The Pyoxynet package

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, and they are included in Pyoxynet only in their TFLite inference version in versions <11.6. TFLite has been intentionally adopted to keep the package light and fast. However, after version 11.6 the Tensorflow models are directly used.

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

Getting Started

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.

Pip install the package

☝️ This package was developed under Python 3.8, so it might not work properly under older versions. The reason why the 3.8 version is not updated to more recent versions is related to the way packages are now distributed and installed for versions >3.8.

To the best of my knowledge, this is the best solution for those Python users who would like to have Oxynet algorithms always on the tip of their fingers. Assuming you have pip installed on your machine, begin with:

pip install pyoxynet

Or, alternatively,

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

Packages that require addition extra url cannot be installed via setuptools, which lately allows and suggests to use pip when possible. To workaround this problem, TFLite is automatically installed with the following command the first time pyoxynet is imported:

pip install --extra-index-url https://google-coral.github.io/py-repo/ tflite_runtime

Currently, The TFLite installation process is completed with a line command inside Python, which is not the best solution (I know...please get in touch if you know how to work around this). However, this is not a problem anymore after version 11.6 (TFLite is no longer adopted).

(back to top)

Usage

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):

VO2	VCO2	VE	PetO2	PetCO2	VEVO2	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:

VO2	VE	PetO2	Rf	VEVO2

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

import pyoxynet

# Load the TFL model
tfl_model = pyoxynet.load_tf_model()

# Make inference on a random input
test_tfl_model(tfl_model)

# Plot the inference on a test dataset
pyoxynet.test_pyoxynet()

For more examples, please refer to the package Documentation

(back to top)

Generation

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):

VO2	VCO2	VE	HR	RF	PetO2	PetCO2

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)

Flask-Pyoxynet inference app and API

A Flask inference/generation app called Flask-Pyoxynet has been deployed on a Amazon Lightsail private server. Currently, flask-pyoxynet runs on Lightsail containers service.

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://flask-service.ci6m7bo8luvmq.eu-central-1.cs.amazonlightsail.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://flask-service.ci6m7bo8luvmq.eu-central-1.cs.amazonlightsail.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 👈

Roadmap

• 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)

Contributing to the Oxynet project

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)

License

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

(back to top)

Contact

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

Repository project link: Pyoxynet

(back to top)

Additional reading

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)

Acknowledgments

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)

Disclaimer

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)