Generate stubs for Automated V&V Phase 1 (#22)

* first pass at stubbing

* lint

* refine

* Update src/vivarium_testing_utils/automated_validation/interface.py

Co-authored-by: Rajan Mudambi <11376379+rmudambi@users.noreply.github.com>

* change pass to notimplementederror

---------

Co-authored-by: Rajan Mudambi <11376379+rmudambi@users.noreply.github.com>

Author: 2 people

src/vivarium_testing_utils/automated_validation/calculations.py

@@ -0,0 +1,25 @@
+import pandas as pd
+
+
+def process_raw_data(
+    input_data_type: str, raw_data: pd.DataFrame, measure: str
+) -> pd.DataFrame:
+    raise NotImplementedError
+
+
+def compute_metric(
+    input_data_type: str, intermediate_data: pd.DataFrame, measure: str
+) -> pd.Series:
+    raise NotImplementedError
+
+
+def ratio(numerator, denominator):
+    raise NotImplementedError
+
+
+def aggregate(data: pd.DataFrame, groupby_cols: list[str]) -> pd.DataFrame:
+    raise NotImplementedError
+
+
+def linear_combination(coefficients: list[float], data: pd.DataFrame) -> pd.Series:
+    raise NotImplementedError

src/vivarium_testing_utils/automated_validation/comparison.py

@@ -0,0 +1,29 @@
+import pandas as pd
+
+from vivarium_testing_utils.automated_validation.calculations import compute_metric
+
+
+class Comparison:
+    def __init__(
+        self,
+        measure_key: str,
+        test_data: pd.DataFrame,
+        reference_data: pd.DataFrame,
+        stratifications: list[str] = [],
+    ):
+        self.measure = measure_key
+        self.test_data = test_data
+        self.reference_data = reference_data
+        self.computed_comparison = compute_metric(
+            self.test_data, self.reference_data, self.measure
+        )
+        # you need to marginalize out the non-stratified columns as well
+
+    def verify(self, stratifications: list[str]):
+        raise NotImplementedError
+
+    def summarize(self, stratifications: list[str]):
+        raise NotImplementedError
+
+    def heads(self, stratifications: list[str]):
+        raise NotImplementedError

src/vivarium_testing_utils/automated_validation/data_loader.py

@@ -0,0 +1,32 @@
+import pandas as pd
+from layered_config_tree import LayeredConfigTree
+
+
+class DataLoader:
+    def __init__(self, results_dir: str, cache_size_mb: int = 1000):
+        self.results_dir = results_dir
+        self.cache_size_mb = cache_size_mb
+        self.raw_datasets = LayeredConfigTree()
+        self.metadata = LayeredConfigTree()
+        self.artifact = None  # Just stubbing this out for now
+
+    def load_data(self, dataset_key: str, data_type: str) -> None:
+        raise NotImplementedError
+
+    def get_dataset(self, dataset_key: str, data_type: str) -> pd.DataFrame:
+        raise NotImplementedError
+
+    def sim_outputs(self) -> list[str]:
+        raise NotImplementedError
+
+    def artifact_keys(self) -> list[str]:
+        raise NotImplementedError
+
+    def load_from_sim(self, dataset_key: str) -> pd.DataFrame:
+        raise NotImplementedError
+
+    def load_from_artifact(self, dataset_key: str) -> pd.DataFrame:
+        raise NotImplementedError
+
+    def load_from_gbd(self, dataset_key: str) -> pd.DataFrame:
+        raise NotImplementedError

src/vivarium_testing_utils/automated_validation/interface.py

@@ -0,0 +1,48 @@
+from pathlib import Path
+
+import pandas as pd
+from layered_config_tree import LayeredConfigTree
+
+from vivarium_testing_utils.automated_validation import plot_utils
+from vivarium_testing_utils.automated_validation.comparison import Comparison
+from vivarium_testing_utils.automated_validation.data_loader import DataLoader
+
+
+class ValidationContext:
+    def __init__(self, results_dir: str | Path, age_groups: pd.DataFrame | None):
+        self.data_loader = DataLoader(results_dir)
+        self.comparisons = LayeredConfigTree()
+
+    def get_sim_outputs(self):
+        return self.data_loader.sim_outputs()
+
+    def get_artifact_keys(self):
+        return self.data_loader.artifact_keys()
+
+    def add_comparison(
+        self, measure_key: str, test_source: str, ref_source: str, stratifications: list[str]
+    ) -> None:
+        test_data = self.data_loader.get_dataset(measure_key, test_source)
+        ref_data = self.data_loader.get_dataset(measure_key, ref_source)
+        self.comparisons.update(
+            [measure_key], Comparison(measure_key, test_data, ref_data, stratifications)
+        )
+
+    def verify(self, comparison_key: str, stratifications: list[str] = []):
+        self.comparisons[comparison_key].verify(stratifications)
+
+    def plot_comparison(self, comparison_key: str, type: str, **kwargs):
+        return plot_utils.plot_comparison(self.comparisons[comparison_key], type, kwargs)
+
+    def generate_comparisons(self):
+        raise NotImplementedError
+
+    def verify_all(self):
+        for comparison in self.comparisons.values():
+            comparison.verify()
+
+    def plot_all(self):
+        raise NotImplementedError
+
+    def get_results(self, verbose: bool = False):
+        raise NotImplementedError

src/vivarium_testing_utils/automated_validation/plot_utils.py

@@ -0,0 +1,31 @@
+import pandas as pd
+
+from vivarium_testing_utils.automated_validation.comparison import Comparison
+
+
+def plot_comparison(comparison: Comparison, type: str, kwargs):
+    raise NotImplementedError
+
+
+def plot_data(dataset: pd.DataFrame, type: str, kwargs):
+    raise NotImplementedError
+
+
+def line_plot(comparison: Comparison, x_axis: str, stratifications: list[str]):
+    raise NotImplementedError
+
+
+def bar_plot(comparison: Comparison, x_axis: str, stratifications: list[str]):
+    raise NotImplementedError
+
+
+def box_plot(comparison: Comparison, cat: str, stratifications: list[str]):
+    raise NotImplementedError
+
+
+def heatmap(comparison: Comparison, row: str, col: str):
+    raise NotImplementedError
+
+
+def save_plot(fig, name, format):
+    raise NotImplementedError