blood-analyzer-software

Table of contents

1. Overview
2. Setup
   • Clone repository
3. Folder structure
4. Features
5. User guide
6. Contributing
7. Contact us
8. License

Overview

Blood Analyzer Software (B.A.S.) is a data visualization and explorative tool, it allows to analyze blood samples from an hematological analyzer and reformat the data into a tabular format.

Setup

Blood Analyzer Software is a Python-based program. The Python language has an Installation page for Windows & Mac users.

Alternatively, you can install Python in your Linux-based machine with the following steps:

#Step 1: Open up your terminal by pressing Ctrl + Alt + T.
#Step 2: Update & Upgrade your local system's repository list by entering the following command
$ sudo apt update & apt upgrade
#Step 3: Download the latest version of Python
$ sudo apt install python3

Make sure you have the following packages installed in your Python environment:

• PyQt5 >= 5.9.0 (https://pypi.org/project/PyQt5/) (https://anaconda.org/anaconda/pyqt)
• matplotlib >= 3.5.0 (https://pypi.org/project/matplotlib/)
• pandas >= 1.5.0 (https://pypi.org/project/pandas/)
• numpy >= 1.23.0 (https://pypi.org/project/numpy/)
• Pillow >= 9.2.0 (https://pypi.org/project/Pillow/)
• xml (https://docs.python.org/3/library/xml.etree.elementtree.html)

Check with pip

pip list
pip install uninstalled_package

Check with conda

conda list
conda install uninstalled_package

Clone repository

Open Terminal or your IDE of preference within your 'projects' folder and take the following steps:

#Step 1: Get sources from GitHub
$ git clone https://github.com/jazg97/BloodAnalyzerSoftware.git
$ cd BloodAnalyzerSoftware
$ python3 feature_code.py

Folder structure

The project has the following structure:

.
│
├── data
│   ├── 20211027165438.xml
│   ├── 20221031134832.xml
│   │
├── docs
├── code
│   ├── cleaning_csv.py
│   ├── generating_plots.py
│   ├── GUI.py
│   ├── parsing_multiple_files.py
│   ├── parsing_xml.py
│   ├── utils.py
│   │
├── figures
│   ├── multiple_ids_feature_ex1.png
│   ├── multiple_ids_feature_ex2.png
├── exemplaryFiles
│   ├── exemplary_csv.csv
│   ├── exemplary_csv_w_meta.csv
│   ├── exemplary_meta.xlsx

Features

The Blood Analyzer Software (B.A.S.) is a data visualization and explorative tool, consequently most of its features are related to these tasks.

1. Generate csv files from xml files: Choose a directory that contains all the XML of interest and obtain a csv file with all its data reformatted.
2. Plot time-series by feature family, patients' ID and dates: Visualize time-series from ids of interest, see trends and compare subpopulations.
3. Import metadata: Add new data into the csv file which could further help in the analysis of the study.
4. Generate scatter plot with metadata fields
   1. Global plot: Obtain global statistics related to metadata of interest.
   2. Time-series: Visualize time-series from ids of interested located inside the metadata file.

User Guide

There are two options to access the program. You can run the program 'GUI.py' from the command line or open the executable. These are the main sections and features accesible in the program.

1) Export XML files

1. Appropiate format for XML files

When exporting a file from the Hematology Analyzer you need to fill out some fields in the machine in order to assign correctly important information for its analysis.

Some fields, such as Tier-ID, Name, and Haltername will be used to differentiate between samples, and as such its recommended to fill them out following some guidelines.

• Tier-ID: This will be the patient's ID and it's recommended to assign an integer number and not a combination of characters with numbers if not necessary.
• Name: This will be the type of blood source, such as systemic blood (BLOOD), bone marrow (BM), spleen (SPLEEN), femur (FEMUR), etc. It's important to maintain a consistent system of naming blood sources for their analysis.
• Haltername: This will be the 'owner' or head of laboratory in charge of the study and this field will be used to avoid mixing samples.

When generating a CSV file, these fields will have its correspondent name.

FIELD_SID_PATIENT_ID	FIELD_SID_ANIMAL_NAME	FIELD_SID_OWNER_LASTNAME	ANALYSIS_DATE	...
120	BLOOD	OWNER #1	dd-mm-YYYY	...
140	FEMUR	ONWER #2	dd-mm-YYYY	...
...	...	...	...	...

2) Start new analysis

1. Generate new `CSV` file without GUI

You can generate CSV files without launching B.A.S, follow these steps:

$ cd BloodAnalyzerSoftware
$ python3 ./code/generate_csv.py <input_data_directory> <output_directory>/<output_filename>.csv

2. Generate new csv file in GUI

You can open the GUI over the command line by carrying out the steps described below:

$ cd BloodAnalyzerSoftware
$ python3 ./code/GUI.py

Altenatively, you can just run the .exe. Either way, here are the steps you need to follow to create a new CSV file inside the GUI.

3) Access a dataset of interest

1. Open `CSV` file

Here's what you need to do to access the CSV file with the relevant dataset:

4) Explore and visualize data

1. Select and Filter Data

Once you have accessed a dataset, you can explore and visualize its data following these instructions.

2. Show Data

Example of time-series plot.

5) Add metadata

1. Recommended file format

You need to format your metadata as shown below and save it as a CSV or XSLX file.

animal_id	Genotype	Treatment	Date-of-interest	...
ID #1	Control+	Treat #1	dd-mm-YYYY	...
ID #2	Test-	Treat #2	dd-mm-YYYY	...
...	...	...	...	...

It is especially important to write the ID identically as it's in the original CSV file, as without this, it won't be associated correctly inside the program.

2. Upload metadata

You can load the metadata file into the dataset following accessing the Import Menu.

6) Generate scatter plot with metadata

1. Select metadata

Similar to ID and Family selection, you can select metadata of interest and choose between plotting global or time-series results of your experiment.

2. Show Global Results

Example of Global results.

3. Show Time-series Results

Example of Time-series Results

7) Export selected data

1. Export data

You can export a subset of a CSV file by selecting and filtering the dataset, similar to the steps done when generating a time-series plot.

8) Edit the canvas and its subplots

1. Modify canvas setings with Toolbar

Additionally, there is the option to modify most of the canvas settings with its Toolbar, which is located right above it. This toolbar have the following buttons:

• Subplot configuration button

  This button allows the user to modify the borders and spacings in between the subplots. You can also active the 'tight layout' mode which will automatically fit the data in the canvas.

  
• Edit axis, curve and image parameters button

  This button allows the modification of most of the parameters for a specific subplot. This means, you can modify its title, x-axis and y-axis, its coloring, the type of linestyle, and many more.

  
• Save button

  There is always the option to save the current figure, you just need to specify its name, save location and type of file.

  
• Zoom to rectangle button

  Define a rectangular region by dragging the mouse while holding the button. When using the left mouse button, the axes view limits will be zoomed to the defined region. When using the right mouse button, the axes view limits will be zoomed out.

  
• Pan/Zoom button

  This button has two modes: pan and zoom. Click the toolbar button to it, then put your mouse somewhere over an axis. Press the left mouse button and hold it to pan the figure, and press the right mouse button to zoom.
• Home/Forward/Back buttons

  These buttons are used to navigate between defined views. The Forward and Back button are use to navigate back and forth, and the Home Button always take you the first, feature view of your data.

9) Import XML files into current analysis

1. Import new xml files to current analysis

If some file was skipped during the CSV file generation, there is an option to add an specific XML file if necessary. You just need to follow the following steps:

Contributing

If you'd like to contribute to this project, please follow these steps:

1. Fork the repository
2. Create a new branch for your changes
3. Make your changes and commit them with descriptive commit messages
4. Push your changes to your fork
5. Create a pull request from your fork to the main repository

Contact Us

• Jose Zapana

• Eric Schmitt

License

Blood Analyzer Software is released under the MIT License - Jose Zapana & Eric Schmitt - 2023.