Skip to content

Commit fcf213b

Browse files
TheCedarPrinceTheCedarPrince
authored
Merge pull request #7 from JuliaHealth/add/docs
[DOCS] Documentation for the package!
2 parents 1359c60 + 95a6622 commit fcf213b

File tree

7 files changed

+334
-13
lines changed

7 files changed

+334
-13
lines changed

‎docs/Project.toml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,11 @@
11
[deps]
22
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
3+
DocumenterTools = "35a29f4d-8980-5a13-9543-d66fff28ecb8"
4+
LiveServer = "16fef848-5104-11e9-1b77-fb7a48bbb589"
35
OMOPCDMFeasibility = "d7c4b303-36e6-42c5-a114-1784c141c4f7"
6+
7+
[compat]
8+
Documenter = "1"
9+
DocumenterTools = "0.1.20"
10+
LiveServer = "1.5"
11+
julia = "1.10"

‎docs/make.jl‎

Lines changed: 14 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,14 +7,25 @@ DocMeta.setdocmeta!(
77

88
makedocs(;
99
modules=[OMOPCDMFeasibility],
10+
checkdocs = :none,
1011
authors="Kosuri Lakshmi Indu <[email protected]> and contributors",
12+
repo = "https://github.com/JuliaHealth/OMOPCDMFeasibility.jl/blob/{commit}{path}#{line}",
1113
sitename="OMOPCDMFeasibility.jl",
1214
format=Documenter.HTML(;
15+
prettyurls = get(ENV, "CI", "false") == "true",
1316
canonical="https://JuliaHealth.github.io/OMOPCDMFeasibility.jl",
14-
edit_link="master",
1517
assets=String[],
1618
),
17-
pages=["Home" => "index.md"],
19+
pages=[
20+
"Home" => "index.md",
21+
"Quickstart" => "quickstart.md",
22+
23+
"Pre-Cohort Analysis" => "precohort.md",
24+
"Post-Cohort Analysis" => "postcohort.md",
25+
26+
"API" => "api.md",
27+
],
28+
doctest = false,
1829
)
1930

20-
deploydocs(; repo="github.com/JuliaHealth/OMOPCDMFeasibility.jl", devbranch="master")
31+
deploydocs(; repo="github.com/JuliaHealth/OMOPCDMFeasibility.jl")

‎docs/src/api.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
```@meta
2+
CurrentModule = OMOPCDMFeasibility
3+
```
4+
5+
# OMOPCDMFeasibility
6+
7+
Documentation for [OMOPCDMFeasibility](https://github.com/JuliaHealth/OMOPCDMFeasibility.jl).
8+
9+
```@index
10+
11+
```
12+
13+
```@autodocs
14+
Modules = [OMOPCDMFeasibility]
15+
```

‎docs/src/index.md‎

Lines changed: 20 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,24 @@
1-
```@meta
2-
CurrentModule = OMOPCDMFeasibility
3-
```
1+
# OMOPCDMFeasibility.jl
42

5-
# OMOPCDMFeasibility
3+
> A Julia package for feasibility and cohort analysis on OMOP Common Data Model (CDM) data.
64
7-
Documentation for [OMOPCDMFeasibility](https://github.com/JuliaHealth/OMOPCDMFeasibility.jl).
5+
## Overview
86

9-
```@index
10-
```
7+
OMOPCDMFeasibility.jl helps researchers and data scientists quickly explore, summarize, and compare patient cohorts using OMOP CDM databases. It is designed for use in observational health studies, cohort discovery, and data quality assessment.
118

12-
```@autodocs
13-
Modules = [OMOPCDMFeasibility]
14-
```
9+
## Features
10+
11+
- **Pre-cohort analysis:** Explore concept distributions, domain breakdowns, and data quality before defining a cohort.
12+
- **Post-cohort analysis:** Summarize, profile, and compare cohorts after extraction.
13+
- **Flexible database support:** Works with DuckDB, SQLite, PostgreSQL, and more.
14+
- **Composable with JuliaHealth:** Integrates with DataFrames.jl, OMOPCommonDataModel.jl, and other JuliaHealth tools.
15+
- **Reproducible workflows:** Designed for robust, testable, and transparent research.
16+
- **Clear error handling:** Provides informative messages and input validation.
17+
18+
## Limitations
19+
20+
- OMOPCDMFeasibility.jl is focused on feasibility and cohort analysis only; it does not perform cohort extraction or patient-level prediction itself.
21+
- Some advanced features (e.g., custom covariates, non-standard dialects) may require additional JuliaHealth packages or extensions.
22+
- The package assumes your data is already in OMOP CDM format and accessible via a supported database backend.
23+
24+
For a step-by-step guide, see the [Quickstart](quickstart.md). For detailed workflows and function documentation, explore the other sections in this documentation.

‎docs/src/postcohort.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# Post-Cohort Analysis
2+
3+
**What is Post-Cohort Analysis?**
4+
5+
Post-cohort analysis is the process of exploring and summarizing your study population after you have defined your cohort. It helps you answer questions like: Who is in my cohort? What are their characteristics? How do they compare to the rest of the database?
6+
7+
This step is essential for understanding your results, checking for biases, and making your study reproducible and transparent.
8+
9+
Post-cohort analysis in OMOPCDMFeasibility.jl is designed to be simple and clear, even for beginners.
10+
11+
## 1. `create_individual_profiles`
12+
13+
```@docs
14+
OMOPCDMFeasibility.create_individual_profiles
15+
```
16+
17+
## 2. `create_cartesian_profiles`
18+
19+
```@docs
20+
OMOPCDMFeasibility.create_cartesian_profiles
21+
```
22+
23+
## Example: Post-Cohort Analysis in Practice
24+
25+
```julia
26+
using DataFrames, DuckDB, DBInterface, Dates
27+
using OMOPCDMFeasibility
28+
using OMOPCDMCohortCreator:
29+
GenerateDatabaseDetails,
30+
GenerateTables,
31+
GetPatientGender,
32+
GetPatientAgeGroup,
33+
GetPatientRace,
34+
GetPatientEthnicity,
35+
ConditionFilterPersonIDs
36+
37+
conn = DBInterface.connect(DuckDB.DB, "synthea_1M_3YR.duckdb")
38+
39+
GenerateDatabaseDetails(:postgresql, "dbt_synthea_dev")
40+
GenerateTables(conn)
41+
42+
diabetes_concept_ids = [201826]
43+
cohort_result = ConditionFilterPersonIDs(diabetes_concept_ids, conn)
44+
cohort_ids = cohort_result.person_id
45+
46+
sample_cohort = DataFrame(
47+
person_id = cohort_ids
48+
)
49+
50+
println("Creating individual demographic profiles...")
51+
individual_demographics = OMOPCDMFeasibility.create_individual_profiles(
52+
cohort_df=sample_cohort,
53+
conn=conn,
54+
covariate_funcs=[GetPatientGender, GetPatientRace, GetPatientAgeGroup]
55+
)
56+
57+
println("Individual profiles:")
58+
for (name, table) in pairs(individual_demographics)
59+
println("$name:")
60+
println(table)
61+
println()
62+
end
63+
64+
println("Creating Cartesian demographic profiles...")
65+
cartesian_demographics = OMOPCDMFeasibility.create_cartesian_profiles(
66+
cohort_df=sample_cohort,
67+
conn=conn,
68+
covariate_funcs=[GetPatientAgeGroup, GetPatientGender, GetPatientRace]
69+
)
70+
71+
println("Cartesian profiles:")
72+
println(cartesian_demographics)
73+
74+
DBInterface.close!(conn)
75+
```

‎docs/src/precohort.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# Pre-Cohort Analysis
2+
3+
**What is Feasibility Analysis?**
4+
5+
Feasibility analysis is the process of checking if your planned study or cohort is possible and meaningful with the data you have. It helps you answer questions like: Are there enough patients? Are the concepts I care about present? Is the data complete and reliable?
6+
7+
**What is Pre-Cohort Analysis?**
8+
9+
Pre-cohort analysis is the first step in any observational health study. Before you define your study population (the "cohort"), you use pre-cohort tools to explore your OMOP CDM database. This helps you:
10+
11+
- Understand what data is available
12+
- Check the frequency and quality of key concepts
13+
- Plan your study with confidence
14+
15+
Pre-cohort analysis is like scouting the terrain before starting a journey—it helps you avoid surprises and design better, more robust studies.
16+
17+
## 1. `analyze_concept_distribution`
18+
19+
```@docs
20+
OMOPCDMFeasibility.analyze_concept_distribution
21+
```
22+
23+
## 2. `generate_summary`
24+
25+
```@docs
26+
OMOPCDMFeasibility.generate_summary
27+
```
28+
29+
## 3. `generate_domain_breakdown`
30+
31+
```@docs
32+
OMOPCDMFeasibility.generate_domain_breakdown
33+
```
34+
35+
## Example: Pre-Cohort Analysis in Practice
36+
37+
```julia
38+
using DataFrames, DuckDB, DBInterface
39+
using OMOPCDMFeasibility
40+
using OMOPCDMCohortCreator:
41+
GenerateDatabaseDetails,
42+
GenerateTables,
43+
GetPatientGender,
44+
GetPatientAgeGroup,
45+
GetPatientRace,
46+
GetPatientEthnicity,
47+
ConditionFilterPersonIDs
48+
49+
conn = DBInterface.connect(DuckDB.DB, "synthea_1M_3YR.duckdb")
50+
51+
GenerateDatabaseDetails(:postgresql, "dbt_synthea_dev")
52+
GenerateTables(conn)
53+
54+
concept_ids = [
55+
31967, # Condition: Nausea
56+
1127433, # Drug: Acetaminophen
57+
]
58+
59+
println("\n")
60+
distribution = OMOPCDMFeasibility.analyze_concept_distribution(
61+
conn;
62+
concept_set=concept_ids,
63+
covariate_funcs=[GetPatientGender, GetPatientRace],
64+
schema="dbt_synthea_dev"
65+
)
66+
display(distribution)
67+
68+
println("\n")
69+
summary = OMOPCDMFeasibility.generate_summary(
70+
conn;
71+
concept_set=concept_ids,
72+
covariate_funcs=[GetPatientAgeGroup, GetPatientRace],
73+
schema="dbt_synthea_dev"
74+
)
75+
display(summary)
76+
77+
println("\n")
78+
domain_breakdown = OMOPCDMFeasibility.generate_domain_breakdown(
79+
conn;
80+
concept_set=concept_ids,
81+
schema="dbt_synthea_dev"
82+
)
83+
display(domain_breakdown)
84+
println()
85+
86+
DBInterface.close!(conn)
87+
```

‎docs/src/quickstart.md‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
# Quickstart 🎉
2+
3+
Welcome to the Quickstart guide for OMOPCDMFeasibility.jl! This guide shows you how to set up your Julia environment and use OMOPCDMFeasibility.jl for pre- and post-cohort analysis-after you have created a cohort using the recommended observational window template workflow.
4+
5+
## 1. Getting Started
6+
7+
### Launch Julia and Enter Your Project Environment
8+
9+
To get started:
10+
11+
1. **Open your terminal or Julia REPL.**
12+
2. **Navigate to your project folder (where `Project.toml` is located):**
13+
14+
```sh
15+
cd path/to/your/project
16+
```
17+
18+
3. **Activate the project:**
19+
20+
```sh
21+
julia --project=.
22+
```
23+
24+
4. **(Optional for docs) For working on documentation:**
25+
26+
```sh
27+
julia --project=docs
28+
```
29+
30+
## 2. Create Your Cohort with the Observation Window Template
31+
32+
> For a robust, reproducible template for observational study setup and cohort creation, follow the official workflow :
33+
>
34+
> **[Observational Template Workflow](https://juliahealth.org/HealthBase.jl/dev/observational_template_workflow/#2.-Download-OHDSI-Cohort-Definitions)**
35+
>
36+
> **1.** Go through steps 2–5 in the workflow to define and create your cohort table in your database.
37+
>
38+
> **2.** Once your cohort is created, return here to analyze it with OMOPCDMFeasibility.jl.
39+
40+
## 3. Pre-Cohort Analysis
41+
42+
Explore your data before defining a cohort.
43+
44+
**Pre-Cohort Analysis:**
45+
46+
- Pre-cohort functions (like `analyze_concept_distribution`) do **not** accept a cohort table or DataFrame. They always analyze the full database, but you can optionally stratify by covariates (e.g., gender, race, age group) using the `covariate_funcs` argument.
47+
- The `covariate_funcs` argument is optional-include it if you want to stratify by covariates.
48+
49+
To use covariate getter functions, import them from [OMOPCDMCohortCreator.jl](https://github.com/JuliaHealth/OMOPCDMCohortCreator.jl/blob/dev/src/getters.jl):
50+
51+
```julia
52+
using OMOPCDMCohortCreator: GetPatientGender, GetPatientRace, GetPatientAgeGroup
53+
```
54+
55+
For more advanced understanding and options, see [Pre-Cohort Analysis](precohort.md).
56+
57+
```julia
58+
# Check how common specific OMOP concepts are in your database
59+
# 201826 = "Hypertension", 3004249 = "Metformin"
60+
analyze_concept_distribution(conn; concept_set=[201826, 3004249], schema="main")
61+
62+
# Example with covariate_funcs (optional)
63+
analyze_concept_distribution(
64+
conn;
65+
concept_set=[201826, 3004249],
66+
covariate_funcs=[GetPatientGender, GetPatientRace],
67+
schema="main"
68+
)
69+
70+
# Get summary statistics for a set of concepts
71+
generate_summary(conn; concept_set=[201826, 3004249], schema="main")
72+
73+
# See which OMOP domains your concepts belong to
74+
generate_domain_breakdown(conn; concept_set=[201826, 3004249], schema="main")
75+
```
76+
77+
## 4. Post-Cohort Analysis
78+
79+
After extracting your cohort, you can perform post-cohort analyses as shown below.
80+
81+
**Post-Cohort Analysis:**
82+
83+
- Post-cohort functions (like `create_individual_profiles`) require you to provide either:
84+
- `cohort_definition_id` (to use a cohort table in the database), or
85+
- `cohort_df` (a DataFrame of person IDs).
86+
- You should provide only one of them.
87+
- The `covariate_funcs` argument is optional-include it if you want to stratify by covariates (e.g., gender, race, age group).
88+
89+
To use covariate getter functions, import them from [OMOPCDMCohortCreator.jl](https://github.com/JuliaHealth/OMOPCDMCohortCreator.jl/blob/dev/src/getters.jl):
90+
91+
```julia
92+
using OMOPCDMCohortCreator: GetPatientGender, GetPatientRace, GetPatientAgeGroup
93+
```
94+
95+
For more advanced understanding and options, see [Post-Cohort Analysis](postcohort.md).
96+
97+
```julia
98+
# Example: Using a DataFrame
99+
create_individual_profiles(
100+
cohort_df = sample_cohort,
101+
conn = conn,
102+
# covariate_funcs = [GetPatientGender, GetPatientRace], # optional
103+
schema = "main"
104+
)
105+
106+
# Example: Using a cohort_definition_id
107+
create_individual_profiles(
108+
cohort_definition_id = 1,
109+
conn = conn,
110+
# covariate_funcs = [GetPatientGender, GetPatientRace], # optional
111+
schema = "main"
112+
)
113+
```
114+
115+
Happy experimenting with OMOPCDMFeasibility.jl! 🎉

0 commit comments

Comments
 (0)