bmmltools 0.2.8

BioMaterial Machine Learning tools (bmmltools), package to do machine learning with large binary 3d images

bmmltools

Current version 0.2.8

Last update 26/10/2022

PyPI: https://pypi.org/project/bmmltools/

Documentation: https://bmmltools.readthedocs.io/en/latest/

Author: Curcuraci L.

Contacts: [e-mail]

This is a python library for 3d binary image segmentation developed at Max-Plank-Institute fuer Kolloid-und Grenzflaechenforschung. This library contains a series of tools which can be useful to segment 3d binary images based on their structural/texture properties and extract information from the various regions identified,

Installation

To install bmmltools use the Anaconda propt. In the propt, copy the lines below

(base) > conda create -n new_env python=3.8
(base) > conda activate new_env
(new_env) > conda install pytables=3.6.1
(new_env) > conda install hdbscan
(new_env) > pip install bmmltools

Possible import errors:

If other packages are installed togheter with bmmltools, the following import error may appear some case:

1. hdbscan related import error: typically this error is related to the "cachedir" variable and happens as soon one imports the HDBSCAN() class. This is not an error of hdbscan, but it is related to the joblib package, which has been recently (september 2022) updated to the 1.2.0 version in which the "cachedir" variables has been renamed. The hdbscan module needs the version 1.10 of joblib to work without problems (maybe the 1.1.1 version is fine to), therefore if you experience an import error of this kind, check if joblib is present in the correct version. If is not, uninstall it and install the correct version. This import error should disappear.

Result visualization: bmmlboard

To inspect the intermediate results, a series of standard visualization tools has been developed. They are collected in the bmmlboard, a web-browser based a graphical interface made using streamlit, which can be used to visualize the intermediate results of bmmltools. To run the bmmlboard, write in the anaconda prompt

(base) > conda activate new_env
(new_env) > python -m bmmltools.run_bmmlboard

assuming that bmmltools is installed in the "new_env" environment.

Possible streamlit errors:

Sometimes streamlit does not work on some computer. This may not be a streamlit related issue, rather an issue related to the permit to write certain environmental variables on the computer during the installation process. Clearly one can solve this problem by reinstalling everything with suitable flags, but an simpler and effective solution can be the following:

1. Download on the computer the content of the folder board, which can be found in the folder src/bmmltools of this repository.

2. Run in the same python environment where the bmmltools has been installed the file home.py inside the downloaded folder with streamlit, namely write in an Anaconda prompt

(new_env) > conda activate new_env
(new_env) > cd [PATH TO THE board FOLDER]
(new_env) [PATH TO THE board FOLDER] > streamlit run home.py

Example usage

A series of example scripts are available in the 'example folder' of this repository. A detailed explanation of what they do can be founs in the "Miscellaneous" section of the bmmmltools documentation.