py2lispIDyOM: A Python package for IDyOM

py2lispIDyOM is an open-source Python package that serves as a unifying Python interface that simplifies and streamlines the research workflow for running the information dynamics of music IDyOM model and analyzing output data. It is broadly aimed at researchers conducting IDyOM-based analysis in Python.

Table of Content

• Getting Started

  • Prerequisites
  • Installing

• Functionality and Usage

  • Notebook examples

• Citation, Contributions and Acknowledgments

  • Citation
  • Authors contributions
  • Contribution guidelines
  • Acknowledgments

---

Getting Started

1. Prerequisites: Installing IDyOM

py2lispIDyOM requires IDyOM to be installed on the local machine. To start with, please read the IDyOM installation page to appropriately install IDyOM.

We also provided a script to automate the IDyOM installation process (for macOS). Some steps to follow:

• Download this folder: install_idyom.
• In the terminal,
  • cd to the path the folder "install_idyom/" has been downloaded. For example, cd Downloads/install_idyom/
  • Type bash install_idyom.sh. You will be prompted to provide
    • your Password, and
    • to follow the subsequent request Press Enter to continue.

2. Installing py2lispIDyOM

The code is compatible with >= Python 3.9.

It can be installed using pip or directly from the source code. Basic installation options include:

• From PyPI using pip: pip install py2lispIDyOM
• Download or gitclone this repository

Functionality and Usage

In summary, py2lispIDyOM has three main functionalities for research workflow:

• Running the IDyOM
• Data preprocessing
• Visualizing IDyOM outputs

Please have a look at the tutorials, which guides you through all three basic functionalities of through examples.

Notebook examples

• Running the IDyOM model: 1_running_IDyOM_tutorial.ipynb
• Data preprocessing:
  • Extracting data: 2a_data_preprocessing_extracting.ipynb
  • Exporting data: 2b_data_preprocessing_exporting.ipynb
• Visualization: 3_visualizing_outputs.ipynb

Citation, Contributions and Acknowledgments

Citation

Guan et al., (2022). py2lispIDyOM: A Python package for the information dynamics of music (IDyOM) model. Journal of Open Source Software, 7(79), 4738, https://doi.org/10.21105/joss.04738

@article{Guan2022, doi = {10.21105/joss.04738}, url = {https://doi.org/10.21105/joss.04738}, year = {2022}, publisher = {The Open Journal}, volume = {7}, number = {79}, pages = {4738}, author = {Xinyi Guan and Zeng Ren and Claire Pelofi}, title = {py2lispIDyOM: A Python package for the information dynamics of music (IDyOM) model}, journal = {Journal of Open Source Software} }

Contribution guidelines

We tried to make the code accessible and provide some examples in the tutorials for getting started smoothly. But there is still lots of room for better documentation, tutorials and testing. Please contact us if you have any questions or encounter bugs.

You are also welcome to contribute to this project. There are just a few small guidelines you need to follow.

Authors contributions

All authors provided critical feedback on the design of this project, and participated in the writing and editing of the manuscript. X.G. and C.P. conceptualized the project. X.G. and Z.R. planned the code architecture. X.G. carried out the overall computational implementation. C.P. supervised the overall project.

Acknowledgments

We thank Guilhem Marion for his initial contribution in the idea and code that constituted the basis for the development of this software.

We also thank the reviewer Alexander Hayes for providing useful comments on automating the installation steps of IDyOM.