ORMIR-XCT

Michael T. Kuczynski, Nathan J. Neeteson, Kathryn S. Stok, Andrew J. Burghardt, Michelle A. Espinosa Hernandez, Jared Vicory, Justin J. Tse, Pholpat Durongbhan, Serena Bonaretti, Andy Kin On Wong, Steven K. Boyd, Sarah L. Manske. ORMIR_XCT: A Python package for high resolution peripheral quantitative computed tomography image processing. Journal of Open Source Software, 9(97), 6084, https://doi.org/10.21105/joss.06084, 2024.

Version: 1.1.0

• ORMIR-XCT is a Python package for processing high resolution peripheral computed tomography (HR-pQCT) scans.
• Development of this project began during the 2022 “Building the Jupyter Community in Musculoskeletal Imaging Research” workshop hosted by the Open and Reproducible Musculoskeletal Imaging Research (ORMIR) group.

Installation

Option A: Install into a new Anaconda environment:

For Windows, Linux, and Intel-based Mac:

Step 1: Install the ormir-xct Anaconda environment from the YAML file:

conda env create -f environment.yml

Step 2: Activate and use the ormir-xct environment:

conda activate ormir-xct

For Apple Silicon Mac (M-chips):

Step 1: Install the ormir-xct Anaconda environment, specifying macOS architecture:

CONDA_SUBDIR=osx-64 conda create -n ormir-xct python=3.11 pip

Step 2: Activate the ormir-xct environment:

conda activate ormir-xct

Step 3: Tell conda to always use the macOS architecture:

conda env config vars set CONDA_SUBDIR=osx-64

Step 4: Deactivate and reactivate the environment:

conda deactivate
conda activate ormir-xct

Step 5: Install the required dependencies using pip:

pip install -r requirements.txt

Option B: Install into an existing Anaconda environment:

Step 1: Activate your environment:

conda activate my_env

Step 2: Install ormir-xct from PyPi

pip install ormir-xct

Example Usage

Example Jupyter Notebooks demonstrating the major functionality of the ORMIR-XCT package are provided in the examples directory.

Command Line Applications

The ORMIR-XCT package now provides a command line interface for some workflows. To install the command line applications, activate your ormir-xct Anaconda environment and run: pip install -e . For detailed usage instructions, type the command followed by -h into the terminal.

Ways to Contribute

Reporting Bugs

• Bugs can be reported by creating a new GitHub issue in this repository. For each bug, please provide details on how to reproduce the bug and the specific error message (if possible).

Contributing Guidelines

• Install ormir-xct with development tools (e.g. black, ruff, pytest, hypothesis):
  1. Clone the repository
  2. Create an Anaconda environment as above
  3. Install development tools: pip install -e .[dev]
• To add a new feature, expand existing functionality, add documentation, or other contributions, please submit a new GitHub issue outlining your contribution in detail.
• When submitting a new pull request, ensure you outline what you have changed and why it is necessary to make this change.

Citation

When using the ORMIR-XCT package, please use the following citation:

• Kuczynski et al., (2024). ORMIR-XCT: A Python package for high resolution peripheral quantitative computed tomography image processing. Journal of Open Source Software, 9(97), 6084, https://doi.org/10.21105/joss.06084