Almirah

almirah aids in the organization, maintenance, and usage of both file-based and table-based datasets. Developed to handle neuroimaging datasets, it provides data format conversion support for specific modalities.

Out-of-the-box, almirah supports:

  • BIDS specification for neuroimaging datasets.

  • BIDS-like specification for genome sequence data.

  • Interfacing with databases supported by SQLAlchemy.

  • File format conversion for neuorimaging data.

  • Lazy access of DataLad compatible datasets.

With some time on config writing, almirah can:

  • Organize unformatted datasets.

  • Query and filter across the dataset.

  • Migrate records from one database to another.

Installing

almirah can be installed with pip:

$ python -m pip install almirah

Alternatively, you can grab the latest source code from Github:

$ git clone https://github.com/bhallalab/almirah.git
$ cd almirah
$ pip install .

Usage

The User Guide is the place to go to learn how to use the libray and accomplish common dataset related tasks. If you have the time, we recommend following the Tutorial for a complete overview.

almirah relies heavily on configs to guide its tasks. The Writing configs page describes the possibilities in detail.

The API Reference documentation provides API-level documentation.

Can you use almirah to manage other datasets? Of course! Have a look at the Translate to another dataset section for files to tweak to achieve this.

If you want to access the CALM-Brain resource, please head over to the user guide for a walk-through. The reference documentation provides details on the files and records available in the dataset. If you have not heard of the resource, but would like to know, please visit the CALM-Brain online page help acquaint you.

Who uses almirah?

almirah was primarily developed to support and maintain the data generated by the CBM-ADBS study. But we believe it can aid with other datasets too! Even non-neuroimaging ones!

If almirah was able to help with your dataset, we would love to hear about it.

Translate to another dataset

If your dataset is a BIDS dataset, congrats you are done! 🎉

The BIDS specification config is available in the repo and you can use it.

If your dataset follows a different specification, describe it as a config file by referring to Specification details. This should allow filtering and querying of the dataset.

If you would like to organize data according to a described specification, define rules according to Organization rules.

If you need assistance migrating records from one database to another, or one schema to another, Database mapping can guide you.

If you need help writing a config file or would like to suggest an improvement, please do reach out via the repo.

Dependencies

almirah provides out-of-the-box routines for format conversion in neuroimaging datasets. These are implemented as wrappers around other standard libraries in different languages. These libraries might have dependencies that are not resolved during almirah installation. The pipelines and their respective externally installed dependencies are:

Important

Though not mentioned explicitly, it is implied that it is necessary to have the language the library is implemented in installed. For example, SPM requires MATLAB.

License

almirah is made available under the MIT License. For more details, see LICENSE.

Contributing

We happily welcome contributions, please see Contributing for details.

Help and Support

We try to make almirah robust, but there might be things we missed. If it does not meet your use case or you have trouble adapting it to your dataset, please write to us or open an issue on the repository or drop by Github Discussions.

Citing

If you use almirah to help with your dataset, please consider citing this repository until a journal article is specifically available for almirah.

Acknowledgements

almirah builds on other libraries and some parts are implemented as a wrapper around modules in these libraries. Thanks to the developers, maintainers, and contributors of these for the amazing documentation and great work!

  • mne

  • mne-bids

  • mne-nirs

  • dcm2bids

  • pybids

  • SQLAlchemy

References

  • Alexandre Gramfort, Martin Luessi, Eric Larson, Denis A. Engemann, Daniel Strohmeier, Christian Brodbeck, Roman Goj, Mainak Jas, Teon Brooks, Lauri Parkkonen, and Matti S. Hämäläinen. MEG and EEG data analysis with MNE-Python. Frontiers in Neuroscience, 7(267):1–13, 2013. doi: https://doi.org/10.3389/fnins.2013.00267.

  • Appelhoff, S., Sanderson, M., Brooks, T., Vliet, M., Quentin, R., Holdgraf, C., Chaumon, M., Mikulan, E., Tavabi, K., Höchenberger, R., Welke, D., Brunner, C., Rockhill, A., Larson, E., Gramfort, A., & Jas, M. (2019). MNE-BIDS: Organizing electrophysiological data into the BIDS format and facilitating their analysis. Journal of Open Source Software, 4:1896. doi: https://doi.org/10.21105/joss.01896.

  • Robert Luke, Eric D. Larson, Maureen J. Shader, Hamish Innes-Brown, Lindsey Van Yper, Adrian K. C. Lee, Paul F. Sowman, David McAlpine. Analysis methods for measuring passive auditory fNIRS responses generated by a block-design paradigm. Neurophotonics, Vol. 8, Issue 2, 025008 (May 2021). doi: https://doi.org/10.1117/1.NPh.8.2.025008.

  • Boré, A., Guay, S., Bedetti, C., Meisler, S., & GuenTher, N. (2023). Dcm2Bids (Version 3.0.2) [Computer software]. doi: https://doi.org/10.5281/zenodo.8306314.

  • Yarkoni et al., (2019). PyBIDS: Python tools for BIDS datasets. Journal of Open Source Software, 4(40), 1294. doi: https://doi.org/10.21105/joss.01294.

  • Michael Bayer. SQLAlchemy. In Amy Brown and Greg Wilson, editors, The Architecture of Open Source Applications Volume II: Structure, Scale, and a Few More Fearless Hacks 2012 http://aosabook.org.