docs

Author: sprivite

.github/workflows/mkdocs.yml

@@ -0,0 +1,52 @@
+name: Deploy Documentation
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: "3.12" # install the python version needed
+      - name: install deps
+        run: |
+          apt-get update && apt-get install -y wget gcc
+          pip install -r requirements.txt
+      - name: build docs
+        run: |
+          PYTHONPATH=. mkdocs build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: page
+          path: site
+          if-no-files-found: error
+
+  deploy:
+    runs-on: ubuntu-latest
+    needs: build
+    environment:
+      name: github-pages
+      url: ${{steps.deployment.outputs.page_url}}
+
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: page
+          path: .
+      - uses: actions/configure-pages@v1
+      - uses: actions/upload-pages-artifact@v2
+        with:
+          path: .
+      - id: deployment
+        uses: actions/deploy-pages@v3

.github/workflows/pypi.yml

@@ -0,0 +1,35 @@
+name: Release
+
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+on:
+  release:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+
+jobs:
+  pypi-publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/phenex
+    permissions:
+      id-token: write # IMPORTANT: this permission is mandatory for trusted publishing
+    steps:
+      - name: Checkout Repository 🛎️
+        uses: actions/checkout@v3
+      - name: Install Python 3.9 🐍
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.9"
+      - name: Clean old build artifacts
+        run: rm -rf dist/*
+      - name: Build deps
+        run: python3 -m pip install -r requirements.txt && pip install wheel
+      - name: Build artifacts
+        run: python setup.py sdist bdist_wheel
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

.github/workflows/pytest.yml

@@ -0,0 +1,19 @@
+name: Run unit tests
+
+on: push
+
+jobs:
+  run_test_pipeline:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v3
+      - name: install python 3.12
+        uses: actions/setup-python@v3
+        with:
+          python-version: "3.12"
+          cache: "pip"
+      - name: install requirements
+        run: pip install -r requirements.txt
+      - name: run tests
+        run: PYTHONPATH=. pytest

.gitignore

@@ -0,0 +1,22 @@
+__pycache__/
+*pyc
+*ipynb
+site/
+build/
+dist/
+*.egg-info
+*.bbl
+*.aux
+*.log
+*.blg
+.DS_Store
+notebooks/*
+mlruns/*
+site/*
+.devcontainer/*
+.idea
+.idea/*
+venv/*
+kubernetes
+kubernetes/*
+kubernetes/deployment.yml

.nojekyll

@@ -0,0 +1,2 @@
+* @sprivite
+* @a-hartens

CODEOWNERS

@@ -0,0 +1,48 @@
+# How to contribute
+
+You can contribute to this project in two ways:
+
+1.  **Reporting bugs** and **suggesting enhancements** by opening an issue.
+2.  **Contributing to the codebase** by opening a pull request.
+
+## Reporting bugs and suggesting enhancements
+
+To report a bug or suggest an enhancement, open an issue on the [Issues]. If
+reporting a bug, please provide a detailed description of the problem, including
+the steps to reproduce it. If suggesting an enhancement, please provide a clear
+description of the proposed change, including the use case for the change.
+
+## Contributing to the codebase
+
+To contribute to the codebase, open a pull request on the [Pull Requests](https://github.com/Bayer-Group/phenx/pulls).
+
+All pull requests must be approved by at least one reviewer. If there is a
+dispute regarding a pull request, a second reviewer will be asked to review the
+pull request and make the final decision.
+
+A pull request can and should be rejected if any of the following apply:
+
+- Existing tests have not been run and passed
+- The code does not follow the project's coding conventions
+- New functionality has not been documented
+- Tests for new functionality have not been written
+- The pull request is too large
+- The pull request addresses more than one issue
+- The pull request breaks code that was previously working
+
+It is the responsibility of the contributor to ensure that the pull request meets
+all these conditions. If the pull request is rejected, the contributor should
+address the issues raised and open a new pull request.
+
+## Coding conventions
+
+Unless specified otherwise here, the codebase follows the [PEP 8](https://peps.python.org/pep-0008/)
+style guide for Python code.
+
+We use snake_case for variable, function and method names, and CamelCase for
+class names. Method names should be descriptive and generally start with a verb.
+Methods should be private unless there is good reason for them to be public. A
+higher standard is expected for documentation of public methods, since these
+directly face the user, and changes to public methods require higher level of
+scrutiny. But this does not mean that private methods should be undocumented if
+they provide crucial functionality.

CONTRIBUTING.md

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2024, Bayer AG.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+- Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+- Redistributions in binary form must reproduce the above copyright notice, this
+  list of conditions and the following disclaimer in the documentation and/or
+  other materials provided with the distribution.
+
+- Neither the name of the copyright holder nor the names of its contributors may
+  be used to endorse or promote products derived from this software without
+  specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

LICENSE

@@ -1 +1,52 @@
-# PhenEx
+# PhenEx: Automatic PHENotype EXtractor
+
+<a href="https://github.com/Bayer-Group/phenx">
+  <div style="text-align: center;">
+    <img src="phenx.png" alt="PhenEx Logo" width="500" />
+  </div>
+</a>
+
+## What is PhenEx?
+
+PhenEx -- pronouned "Phoenix" -- is a cutting-edge cohort builder designed to simplify the extraction of analysis-ready datasets from raw real-world data as part of observational study execution. Using a meta-language closely aligned to plain English, PhenEx allows you to define and calculate index dates, inclusion and exclusion criteria, baseline characteristics, and outcome event tables based on arbitrarily complex criteria.
+
+Questions you can answer using PhenEx include, but are not limited to:
+
+- What is the incidence of diabetes among patients aged 50-70?
+- How many patients with a history of stroke have also had a diagnosis of atrial fibrillation and prescribed anticoagulants?
+- What are the common comorbidities observed in patients with hypertension?
+- How do medication adherence rates compare between different patient demographics?
+  0 What proportion of patients who have been diagnosed with breast cancer receive genetic testing for BRCA1 and BRCA2 mutations?
+- Among patients treated for acute myocardial infarction (AMI), how many have been re-admitted to the hospital within six months for heart-related issues?
+  What is the incidence of diabetes among patients aged 50-70?
+- How many patients with a diagnosis of rheumatoid arthritis have been prescribed at least three different disease-modifying antirheumatic drugs (DMARDs) over their treatment history?
+
+## Who is PhenEx for?
+
+PhenEx is for anyone seeking to analyze real-world patient data, such as claims, electronic health records or disease registries.
+
+- **Pharmaceutical and Biotech Companies**: Accelerate drug development and market access strategies. PhenEx helps you identify patient populations for clinical trials, analyze real-world treatment patterns, and assess the safety and efficacy of new therapies.
+- **Epidemiologists and Public Health Professionals**: Conduct comprehensive epidemiological studies and public health surveillance. PhenEx enables you to define and extract complex phenotypes, track health outcomes, and respond to public health challenges effectively.
+- **Data Scientists and Analysts**: Simplify the process of data extraction and cohort building. PhenEx provides powerful tools to transform raw data into structured, analysis-ready datasets, enabling you to focus on generating actionable insights.
+
+## Why should I use PhenEx?
+
+1. PhenEx is **free, open-source and interoperable** with a large number of data warehouse backends. Regardless of where you host your data, you can use PhenEx to extract cohorts from it.
+
+2. PhenEx is **data format agnostic**. Whether your data is in the OMOP Common Data Model or something else, PhenEx can handle it with only minimal compatibility transformations. The most common data formats are already built-in and understood by PhenEx.
+
+3. PhenEx supports **complex phenotypes**. PhenEx covers not only basic use cases but also handles arbitrarily complex phenotypes (e.g. ISTH major bleeding, CHADSVASc). With PhenEx, you can define and extract intricate phenotypes, empowering you to tackle a wide range of research questions.
+
+4. PhenEx is **extensible**. If your phenotype is not covered by the existing classes, you can easily create your own implementation using the provided abstract base classes. If you encounter a common pattern that is missing, simply open an issue, and we'll be delighted to consider it for inclusion in the core packages.
+
+5. PhenEx is **scalable**. Whether you have a simple feasibility analysis or a full-blown research protocol with 20 inclusion criteria and 100 baseline characteristics, PhenEx can build your cohort.
+
+## What is PhenEx _not_?
+
+- PhenEx does not clean your data. Garbage-in-garbage-out, so please invest time in cleaning your data before attempting to perform observational research using it.
+
+- PhenEx does not perform outcome analysis, e.g., Kaplan-Meier estimation or Cox regressions. PhenEx only prepares the analysis dataset for downstream analysis. For outcome analysis in Python, the [lifelines](https://lifelines.readthedocs.io/en/latest/) package is a good place to start; in R, the [surv](https://cran.r-project.org/web/packages/survival/index.html) package is fairly popular.
+
+## I'm convinced! How can I get started?
+
+Head on over to the [Official PhenEx Documentation](https://bayer-group.github.io/PhenEx). If you have any questions, please feel free to reach out to any of the developers and we'll be happy to get you on your way.