Report errors in background correlation setup

Errors while reading the background sheet were swallowed by a broad
try/except, silently leaving all background parameters out of the design
matrix. Correlation sheet mismatches and missing background sheets are
now reported to the user.

Author: larsevj

src/semeio/fmudesign/_excel_to_dict.py

@@ -265,19 +265,17 @@ def parse_value(value: object) -> object:
         if isinstance(maybe_path, str) and Path(maybe_path).exists():
             output[key] = seeds_from_extern(maybe_path)
 
-    # If 'background' is a file, then read it
+    # The 'background' key is either blank/'None', a reference to another file
+    # or the name of a sheet in this workbook.
     key = "background"
-    output[key] = {}
-    try:
-        value = str(generalinput[key])
-        if value.endswith(("csv", "xlsx")):
-            output[key]["extern"] = resolve_path(input_filename, value)
-        else:
-            output[key] = _read_background(input_filename, value)
-    except KeyError:
+    value = generalinput.get(key)
+    background = "" if value is None else str(value).strip()
+    if background.lower() in {"", "none"}:
         output[key] = None
-    except ValueError:
-        output[key] = generalinput[key]
+    elif background.endswith(("csv", "xlsx")):
+        output[key] = {"extern": resolve_path(input_filename, background)}
+    else:
+        output[key] = _read_background(input_filename, background)
 
     output["defaultvalues"] = _read_defaultvalues(input_filename, default_values_sheet)
 
@@ -464,6 +462,18 @@ def _read_background(inp_filename: str, bck_sheet: str) -> dict[str, Any]:
     """
     backdict: dict[str, Any] = {}
     paramdict: dict[str, Any] = {}
+    with pd.ExcelFile(inp_filename, engine="openpyxl") as workbook:
+        sheet_names = [str(name) for name in workbook.sheet_names]
+    try:
+        bck_sheet = find_sheet(bck_sheet, names=sheet_names)
+    except ValueError as err:
+        raise ValueError(
+            f"Sheet {bck_sheet!r} with background parameters, specified in the "
+            f"general input sheet, was not found in {inp_filename!r}.\n"
+            f"Sheets in workbook: {sheet_names}\n"
+            "Use 'None' as background in the general input sheet if no "
+            "background parameters are wanted."
+        ) from err
     bck_input = (
         pd.read_excel(inp_filename, bck_sheet, engine="openpyxl")
         .dropna(axis=0, how="all")
@@ -472,7 +482,9 @@ def _read_background(inp_filename: str, bck_sheet: str) -> dict[str, Any]:
 
     backdict["correlations"] = None
     if "corr_sheet" in bck_input:
-        backdict["correlations"] = _read_correlations(bck_input, inp_filename)
+        backdict["correlations"] = _read_correlations(
+            bck_input, inp_filename, group_description=f"background sheet {bck_sheet!r}"
+        )
 
     if "dist_param1" not in bck_input.columns.to_numpy():
         bck_input["dist_param1"] = float("NaN")
@@ -686,9 +698,17 @@ def _read_dist_sensitivity(sensgroup: pd.DataFrame) -> dict[str, Any]:
 
 
 def _read_correlations(
-    sensgroup: pd.DataFrame, inputfile: str
+    sensgroup: pd.DataFrame, inputfile: str, group_description: str | None = None
 ) -> dict[str, Any] | None:
-    """Parse correlation information from a sensitivity group."""
+    """Parse correlation information from a sensitivity group.
+
+    Args:
+        sensgroup: rows describing the parameters, either a sensitivity group
+            from the designinput sheet or the background sheet.
+        inputfile: name of the Excel workbook holding the correlation sheets.
+        group_description: how to refer to `sensgroup` in error messages.
+            Defaults to the sensname of the group.
+    """
 
     # No correlation sheet column exists
     if "corr_sheet" not in sensgroup.columns:
@@ -698,6 +718,9 @@ def _read_correlations(
     if sensgroup["corr_sheet"].dropna().empty:
         return None
 
+    if group_description is None:
+        group_description = f"sensitivity group {sensgroup['sensname'].iloc[0]!r}"
+
     correlations: dict[str, Any] = {"inputfile": inputfile}
 
     # Create a mapping 'corr_to_params' like:
@@ -714,11 +737,10 @@ def _read_correlations(
     for corr_sheet, parameters in corr_to_params.items():
         df_corr = read_correlations(excel_filename=inputfile, corr_sheet=corr_sheet)
         if set(df_corr.columns) != set(parameters):
-            sensname = sensgroup["sensname"].iloc[0]
-            msg = f"Mismatch between parameters in sensitivity group {sensname!r} "
+            msg = f"Mismatch between parameters in {group_description} "
             msg += f"pointing to\ncorrelation sheet {corr_sheet!r} and "
             msg += "parameters specified in that correlation sheet.\n"
-            msg += f"Parameters in sensitivity group: {sorted(set(parameters))}\n"
+            msg += f"Parameters in {group_description}: {sorted(set(parameters))}\n"
             msg += f"Parameters in correlation sheet: {sorted(set(df_corr.columns))}\n"
             msg += "These parameters must be specified one-to-one."
             raise ValueError(msg)

tests/fmudesign/test_excel_to_dict.py

@@ -228,6 +228,154 @@ def test_background_sheet(tmpdir, monkeypatch):
     assert dict_design["defaultvalues"]["extraseed"] == 0
 
 
+def _write_background_workbook(filename, background, corr_matrix, background_name):
+    """Write a workbook with a background sheet and a 'bgcorr' correlation sheet."""
+    general_input = pd.DataFrame(
+        data=[
+            ["designtype", "onebyone"],
+            ["repeats", 3],
+            ["rms_seeds", "default"],
+            ["background", background_name],
+            ["distribution_seed", 42],
+        ]
+    )
+    defaultvalues = pd.DataFrame(
+        columns=["param_name", "default_value"], data=[["PARAM_A", 0], ["PARAM_B", 0]]
+    )
+    with pd.ExcelWriter(filename, engine="openpyxl") as writer:
+        general_input.to_excel(
+            writer, sheet_name="general_input", index=False, header=None
+        )
+        MOCK_DESIGNINPUT.to_excel(
+            writer, sheet_name="designinput", index=False, header=None
+        )
+        defaultvalues.to_excel(writer, sheet_name="defaultvalues", index=False)
+        background.to_excel(
+            writer, sheet_name="backgroundsheet", index=False, header=None
+        )
+        if corr_matrix is not None:
+            corr_matrix.to_excel(writer, sheet_name="bgcorr")
+
+
+BACKGROUND_WITH_CORR = pd.DataFrame(
+    data=[
+        ["param_name", "dist_name", "dist_param1", "dist_param2", "corr_sheet"],
+        ["PARAM_A", "uniform", 0, 1, "bgcorr"],
+        ["PARAM_B", "uniform", 0, 1, "bgcorr"],
+    ]
+)
+
+
+def test_background_correlation_sheet_with_mismatching_index_and_columns(
+    tmpdir, monkeypatch
+):
+    """Correlation matrices for background parameters must be validated the same
+    way as correlation matrices for ordinary sensitivities."""
+    monkeypatch.chdir(tmpdir)
+    corr_matrix = pd.DataFrame(
+        [[1.0, np.nan], [0.5, 1.0]],
+        index=["PARAM_A", "PARAM_B"],
+        columns=["PARAM_A", "PARAM_TYPO"],
+    )
+    _write_background_workbook(
+        "designinput.xlsx", BACKGROUND_WITH_CORR, corr_matrix, "backgroundsheet"
+    )
+
+    with pytest.raises(
+        ValueError, match="Mismatch between column and index in correlation"
+    ):
+        excel_to_dict("designinput.xlsx")
+
+
+def test_background_correlation_sheet_with_mismatching_parameters(tmpdir, monkeypatch):
+    """Parameters pointing to a correlation sheet from the background sheet must
+    match the parameters in that correlation sheet exactly."""
+    monkeypatch.chdir(tmpdir)
+    corr_matrix = pd.DataFrame(
+        [[1.0, np.nan], [0.5, 1.0]],
+        index=["PARAM_A", "PARAM_TYPO"],
+        columns=["PARAM_A", "PARAM_TYPO"],
+    )
+    _write_background_workbook(
+        "designinput.xlsx", BACKGROUND_WITH_CORR, corr_matrix, "backgroundsheet"
+    )
+
+    with pytest.raises(ValueError, match="Mismatch between parameters"):
+        excel_to_dict("designinput.xlsx")
+
+
+def test_background_sheet_that_does_not_exist(tmpdir, monkeypatch):
+    """A background sheet name that does not exist must be reported, listing the
+    sheets that are available."""
+    monkeypatch.chdir(tmpdir)
+    _write_background_workbook(
+        "designinput.xlsx", BACKGROUND_WITH_CORR, None, "typo_sheet"
+    )
+
+    with pytest.raises(ValueError, match="Sheets in workbook") as exc_info:
+        excel_to_dict("designinput.xlsx")
+
+    message = str(exc_info.value)
+    assert "typo_sheet" in message
+    assert "backgroundsheet" in message
+    assert "Use 'None' as background" in message
+
+
+@pytest.mark.parametrize(
+    "background_name", ["Backgroundsheet", "background_sheet", " backgroundsheet "]
+)
+def test_background_sheet_name_is_matched_softly(tmpdir, monkeypatch, background_name):
+    monkeypatch.chdir(tmpdir)
+    corr_matrix = pd.DataFrame(
+        [[1.0, np.nan], [0.5, 1.0]],
+        index=["PARAM_A", "PARAM_B"],
+        columns=["PARAM_A", "PARAM_B"],
+    )
+    _write_background_workbook(
+        "designinput.xlsx", BACKGROUND_WITH_CORR, corr_matrix, background_name
+    )
+
+    background = excel_to_dict("designinput.xlsx")["background"]
+    assert list(background["parameters"]) == ["PARAM_A", "PARAM_B"]
+
+
+def test_background_file_that_does_not_exist(tmpdir, monkeypatch):
+    monkeypatch.chdir(tmpdir)
+    _write_background_workbook(
+        "designinput.xlsx", BACKGROUND_WITH_CORR, None, "missing_background.csv"
+    )
+
+    with pytest.raises(ValueError, match="Failed to resolve path"):
+        excel_to_dict("designinput.xlsx")
+
+
+@pytest.mark.parametrize("background_name", ["None", "none", np.nan])
+def test_background_not_in_use(tmpdir, monkeypatch, background_name):
+    """Not specifying a background must not be an error."""
+    monkeypatch.chdir(tmpdir)
+    _write_background_workbook(
+        "designinput.xlsx", BACKGROUND_WITH_CORR, None, background_name
+    )
+
+    assert excel_to_dict("designinput.xlsx")["background"] is None
+
+
+def test_background_correlations_are_read(tmpdir, monkeypatch):
+    monkeypatch.chdir(tmpdir)
+    corr_matrix = pd.DataFrame(
+        [[1.0, np.nan], [0.5, 1.0]],
+        index=["PARAM_A", "PARAM_B"],
+        columns=["PARAM_A", "PARAM_B"],
+    )
+    _write_background_workbook(
+        "designinput.xlsx", BACKGROUND_WITH_CORR, corr_matrix, "backgroundsheet"
+    )
+
+    background = excel_to_dict("designinput.xlsx")["background"]
+    assert background["correlations"]["sheetnames"] == ["bgcorr"]
+    assert list(background["parameters"]) == ["PARAM_A", "PARAM_B"]
+
+
 def test_assert_no_merged_cells(tmpdir, monkeypatch):
     """Test that assert_no_merged_cells detects merged cells"""
     monkeypatch.chdir(tmpdir)