MotilA v1.1.0 Release Notes 🚀 Major Improvements: Installation, API Structure, CI, Code Coverage, Documentation, and Roadmap This release introduces several substantial improvements that modernize the installation workflow, strengthen the package structure, add full Read the Docs documentation, ensure consistent behavior across environments, notebooks, and CI testing, and formally introduce a project-level roadmap for future development. In addition, citation metadata has been consolidated. The previously included .zenodo.json file has been removed to avoid duplication and version mismatches. MotilA now uses CITATION.cff as the single authoritative source of citation information. Many of these enhancements were developed in direct response to the constructive feedback provided during the JOSS review process, which greatly strengthened the overall robustness of the software and significantly improved its readiness for sustainable open-source development. 📚 Full Read the Docs Documentation MotilA now includes a complete, structured documentation site: 🔗 https://motila.readthedocs.io The new documentation provides: A full Sphinx-based site with: automated API reference (autodoc, autosummary, napoleon, typehints) detailed descriptions of preprocessing steps (3D and 2D registration, spectral unmixing, histogram equalization and matching, filtering) input format expectations (TZCYX and TZYX) an expanded pipeline overview with figures structured tutorials and example datasets clear parameter explanations API references for all main and utility functions A dedicated Contributing section Cross-referenced pages and improved navigation These changes make MotilA's documentation maintainable and easy to extend. 🔧 API Improvements ✔️ Clean top-level API MotilA now exposes its main functions directly at package level: import motila as mt mt.process_stack(...) The top-level namespace includes: process_stack batch_process_stacks batch_collect hello_world tiff_axes_check_and_correct ✔️ Backward compatibility preserved The older import style remains functional: from motila import motila as mt 🧹 Internal Code Cleanup Removed all debugging code under if __name__ == '__main__': in production modules Removed all sys.path.append(...) development helpers Cleaned unused imports throughout scripts and notebooks Unified import patterns to: import motila as mt Updated in-code comments for clarity Updated example notebooks and scripts 🏷️ Citation Metadata Cleanup MotilA now standardizes its citation metadata by removing the obsolete .zenodo.json file. This file originated from an older DOI workflow and is no longer required. Maintaining two parallel metadata sources introduced the possibility of version inconsistencies. With this change, CITATION.cff is the sole source of truth for citation information, ensuring clarity and long-term maintainability. 📦 Installation & Environment Handling ✔️ Modernized installation instructions The README now uses current best practices: pip install motila pip install . pip install -e . pip install git+https://github.com/FabrizioMusacchio/MotilA.git Additions include: clearer environment recommendations explicit warnings about mixing install methods notes on correct kernel selection for notebooks simplified dependency setup ✔️ Example scripts updated All development-only sys.path.append statements commented out with explanation Scripts now run out-of-the-box after a standard installation 📂 Example Dataset Externalization The example dataset previously included inside the repository has been removed and is now hosted on Zenodo as a citable research object. Both the full dataset and a curated subset ("cutout") are available for independent download: Full dataset: Musacchio et al., 2025, DOI: 10.5281/zenodo.15061566 Subset ("cutout"): Musacchio, 2025, DOI: 10.5281/zenodo.17803977 Externalizing the data avoids accidental overwriting of example projects inside the repository, enables clean and reproducible workflows, and significantly reduces the size of the main MotilA installation. 🧪 CI Workflow Modernization The GitHub Actions workflow (python-tests.yml) has been updated to match real-world user workflows: creates a clean conda environment installs MotilA via pip install . installs pytest and coverage tools runs the test suite and uploads coverage This ensures consistent behavior across systems. 📊 Test Coverage Integration MotilA now includes full test coverage reporting integrated directly into the development workflow. The test suite is executed with pytest-cov, generating standardized coverage reports. GitHub Actions automatically upload coverage reports to Codecov on every push and pull request. A Codecov badge in the README provides immediate visibility into current test coverage. Coverage includes core functionality such as subvolume extraction, optional registration, spectral unmixing, segmentation, change detection, and Zarr-based chunked processing. This integration enhances transparency, supports reproducibility, and improves long-term maintainability of the pipeline. 🧭 Contribution and Community Guidelines MotilA now includes: CONTRIBUTING.md, covering: environment setup branching and workflow pull request guidelines commit conventions issue reporting CODE_OF_CONDUCT.md, based on the Contributor Covenant Both documents integrated into the Read the Docs site These additions support healthy, sustainable project development. 🗺️ Roadmap Implementation MotilA now includes a project-level roadmap (ROADMAP.md) that outlines planned future enhancements and long-term development priorities. The roadmap documents upcoming changes such as dedicated TYX support, transition of tabular outputs from .xls to .csv or .yml, standardization of naming conventions for cross-platform compatibility, restructuring of example scripts, and further expansions to the documentation. This file provides a transparent reference for users and contributors and supports structured, forward-looking development. 🧹 Additional Documentation Refinements Expanded "Example Usage" with parameter explanations Added example parameter blocks from tutorial scripts Added screenshot of Zenodo dataset structure Ensured consistent and accessible reStructuredText formatting Improved cross-referencing throughout the documentation Summary MotilA v1.1.0 focuses on strengthening: installation consistency API clarity documentation quality development workflow CI reliability code cleanliness forward-oriented planning through an explicitly documented roadmap The release also consolidates citation metadata by removing the outdated .zenodo.json file and designating CITATION.cff as the central and only citation reference. The integration of automated test coverage and public reporting additionally reinforces MotilA's robustness by making testing completeness visible and traceable to users and contributors. These improvements significantly enhance the usability, maintainability, and long-term stability of MotilA. If you encounter any issues or have suggestions, please open an issue on GitHub. We thank the JOSS reviewers for their constructive feedback, which helped guide several of the improvements included in this release. Thank you for using MotilA!

If you use MotilA in your research, please cite it as below.