clinops: A Python Toolkit for Clinical ML Data Pipelines

[chaitanyakasaraneni]

Submitting Author: Chaitanya Kasaraneni (@chaitanyakasaraneni)
Package Name: clinops
One-Line Description of Package: Production-grade Python toolkit for clinical ML data pipelines — patient-safe splitting, physiological outlier clipping, unit normalization, and ICD harmonization for MIMIC-IV and FHIR R4
Repository Link (if existing): https://github.com/chaitanyakasaraneni/clinops
EiC: TBD

---

Code of Conduct & Commitment to Maintain Package

• I agree to abide by pyOpenSci's Code of Conduct during the review process and in maintaining my package after should it be accepted.
• I have read and will commit to package maintenance after the review as per the pyOpenSci Policies Guidelines.

Description

• Include a brief paragraph describing what your package does:

clinops is a Python library providing validated, reusable abstractions for the data engineering steps that precede model training in clinical ML workflows. It directly addresses four failure modes endemic to healthcare AI pipelines: patient leakage in train/test splits (the most common source of inflated performance metrics in published ICU prediction models), unit heterogeneity in multi-site data (e.g., glucose in mg/dL vs. mmol/L), ICD-9 to ICD-10 version discontinuities introduced by the October 2015 US coding transition, and physiological outliers that standard statistical methods misclassify as noise. The library ships with four modules — clinops.ingest (MIMIC-IV, FHIR R4, and flat file loaders), clinops.preprocess (outlier clipping, unit normalization, ICD mapping), clinops.temporal (gap-aware sliding windows, lag features, cohort alignment, fit/transform imputation), and clinops.split (temporal, patient-level, and stratified patient splitting) — and is fully tested (118 tests, 85% coverage) with a scikit-learn-compatible API.

Community Partnerships

We partner with communities to support peer review with an additional layer of
checks that satisfy community requirements. If your package fits into an
existing community please check below:

• Astropy: My package adheres to Astropy community standards
• Pangeo: My package adheres to the Pangeo standards listed in the pyOpenSci peer review guidebook

Scope

• Please indicate which category or categories this package falls under:

  • Data retrieval
  • Data extraction
  • Data processing/munging
  • Data deposition
  • Data validation and testing
  • Data visualization
  • Workflow automation
  • Citation management and bibliometrics
  • Scientific software wrappers
  • Database interoperability

Domain Specific

• Geospatial
• Education

---

• Explain how and why the package falls under these categories (briefly, 1-2 sentences). For community partnerships, check also their specific guidelines as documented in the links above. Please note any areas you are unsure of:

clinops falls under data retrieval (structured loaders for MIMIC-IV and FHIR R4), data extraction (temporal windowing and lag feature generation from clinical event streams), data processing/munging (unit normalization, ICD harmonization, outlier clipping), and data validation and testing (physiological bound enforcement and schema validation on load). It is domain-specific to clinical/EHR data but does not fit the Geospatial or Education community partnership categories.

• Who is the target audience and what are the scientific applications of this package?
  The primary audience is clinical ML researchers and healthcare data engineers who build predictive models on electronic health record data — particularly MIMIC-IV, PhysioNet datasets, and institutional EHR exports. Scientific applications include ICU outcome prediction (mortality, length of stay, organ failure), cohort construction for clinical studies, and pipelines that ingest heterogeneous, multi-site EHR data. The library is also relevant to engineers building production ML pipelines in healthcare settings where data quality and leakage prevention are regulatory requirements.

• Are there other Python packages that accomplish similar things? If so, how does yours differ?
  No existing Python package addresses the full combination of problems clinops targets. The closest adjacent tools are:

  • pandas / scikit-learn — general-purpose; do not know about physiological bounds, patient-level splitting, ICD codes, or clinical unit conversions
  • MIMIC-Extract — extracts features from MIMIC-III specifically; not designed as a reusable library, not maintained for MIMIC-IV, no splitting or preprocessing abstractions
  • medcat / spaCy clinical models — NLP-focused; operate on clinical text rather than structured EHR tables
  • lifelines — survival analysis; does not address data ingestion, splitting, or preprocessing

clinops is the first library to package the specific set of clinical data engineering safeguards (patient-safe splitting, physiological outlier bounds, unit normalization, ICD harmonization) together in a scikit-learn-compatible API designed for reuse across projects.

• Any other questions or issues we should be aware of:
  JOSS opt-in: I would like to opt into the pyOpenSci–JOSS partnership. A paper.md following JOSS requirements is already in the repository. I previously submitted directly to JOSS (issue #10111) and was rejected at pre-review solely for insufficient public development history (the repository was 2 days old at submission). I understand PyOpenSci does not have this requirement, and that PyOpenSci acceptance routes to JOSS without a second review.

P.S. Have feedback/comments about our review process? Leave a comment here

[crhea93]

Hi @chaitanyakasaraneni Thank you for your submission! Before moving to the next stage, I'm hoping you can answer a few questions for us.
First, I'd like to know when this code was developed and where it was stored previously. I note in the commit history that the project was initialized 3 days ago with the majority of the code added in the second commit.

[chaitanyakasaraneni]

Hey @crhea93 ! Thank you for looking at this!

The code was developed iteratively over the past several weeks as a generalization of patterns I have used across multiple production clinical ML projects at my work, where I build bioinformatics data pipelines that process genomic and clinical data.

The library was developed locally and then published to GitHub and PyPI on February 22, 2026. There is no prior public repository — this was a deliberate decision to package recurring internal patterns as a standalone open-source library rather than extracting them from proprietary codebases.

The large second commit reflects the initial public release of code that had been written locally before the repository was created. I understand this is a known pattern that raises questions about development history, and I want to be transparent about it.

Please let me know if you have any other questions before deciding whether to proceed.

[crhea93]

@chaitanyakasaraneni Thank you for the explanation. Yes, this is a pattern common in vibe-coded work; but, your comment clearly explains the case :) I'm happy to continue with this.

[chaitanyakasaraneni]

@crhea93 - just checking on the next steps

[crhea93]

@chaitanyakasaraneni Thank you very much for pinging me here again on this! I will run the full editor in chief checks tonight and start looking for an editor.

[crhea93]

Editor in Chief checks

Hi there! Thank you for submitting your package for pyOpenSci
review. Below are the basic checks that your package needs to pass
to begin our review. If some of these are missing, we will ask you
to work on them before the review process begins.

Please check our Python packaging guide for more information on the elements
below.

• Installation The package can be installed from a community repository such as PyPI (preferred), and/or a community channel on conda (for example, conda-forge, bioconda).
  • The package imports properly into a standard Python environment import package.
• Fit The package meets criteria for fit and overlap.
• Documentation The package has sufficient online documentation to allow us to evaluate the package's function and scope without installing the package. This includes:
  • User-facing documentation that overviews how to install and start using the package.
  • Short, quickstart tutorials that help a user understand how to use the package and what it can do for them.
  • API documentation (documentation for your code's functions, classes, methods, and attributes): this includes clearly written docstrings with variables defined using a standard docstring format.
• Core GitHub repository Files
  • README The package has a README.md file with a clear explanation of what the package does, instructions on how to install it, and a link to development instructions.
  • Contributing File The package has a CONTRIBUTING.md file that details how to install and contribute to the package.
  • Code of Conduct The package has a CODE_OF_CONDUCT.md file.
  • License The package has an OSI approved license.
    NOTE: We prefer that you have development instructions in your documentation too.
• Issue Submission Documentation All of the information is filled out in the YAML header of the issue (located at the top of the issue template).
• Automated tests Package has a testing suite and is tested via a Continuous Integration service.
• Repository The repository link resolves correctly.
• Package overlap The package doesn't entirely overlap with the functionality of other packages that have already been submitted to pyOpenSci.
• Archive (JOSS only, may be post-review): The repository DOI resolves correctly.
• Version (JOSS only, may be post-review): Does the release version given match the GitHub release (v1.0.0)?
• The package authors have disclosed the use of Generative AI tools in the development and/or maintenance of their package.

Optional but recommended:

• Linting The package uses automated linting (e.g., ruff) to enforce code style and quality standards, ideally integrated with CI.
• Type checking The package includes type hints and uses a type checker (e.g., mypy) to catch type-related issues, ideally integrated with CI.
• Modern tooling The package uses modern Python development tools (e.g., uv for dependency management) and Hatch for building publishing and running development tasks to streamline development workflows. See the pyOpenSci packaging guide for more on modern packaging tools.

Optional: Let projects know that it's a great idea for projects to have a .github repository for the project organization where they can host a commonly used LICENSE, Code of Conduct, and even a YAML file with label definitions. These items will then be automatically applied to every repository in the organization to ensure consistency (but can be customized within repos too). The SunPy project has a great example of this.

---

• Initial onboarding survey was filled out
  We appreciate each maintainer of the package filling out this survey individually. 🙌
  A big thank you in advance to authors for setting aside five to ten minutes to do this. It truly helps our organization! 🙌

---

---

Editor comments

This submission is in a very good place! However, there is one thing that I think is missing before we can start a proper review. There doesn't appear to be complete documentation replit with walk-through examples. I notice that there is a docs folder with several markdown files. These are good, but it is missing a nice walk through example. Also, this does not appear to be hosted online (I could be wrong but I didn't see any link in the repo). I suggest using something like sphinx (https://www.sphinx-doc.org/en/master/development/html_themes/templating.html) and ReadTheDocs (https://about.readthedocs.com/).

[chaitanyakasaraneni]

Hey @crhea93!
Reading through your comments, I noticed you mentioned that the docs aren't hosted online. Here's the link: https://clinops.readthedocs.io/en/latest/