Reorganize documentation

Author: kzollove

rmd/_site.yml

@@ -16,54 +16,27 @@ navbar:
     - text: "Home"
       icon: fa-home
       href: index.html
+    - text: "Getting Started"
+      icon: fa-home
+      href: getting-started.html 
     - text: "Gaia"
       icon: fa-earth
       menu:
         - text: "Overview"
           href: gaia-intro.html
         - text: "Design"
           href: gaia-principles.html                     # TODO add the architecture diagram
-        - text: "Specifications"
-          menu: 
-             - text: "Terminology"
-               href: gaia-terminology.html    
-             - text: "Data Models"
-               href: gaia-datamodels.html
-    - text: "Gaia Framework"
-      icon: fa-cubes
-      menu:
-        - text: "Overview"
-          href: fw-overview.html
-        - text: "Gaia Catalog"
-          href: fw-gaia-catalog.html
-        - text: "Gaia Core"
-          href: fw-gaia-core.html         # TODO create this
-        - text: "Extensions"
-          menu:
-            - text: "Overview"
-              href: fw-gaia-extensions.html       # TODO create this
-            - text: "GaiaOhdsi"
-              href: fw-gaia-extensions-ohdsi.html       # TODO create this
+        - text: "Data Models"
+          href: gaia-datamodels.html 
+        - text: "gaiaDB"
+          href: gaiaDB.html
+        - text: "gaiaCore"
+          href: gaiaCore.html
+        - text: "gaiaOHDSI"
+          href: gaiaOHDSI.html
     - text: "How to"
       icon: fa-question
-      menu:
-        - text: "Get Started with Gaia"
-          href: ht-get-started.html
-        - text: "Use a Local Dataset"
-          href: ht-local-dataset.html
-        - text: "Geocode for OMOP Database Addresses"
-          href: ht-geocode.html              # TODO combine into one geocoding article
-        - text: "Geocode an OMOP Cohort"
-          href: geocodingCohort.html            # TODO combine into one geocoding article
-        - text: "Add Data Sources to a Local gaiaDB Instance"
-          href: ht-add-data-source.html
-        - text: "Share Your Local Data Sources"
-          href: ht-share-data-source.html
+      href: how-to.html # MERGE ht-overview, ht-local-dataset, ht-add-data-source, ht-share-data-source
     - text: "Getting Involved"
       icon: fa-info
-      menu:
-        - text: "Use Case Proposals"
-          href: gi-propose-usecase.html
-        - text: "How to Edit Documentation"
-          href: gi-edit-docs.html           # TODO add a quick para on cycle of clone repo -> edit RMD -> regenerate with render_gaia_site.R
-
+      href: getting-involved.html # MERGE gi-propose-usecase, gi-edit-docs, and start with a blurb about joining Workgroup meetings

rmd/fw-gaia-catalog.Rmd

@@ -26,17 +26,17 @@ This is the specification document for the gaiaDB Data Model. **This data model
 
 ```{r docLoopGaia, echo=FALSE, results='asis'}
 
-tableSpecs <- readr::read_csv("../inst/csv/gaia001tableLevel.csv", show_col_types = FALSE)
-cdmSpecs <- readr::read_csv("../inst/csv/gaia001fieldLevel.csv", show_col_types = FALSE)
+tableSpecs <- readr::read_csv("../inst/csv/Gaia_Table_Level.csv", show_col_types = FALSE)
+cdmSpecs <- readr::read_csv("../inst/csv/Gaia_Field_Level.csv", show_col_types = FALSE)
 
-tables <- tableSpecs$gaiaTableName
+tables <- tableSpecs$cdmTableName
 
 gaiaSpecsClean <- cdmSpecs %>%
-  dplyr::select(`Gaia Table` = gaiaTableName,
-                `Gaia Field` = gaiaFieldName,
+  dplyr::select(`Gaia Table` = cdmTableName,
+                `Gaia Field` = cdmFieldName,
                 `User Guide` = userGuidance,
                 `ETL Conventions` = etlConventions,
-                `Datatype` = gaiaDataType,
+                `Datatype` = cdmDataType,
                 `Required` = isRequired,
                 `Primary Key` = isPrimaryKey,
                 `Foreign Key` = isForeignKey,
@@ -48,24 +48,20 @@ gaiaSpecsClean[is.na(gaiaSpecsClean)] <- ""
 
 for(tb in tables) {
   
-  if(tb == 'data_source') {
-    cat("## **Backbone**\n\n")
-  }
-  
-  if(tb == 'geom_omop_location') {
+  if(tb == 'location_history') {
     cat("## **OMOP**\n\n")
   }
   
-  if(tb == 'exposure_occurrence') {
+  if(tb == 'external_exposure') {
     cat("## **CDM Extension**\n\n")
   }
   
   cat("###", tb, "{.tabset .tabset-pills} \n\n")
   
-  tableInfo <- subset(tableSpecs, gaiaTableName == tb)
+  tableInfo <- subset(tableSpecs, cdmTableName == tb)
   cat("**Table Description**\n\n",tableInfo[,"tableDescription"][[1]], "\n\n")
   
-  fieldInfo <- subset(cdmSpecs, gaiaTableName == tb)
+  fieldInfo <- subset(cdmSpecs, cdmTableName == tb)
   if(!isTRUE(fieldInfo[,"userGuidance"][[1]]=="")){
     cat("**User Guide**\n\n",fieldInfo[,"userGuidance"][[1]],"\n\n")
   }

rmd/fw-gaia-extensions-ohdsi.Rmd

@@ -59,3 +59,40 @@ Taking this scenario a step further, a researcher with an established OMOP CDM d
 
 Finally, Gaia enables standardized and reproducible workflows for federated data networks and studies. The process highlighted above to retrieve and harmonize geospatial datasets, perform spatiotemporal joins to transform place-based data to person-level information, and insert person-level information into an OMOP CDM and define cohorts, is fully reproducible. Each step of the process contains detailed, structured metadata focused on provenance of source data and rationale for transformation methods. By scripting and containerizing an entire Gaia workflow, the process of pairing place-based data, often handled using undocumented ad-hoc methods unique to single sites, can be packaged and shipped across an entire network with minimal effort.
 
+
+# Added from Gaia Framework Overview (below)
+
+# **Gaia Framework Overview**
+
+<div><img src="images/framework_overview.png"></img></div>
+The Gaia Framework provides the highest-level view of the components that compose Gaia; the framework is divided into three main parts, a functional metadata repository (Catalog), staging database and execution engine (Core), and ecosystem of Gaia-compatible software packages (Extensions):
+
+---
+
+<br>
+
+## [Gaia Catalog](gaia-catalog.html)
+
+A readily-extensible catalog of source datasets. Gaia Catalog contains metadata for public geospatial datasets. Descriptive metadata facilitates search and discovery of relevant datasets. Functional metadata (machine-actionable instructions) enables automated retrieval, extraction, transformation, and loading of public datasets and their constituent variables.
+
+---
+
+<br>
+
+## [Gaia Core](gaia-core.html)
+
+Gaia Core is the central functionality and storage of Gaia and itself consists of two main features: a **staging database** and an **execution engine**.
+
+The staging database is a PostGIS database with a replica copy of the Gaia Catalog installed in a schema named "backbone". In this database, public datasets that are registered in Gaia Catalog can be "staged": transformed and then loaded as tables in a standardized Entity-Attribute-Value format. Other geospatial data, such as geocoded addresses, can also be loaded into the staging database for use in conjunction with the staged data.
+
+All operations on the staging database (creating tables, inserting data, accessing data, etc.) are performed through the "execution engine". The execution engine can be any software package (e.g. R package, Python library, CLI) that connects to the database and functionalizes the logic required to write or read data to and from the standard format. Currently, there is one execution engine: an R Package named [gaiaCore](gaiaCore/index.html).
+
+---
+
+<br>
+
+
+## [Extensions](gaia-extensions.html)
+
+Any functionality that falls outside of Gaia Core's scope (basic Create, Read, Update and Delete operations) can be encapsulated in an Extension. An extension can be thought of as a software package or library that interfaces with Gaia Core (through the execution engine) that collects similar functionality. Extensions can be grouped by the communities they serve or by the functionality they provide. For example, the [gaiaOHDSI extension](gaia-extensions-ohdsi.html) is built to provide members of the OHDSI community useful connectors between Gaia Core and an OMOP database and various OHDSI tools. On the other hand, general (hypothetical) extensions like gaiaVis or gaiaLayer provide visualization and layer building software to Gaia Core, respectively.
+

rmd/fw-gaia-extensions.Rmd

@@ -5,7 +5,7 @@ output:
         toc: FALSE
 ---
 
-# **GaiaCore**
+# **gaiaCore**
 
 ## Description
 

rmd/fw-overview.Rmd

@@ -0,0 +1,24 @@
+---
+title: '<div><img src="ohdsi40x40.png"></img> OHDSI GIS WG</div>'
+output:
+   html_document:
+        toc: FALSE
+---
+
+# **gaiaDB**
+
+## Description
+
+gaiaDB is the central functionality and storage of Gaia and consists of two main features: a **staging database** and an **execution engine**.
+
+The staging database is a PostGIS database with a replica copy of the Gaia Catalog installed in a schema named "backbone". In this database, public datasets that are registered in Gaia Catalog can be "staged": transformed and then loaded as tables in a standardized Entity-Attribute-Value format. Other geospatial data, such as geocoded addresses, can also be loaded into the staging database for use in conjunction with the staged data.
+
+All operations on the staging database (creating tables, inserting data, accessing data, etc.) are performed through the "execution engine". The execution engine can be any software package (e.g. R package, Python library, CLI) that connects to the database and functionalizes the logic required to write or read data to and from the standard format.
+
+## Scope
+
+The **ultimate vision** of Gaia DB is support for multiple geospatial databases (particularly cloud-native), as well as execution engine interfaces for multiple popular data science programming languages (e.g. Python, Julia, R, Bash). **Currently**, the staging database has only been implemented in PostGIS and the execution engine has only been implemented in R.
+
+## Documentation
+
+[gaiaDB (R Package)](gaiaDB/index.html)

rmd/gaia-datamodels.Rmd

@@ -0,0 +1,24 @@
+---
+title: '<div><img src="ohdsi40x40.png"></img> OHDSI GIS WG</div>'
+output:
+   html_document:
+        toc: FALSE
+---
+
+# **gaiaOHDSI**
+
+## Description
+
+Gaia Core is the central functionality and storage of Gaia and consists of two main features: a **staging database** and an **execution engine**.
+
+The staging database is a PostGIS database with a replica copy of the Gaia Catalog installed in a schema named "backbone". In this database, public datasets that are registered in Gaia Catalog can be "staged": transformed and then loaded as tables in a standardized Entity-Attribute-Value format. Other geospatial data, such as geocoded addresses, can also be loaded into the staging database for use in conjunction with the staged data.
+
+All operations on the staging database (creating tables, inserting data, accessing data, etc.) are performed through the "execution engine". The execution engine can be any software package (e.g. R package, Python library, CLI) that connects to the database and functionalizes the logic required to write or read data to and from the standard format.
+
+## Scope
+
+The **ultimate vision** of Gaia Core is support for multiple geospatial databases (particularly cloud-native), as well as execution engine interfaces for multiple popular data science programming languages (e.g. Python, Julia, R, Bash). **Currently**, the staging database has only been implemented in PostGIS and the execution engine has only been implemented in R.
+
+## Documentation
+
+[gaiaOHDSI (R Package)](gaiaOHDSI/index.html)