Document updating HDF5 test files

[ns-rse]

Updating regression test files is relatively straight-forward but in tests/test_processing.py::test_process_scan_both the resulting HDF5 .topostast file that is generated/saved as part of the processing is compared to an existing file (tests/resources/process_scan_topostats_file_regtest.topostats.

If we add additional content to the HDF5 file (e.g. height profiles see #748 and #871) then this test will fail as the new fields won't be present.

We should, for our own sanity and that of anyone contributing, document how to update this file.

The configuration for processing is defined in tests/conftest.py::process_scan_config() and is based on topostats/default_config.yaml with some adjustments made when defining the fixture...

@pytest.fixture()
def process_scan_config() -> dict:
    """Sample configuration."""
    config = read_yaml(BASE_DIR / "topostats" / "default_config.yaml")
    config["filter"]["remove_scars"]["run"] = True
    config["grains"]["threshold_std_dev"]["below"] = 1.0
    config["grains"]["absolute_area_threshold"]["above"] = [500, 800]
    config["plotting"]["zrange"] = [0, 3]
    plotting_dictionary = pkg_resources.open_text(topostats, "plotting_dictionary.yaml")
    config["plotting"]["plot_dict"] = yaml.safe_load(plotting_dictionary.read())
    return config

...and also when setting up the test in tests/test_processing::test_process_scan_both()...

def test_process_scan_both(regtest, tmp_path, process_scan_config: dict, load_scan_data: LoadScans) -> None:
    """Regression test for checking the process_scan functions correctly."""
    # Ensure there are below grains
    process_scan_config["grains"]["threshold_std_dev"]["below"] = 0.8
    process_scan_config["grains"]["smallest_grain_size_nm2"] = 10
    process_scan_config["grains"]["absolute_area_threshold"]["below"] = [1, 1000000000]

    process_scan_config["grains"]["direction"] = "both"
...

The process_scan() function is run with img_dic["minicircle_small"] which is defined in the tests/conftest.py::load_scan_data() fixture and loads the file tests/resources/test_image/minicircle_small.topostats.

To which end the steps required to update the target file are...

1. Make a temporary directory and copy the tests/resources/test_image/minicircle_small.topostats to this directory, change directory to this location
2. Create a config.yaml for editing (topostats create-config will generate config.yaml).
3. Modify the following fields...

• filter.remove_scar.run : true
• grains.threshold_std_dev.below : 0.8`
• grains.absolute_area_threshold.above : 500, 800`
• grains.smallest_grain_size_nm2 : 10
• grains.absolute_area_threshold.below : 1, 1000000000
• grains.direction : both

4. Run analysis with custom modified config.yaml (i.e. topostats process -c config.yaml).
5. Inspect the resulting HDF5 at output/process/minicricle_small.topostats has the new/additional content.
6. Copy output/process/minicricle_small.topostats to TopoStats/tests/resources/process_scan_topostats_file_regtest.topostats
7. Confirm tests pass (pytest tests/test_processing.py::test_process_scan_both).