Reorganize builders

- Moves contents of `statistics` to `builders`
- Moves base_table_builder from root to builders

cumulus_library/__init__.py

@@ -1,8 +1,8 @@
 """Package metadata"""
 
-from .base_table_builder import BaseTableBuilder
 from .base_utils import StudyConfig
-from .statistics.counts import CountsBuilder
+from .builders.base_table_builder import BaseTableBuilder
+from .builders.counts import CountsBuilder
 from .study_manifest import StudyManifest
 
 __all__ = ["BaseTableBuilder", "CountsBuilder", "StudyConfig", "StudyManifest"]

cumulus_library/actions/builder.py

@@ -11,15 +11,15 @@
 from rich.progress import Progress, TaskID
 
 from cumulus_library import (
-    base_table_builder,
+    BaseTableBuilder,
     base_utils,
     databases,
     enums,
     errors,
     log_utils,
-    protected_table_builder,
     study_manifest,
 )
+from cumulus_library.builders import protected_table_builder
 from cumulus_library.statistics import psm
 
 
@@ -72,10 +72,7 @@ def _load_and_execute_builder(
     # we'll punt.
     table_builder_subclasses = []
     for _, cls_obj in inspect.getmembers(table_builder_module, inspect.isclass):
-        if (
-            issubclass(cls_obj, base_table_builder.BaseTableBuilder)
-            and cls_obj != base_table_builder.BaseTableBuilder
-        ):
+        if issubclass(cls_obj, BaseTableBuilder) and cls_obj != BaseTableBuilder:
             table_builder_subclasses.append(cls_obj)
 
     if len(table_builder_subclasses) == 0:

cumulus_library/builders/README.md

@@ -0,0 +1,42 @@
+# SQL builders
+
+This folder contains various builders, either exposed as part of the package
+API or configurable via toml config files, that are intended to be used
+as starting points in studies.
+
+## Class-based builders
+
+These are intended to be used directly via python
+
+### BaseTableBuilder(base_table_builder.py)
+
+All builders inherit from this class. This handles the prepare/execute
+hooks that Cumulus Library uses to invoke queries against your
+database. If you're writing a custom builder, base it off this and
+implement `prepare_queries()`.
+
+### CountsBuilder(counts.py)
+
+The CountsBuilder provides conveniences for generating aggregate tables
+by summarizing data at the FHIR resource level. These are the basic
+output units of Cumulus Library.
+
+As long as your table has the appropriate resource refs (always the
+ref of the resource in question, and occasionally also either subject
+or encounter refs), all you need is to specify the columns you want
+and optional join clauses, and it will handle constructing the 
+counts query for you
+
+## Config-based Builders
+
+These builders are not meant to be imported as base classes in python
+directly (though you could if you wanted). Instead, these provide
+a configuration file format, in toml, which you can use to customize
+a strict set of build steps.
+
+### Propensity score matching (psm.py)
+
+This handles generating a cohort around a specific variable of interest.
+See the
+[PSM documentation](https://docs.smarthealthit.org/cumulus/library/statistics/propensity-score-matching.html)
+for more info

cumulus_library/statistics/counts.py → cumulus_library/builders/counts.py

@@ -3,14 +3,14 @@
 import sys
 from pathlib import Path
 
-from cumulus_library import base_table_builder, errors, study_manifest
+from cumulus_library import BaseTableBuilder, errors, study_manifest
 from cumulus_library.statistics.statistics_templates import counts_templates
 
 # Defined here for easy overriding by tests
 DEFAULT_MIN_SUBJECT = 10
 
 
-class CountsBuilder(base_table_builder.BaseTableBuilder):
+class CountsBuilder(BaseTableBuilder):
     """Extends BaseTableBuilder for counts-related use cases"""
 
     def __init__(self, study_prefix: str | None = None):

cumulus_library/protected_table_builder.py → cumulus_library/builders/protected_table_builder.py

@@ -1,7 +1,7 @@
 """Builder for creating tables for tracking state/logging changes"""
 
 from cumulus_library import (
-    base_table_builder,
+    BaseTableBuilder,
     base_utils,
     enums,
     study_manifest,
@@ -30,7 +30,7 @@
 ]
 
 
-class ProtectedTableBuilder(base_table_builder.BaseTableBuilder):
+class ProtectedTableBuilder(BaseTableBuilder):
     """Builder for tables that persist across study clean/build actions"""
 
     display_text = "Creating/updating system tables..."

cumulus_library/statistics/psm.py → cumulus_library/builders/psm.py

@@ -16,7 +16,7 @@
 # these imports are mimicing PsmPy imports for re-implemented functions
 from psmpy.functions import cohenD
 
-from cumulus_library import base_table_builder, base_utils, databases
+from cumulus_library import BaseTableBuilder, base_utils, databases
 from cumulus_library.statistics.statistics_templates import psm_templates
 from cumulus_library.template_sql import base_templates
 
@@ -49,7 +49,7 @@ class PsmConfig:
     seed: int
 
 
-class PsmBuilder(base_table_builder.BaseTableBuilder):
+class PsmBuilder(BaseTableBuilder):
     """TableBuilder for creating PSM tables"""
 
     display_text = "Building PSM tables..."

cumulus_library/statistics/README.md

@@ -0,0 +1,5 @@
+# Deprecation notice
+
+The statistics module has been combined with other tables builders into
+the new `builders` module. Backwards compatibility for importing from 
+`statistics` will be removed in a future version.

cumulus_library/statistics/__init__.py

@@ -0,0 +1 @@
+from cumulus_library.builders import counts, psm, statistics_templates

cumulus_library/statistics/counts/__init__.py

@@ -0,0 +1 @@
+from cumulus_library.builders import counts

cumulus_library/statistics/statistics_templates/__init__.py

@@ -0,0 +1 @@
+from cumulus_library.builders.statistics_templates import counts_templates, psm_templates

tests/core/test_core_allergy.py

@@ -240,7 +240,7 @@ def test_core_allergy_date_cutoff(tmp_path):
     assert ["New"] == list(df.id)
 
 
-@mock.patch("cumulus_library.statistics.counts.DEFAULT_MIN_SUBJECT", new=1)
+@mock.patch("cumulus_library.builders.counts.DEFAULT_MIN_SUBJECT", new=1)
 def test_core_count_allergy_intolerance_by_patient(tmp_path):
     """Verify that our basic allergy count is per-patient"""
     testbed = testbed_utils.LocalTestbed(tmp_path)