create empty and create_empty_like

src/mdio/api/__init__.py

@@ -1 +1,6 @@
 """Public API."""
+
+from mdio.api.create import create_empty
+from mdio.api.create import create_empty_like
+
+__all__ = ["create_empty", "create_empty_like"]

src/mdio/api/create.py

@@ -0,0 +1,168 @@
+"""Creating MDIO v1 datasets."""
+
+from __future__ import annotations
+
+from datetime import UTC
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+from mdio.api.io import _normalize_path
+from mdio.api.io import open_mdio
+from mdio.api.io import to_mdio
+from mdio.builder.template_registry import TemplateRegistry
+from mdio.builder.xarray_builder import to_xarray_dataset
+from mdio.converters.segy import populate_dim_coordinates
+from mdio.converters.type_converter import to_structured_type
+from mdio.core.grid import Grid
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from segy.schema import HeaderSpec
+    from upath import UPath
+    from xarray import Dataset as xr_Dataset
+
+    from mdio.builder.schemas import Dataset
+    from mdio.builder.templates.base import AbstractDatasetTemplate
+    from mdio.core.dimension import Dimension
+
+
+def create_empty(  # noqa PLR0913
+    mdio_template: AbstractDatasetTemplate | str,
+    dimensions: list[Dimension],
+    output_path: UPath | Path | str | None,
+    headers: HeaderSpec | None = None,
+    overwrite: bool = False,
+) -> xr_Dataset:
+    """A function that creates an empty MDIO v1 file with known dimensions.
+
+    Args:
+        mdio_template: The MDIO template or template name to use to define the dataset structure.
+        dimensions: The dimensions of the MDIO file.
+        output_path: The universal path for the output MDIO v1 file.
+        headers: SEG-Y v1.0 trace headers. Defaults to None.
+        overwrite: Whether to overwrite the output file if it already exists. Defaults to False.
+
+    Returns:
+        The output MDIO dataset.
+
+    Raises:
+        FileExistsError: If the output location already exists and overwrite is False.
+    """
+    output_path = _normalize_path(output_path)
+
+    if not overwrite and output_path.exists():
+        err = f"Output location '{output_path.as_posix()}' exists. Set `overwrite=True` if intended."
+        raise FileExistsError(err)
+
+    header_dtype = to_structured_type(headers.dtype) if headers else None
+    grid = Grid(dims=dimensions)
+    if isinstance(mdio_template, str):
+        # A template name is passed in. Get a unit-unaware template from registry
+        mdio_template = TemplateRegistry().get(mdio_template)
+    # Build the dataset using the template
+    mdio_ds: Dataset = mdio_template.build_dataset(name=mdio_template.name, sizes=grid.shape, header_dtype=header_dtype)
+
+    # Convert to xarray dataset
+    xr_dataset: xr_Dataset = to_xarray_dataset(mdio_ds=mdio_ds)
+
+    # Populate coordinates using the grid
+    # For empty datasets, we only populate dimension coordinates
+    drop_vars_delayed = []
+    xr_dataset, drop_vars_delayed = populate_dim_coordinates(xr_dataset, grid, drop_vars_delayed=drop_vars_delayed)
+
+    if headers:
+        # Since the headers were provided, the user wants to export to SEG-Y
+        # Add a dummy segy_file_header variable used to export to SEG-Y
+        xr_dataset["segy_file_header"] = ((), "")
+
+    # Create the Zarr store with the correct structure but with empty arrays
+    if output_path is not None:
+        to_mdio(xr_dataset, output_path=output_path, mode="w", compute=False)
+
+    # Write the dimension coordinates and trace mask
+    xr_dataset = xr_dataset[drop_vars_delayed + ["trace_mask"]]
+
+    if output_path is not None:
+        to_mdio(xr_dataset, output_path=output_path, mode="r+", compute=True)
+
+    return xr_dataset
+
+
+def create_empty_like(  # noqa PLR0913
+    input_path: UPath | Path | str,
+    output_path: UPath | Path | str,
+    keep_coordinates: bool = False,
+    overwrite: bool = False,
+) -> xr_Dataset:
+    """A function that creates an empty MDIO v1 file with the same structure as an existing one.
+
+    Args:
+        input_path: The path of the input MDIO file.
+        output_path: The path of the output MDIO file.
+                     If None, the output will not be written to disk.
+        keep_coordinates: Whether to keep the coordinates in the output file.
+        overwrite: Whether to overwrite the output file if it exists.
+
+    Returns:
+        The output MDIO dataset.
+
+    Raises:
+        FileExistsError: If the output location already exists and overwrite is False.
+    """
+    input_path = _normalize_path(input_path)
+    output_path = _normalize_path(output_path) if output_path is not None else None
+
+    if not overwrite and output_path is not None and output_path.exists():
+        err = f"Output location '{output_path.as_posix()}' exists. Set `overwrite=True` if intended."
+        raise FileExistsError(err)
+
+    ds = open_mdio(input_path)
+
+    # Create a copy with the same structure but no data or,
+    # optionally, coordinates
+    ds_output = ds.copy(data=None).reset_coords(drop=not keep_coordinates)
+
+    # Dataset
+    # Keep the name (which is the same as the used template name) and the original API version
+    # ds_output.attrs["name"]
+    # ds_output.attrs["apiVersion"]
+    ds_output.attrs["createdOn"] = str(datetime.now(UTC))
+
+    # Coordinates
+    if not keep_coordinates:
+        for coord_name in ds_output.coords:
+            ds_output[coord_name].attrs.pop("unitsV1", None)
+
+    # MDIO attributes
+    attr = ds_output.attrs["attributes"]
+    if attr is not None:
+        attr.pop("gridOverrides", None)  # Empty dataset should not have gridOverrides
+        # Keep the original values for the following attributes
+        # attr["defaultVariableName"]
+        # attr["surveyType"]
+        # attr["gatherType"]
+
+    # "All traces should be marked as dead in empty dataset"
+    if "trace_mask" in ds_output.variables:
+        ds_output["trace_mask"][:] = False
+
+    # Data variable
+    var_name = attr["defaultVariableName"]
+    var = ds_output[var_name]
+    var.attrs.pop("statsV1", None)
+    if not keep_coordinates:
+        var.attrs.pop("unitsV1", None)
+
+    # SEG-Y file header
+    if "segy_file_header" in ds_output.variables:
+        segy_file_header = ds_output["segy_file_header"]
+        if segy_file_header is not None:
+            segy_file_header.attrs.pop("textHeader", None)
+            segy_file_header.attrs.pop("binaryHeader", None)
+            segy_file_header.attrs.pop("rawBinaryHeader", None)
+
+    if output_path is not None:
+        to_mdio(ds_output, output_path=output_path, mode="w", compute=True)
+
+    return ds_output

src/mdio/builder/dataset_builder.py

@@ -6,7 +6,6 @@
 from enum import auto
 from typing import Any
 
-from mdio import __version__
 from mdio.builder.formatting_html import dataset_builder_repr_html
 from mdio.builder.schemas.compressors import ZFP
 from mdio.builder.schemas.compressors import Blosc
@@ -59,6 +58,8 @@ class MDIODatasetBuilder:
     """
 
     def __init__(self, name: str, attributes: dict[str, Any] | None = None):
+        from mdio import __version__  # noqa: PLC0415 -  fixed circular import in mdio package and dataset_builder.py
+
         self._metadata = DatasetMetadata(
             name=name,
             api_version=__version__,

src/mdio/converters/__init__.py

@@ -1,6 +1,30 @@
 """MDIO Data conversion API."""
 
-from mdio.converters.mdio import mdio_to_segy
-from mdio.converters.segy import segy_to_mdio
+from typing import TYPE_CHECKING
+from typing import Any
+
+if TYPE_CHECKING:
+    from mdio.converters.mdio import mdio_to_segy
+    from mdio.converters.segy import segy_to_mdio
 
 __all__ = ["mdio_to_segy", "segy_to_mdio"]
+
+
+def __getattr__(name: str) -> Any:  # noqa: ANN401 - required for dynamic attribute access
+    """Lazy import for converters to avoid circular imports."""
+    if name == "mdio_to_segy":
+        from mdio.converters.mdio import (  # noqa: PLC0415 - intentionally inside the function to avoid circular imports
+            mdio_to_segy,
+        )
+
+        return mdio_to_segy
+
+    if name == "segy_to_mdio":
+        from mdio.converters.segy import (  # noqa: PLC0415 - intentionally inside the function to avoid circular imports
+            segy_to_mdio,
+        )
+
+        return segy_to_mdio
+
+    err = f"module {__name__!r} has no attribute {name!r}"
+    raise AttributeError(err)

tests/conftest.py

@@ -47,6 +47,18 @@ def zarr_tmp(tmp_path_factory: pytest.TempPathFactory) -> Path:
     return tmp_path_factory.mktemp(r"mdio")
 
 
+@pytest.fixture(scope="session")
+def teapot_mdio_tmp(tmp_path_factory: pytest.TempPathFactory) -> Path:
+    """Make a temp file for the output MDIO."""
+    return tmp_path_factory.mktemp(r"teapot.mdio")
+
+
+@pytest.fixture(scope="module")
+def mdio_4d_tmp(tmp_path_factory: pytest.TempPathFactory) -> Path:
+    """Make a temp file for the output MDIO."""
+    return tmp_path_factory.mktemp(r"tmp_4d.mdio")
+
+
 @pytest.fixture(scope="module")
 def zarr_tmp2(tmp_path_factory: pytest.TempPathFactory) -> Path:  # pragma: no cover - used by disabled test
     """Make a temp file for the output MDIO."""
@@ -58,3 +70,9 @@ def segy_export_tmp(tmp_path_factory: pytest.TempPathFactory) -> Path:
     """Make a temp file for the round-trip IBM SEG-Y."""
     tmp_dir = tmp_path_factory.mktemp("segy")
     return tmp_dir / "teapot_roundtrip.segy"
+
+
+@pytest.fixture(scope="class")
+def empty_mdio_dir(tmp_path_factory: pytest.TempPathFactory) -> Path:
+    """Make a temp file for empty MDIO testing."""
+    return tmp_path_factory.mktemp(r"empty_mdio_dir")

tests/integration/test_import_streamer_grid_overrides.py

@@ -39,7 +39,7 @@ class TestImport4DNonReg:  # pragma: no cover - tests is skipped
     def test_import_4d_segy(  # noqa: PLR0913
         self,
         segy_mock_4d_shots: dict[StreamerShotGeometryType, Path],
-        zarr_tmp: Path,
+        mdio_4d_tmp: Path,
         grid_override: dict[str, Any],
         chan_header_type: StreamerShotGeometryType,
     ) -> None:
@@ -51,7 +51,7 @@ def test_import_4d_segy(  # noqa: PLR0913
             segy_spec=segy_spec,
             mdio_template=TemplateRegistry().get("PreStackShotGathers3DTime"),
             input_path=segy_path,
-            output_path=zarr_tmp,
+            output_path=mdio_4d_tmp,
             overwrite=True,
             grid_overrides=grid_override,
         )
@@ -62,7 +62,7 @@ def test_import_4d_segy(  # noqa: PLR0913
         cables = [0, 101, 201, 301]
         receivers_per_cable = [1, 5, 7, 5]
 
-        ds = open_mdio(zarr_tmp)
+        ds = open_mdio(mdio_4d_tmp)
 
         assert ds["segy_file_header"].attrs["binaryHeader"]["samples_per_trace"] == num_samples
         assert ds.attrs["attributes"]["gridOverrides"] == grid_override
@@ -86,7 +86,7 @@ class TestImport4D:
     def test_import_4d_segy(  # noqa: PLR0913
         self,
         segy_mock_4d_shots: dict[StreamerShotGeometryType, Path],
-        zarr_tmp: Path,
+        mdio_4d_tmp: Path,
         grid_override: dict[str, Any],
         chan_header_type: StreamerShotGeometryType,
     ) -> None:
@@ -98,7 +98,7 @@ def test_import_4d_segy(  # noqa: PLR0913
             segy_spec=segy_spec,
             mdio_template=TemplateRegistry().get("PreStackShotGathers3DTime"),
             input_path=segy_path,
-            output_path=zarr_tmp,
+            output_path=mdio_4d_tmp,
             overwrite=True,
             grid_overrides=grid_override,
         )
@@ -109,7 +109,7 @@ def test_import_4d_segy(  # noqa: PLR0913
         cables = [0, 101, 201, 301]
         receivers_per_cable = [1, 5, 7, 5]
 
-        ds = open_mdio(zarr_tmp)
+        ds = open_mdio(mdio_4d_tmp)
 
         assert ds["segy_file_header"].attrs["binaryHeader"]["samples_per_trace"] == num_samples
         assert ds.attrs["attributes"].get("gridOverrides", None) == grid_override  # may not exist, so default=None
@@ -134,7 +134,7 @@ class TestImport4DSparse:
     def test_import_4d_segy(  # noqa: PLR0913
         self,
         segy_mock_4d_shots: dict[StreamerShotGeometryType, Path],
-        zarr_tmp: Path,
+        mdio_4d_tmp: Path,
         chan_header_type: StreamerShotGeometryType,
     ) -> None:
         """Test importing a SEG-Y file to MDIO."""
@@ -148,7 +148,7 @@ def test_import_4d_segy(  # noqa: PLR0913
                 segy_spec=segy_spec,
                 mdio_template=TemplateRegistry().get("PreStackShotGathers3DTime"),
                 input_path=segy_path,
-                output_path=zarr_tmp,
+                output_path=mdio_4d_tmp,
                 overwrite=True,
             )
 
@@ -167,7 +167,7 @@ class TestImport6D:  # pragma: no cover - tests is skipped
     def test_import_6d_segy(  # noqa: PLR0913
         self,
         segy_mock_4d_shots: dict[StreamerShotGeometryType, Path],
-        zarr_tmp: Path,
+        mdio_4d_tmp: Path,
         grid_override: dict[str, Any],
         chan_header_type: StreamerShotGeometryType,
     ) -> None:
@@ -179,7 +179,7 @@ def test_import_6d_segy(  # noqa: PLR0913
             segy_spec=segy_spec,
             mdio_template=TemplateRegistry().get("XYZ"),  # Placeholder for the template
             input_path=segy_path,
-            output_path=zarr_tmp,
+            output_path=mdio_4d_tmp,
             overwrite=True,
             grid_overrides=grid_override,
         )
@@ -195,7 +195,7 @@ def test_import_6d_segy(  # noqa: PLR0913
         guns = [1, 2]
         receivers_per_cable = [1, 5, 7, 5]
 
-        ds = open_mdio(zarr_tmp)
+        ds = open_mdio(mdio_4d_tmp)
 
         xrt.assert_duckarray_equal(ds["gun"], guns)
         xrt.assert_duckarray_equal(ds["shot_point"], shots)