modosaic.services.experiment

modosaic.services.experiment

ExperimentService

ExperimentService(root='experiments', experiment_name=None)

Persist generated artifacts below one experiment directory.

Attributes:

Name	Type	Description
experiment_path	Path	Directory where this run writes artifacts.

Initialize an experiment folder.

Parameters:

Name	Type	Description	Default
root	str | Path	Parent directory for experiments.	'experiments'
experiment_name	str | None	Optional run directory name. A timestamp is used when omitted.	None

Source code in modosaic/services/experiment.py

def __init__(
        self,
        root: str | Path = "experiments",
        experiment_name: str | None = None,
):
    """Initialize an experiment folder.

    Args:
        root: Parent directory for experiments.
        experiment_name: Optional run directory name. A timestamp is used
            when omitted.
    """
    current_date = experiment_name or datetime.now().strftime("%Y%m%d-%H%M%S")
    self.experiment_path = Path(root) / current_date
    self.experiment_path.mkdir(parents=True, exist_ok=True)
    logger.debug(f"Experiment artifacts will be saved under {self.experiment_path}")

save_array_artifact

save_array_artifact(relative_path, array)

Save a NumPy array with numpy.save.

Source code in modosaic/services/experiment.py

def save_array_artifact(self, relative_path: str | Path, array: np.ndarray) -> Path:
    """Save a NumPy array with `numpy.save`."""
    artifact_path = self._artifact_path(relative_path)
    artifact_path.parent.mkdir(parents=True, exist_ok=True)
    with artifact_path.open("wb") as file:
        np.save(file, array)
    logger.debug(f"Saved array artifact to {artifact_path}")
    return artifact_path

save_array_collection_artifact

save_array_collection_artifact(relative_path, arrays)

Save an array collection with numpy.savez.

Source code in modosaic/services/experiment.py

def save_array_collection_artifact(
        self,
        relative_path: str | Path,
        arrays: Sequence[np.ndarray] | Mapping[str, np.ndarray],
) -> Path:
    """Save an array collection with `numpy.savez`."""
    artifact_path = self._artifact_path(relative_path)
    artifact_path.parent.mkdir(parents=True, exist_ok=True)
    with artifact_path.open("wb") as file:
        if isinstance(arrays, Mapping):
            np.savez(file, **arrays)
        else:
            np.savez(file, *arrays)
    logger.debug(f"Saved array collection artifact to {artifact_path}")
    return artifact_path

save_artifact

save_artifact(artifact)

Save one artifact using its declared kind.

Parameters:

Name	Type	Description	Default
artifact	ExperimentArtifact[Any]	Artifact to persist.	required

Returns:

Type	Description
Path	Path written to disk.

Raises:

Type	Description
ValueError	If the artifact kind is unsupported.

Source code in modosaic/services/experiment.py

def save_artifact(self, artifact: ExperimentArtifact[Any]) -> Path:
    """Save one artifact using its declared kind.

    Args:
        artifact: Artifact to persist.

    Returns:
        Path written to disk.

    Raises:
        ValueError: If the artifact kind is unsupported.
    """
    logger.debug(f"Saving {artifact.kind} artifact to {artifact.relative_path}")
    match artifact.kind:
        case ExperimentArtifactKind.TEXT:
            return self.save_text_artifact(artifact.relative_path, artifact.payload)
        case ExperimentArtifactKind.ARRAY:
            return self.save_array_artifact(artifact.relative_path, artifact.payload)
        case ExperimentArtifactKind.ARRAY_COLLECTION:
            return self.save_array_collection_artifact(artifact.relative_path, artifact.payload)
        case ExperimentArtifactKind.IMAGE:
            return self.save_image_artifact(artifact.relative_path, artifact.payload)
        case ExperimentArtifactKind.JSON:
            return self.save_json_artifact(artifact.relative_path, artifact.payload)
        case ExperimentArtifactKind.BYTES:
            return self.save_bytes_artifact(artifact.relative_path, artifact.payload)
        case _:
            raise ValueError(f"Unsupported experiment artifact kind: {artifact.kind}")

save_artifacts

save_artifacts(artifacts)

Save many artifacts.

Parameters:

Name	Type	Description	Default
artifacts	Iterable[ExperimentArtifact[Any]]	Artifact objects to persist.	required

Returns:

Type	Description
list[Path]	Paths written to disk.

Source code in modosaic/services/experiment.py

def save_artifacts(self, artifacts: Iterable[ExperimentArtifact[Any]]) -> list[Path]:
    """Save many artifacts.

    Args:
        artifacts: Artifact objects to persist.

    Returns:
        Paths written to disk.
    """
    return [
        self.save_artifact(artifact)
        for artifact in artifacts
    ]

save_bytes_artifact

save_bytes_artifact(relative_path, payload)

Save raw bytes below the experiment directory.

Source code in modosaic/services/experiment.py

def save_bytes_artifact(self, relative_path: str | Path, payload: bytes) -> Path:
    """Save raw bytes below the experiment directory."""
    artifact_path = self._artifact_path(relative_path)
    artifact_path.parent.mkdir(parents=True, exist_ok=True)
    artifact_path.write_bytes(payload)
    logger.debug(f"Saved bytes artifact to {artifact_path}")
    return artifact_path

save_depth

save_depth(depth, depth_img)

Save legacy depth array and preview image artifacts.

Source code in modosaic/services/experiment.py

def save_depth(self, depth: np.ndarray, depth_img: Image) -> list[Path]:
    """Save legacy depth array and preview image artifacts."""
    depth_path = Path("depth")

    return [
        self.save_array_artifact(depth_path / "depth.npy", depth),
        self.save_image_artifact(depth_path / "depth.png", depth_img),
    ]

save_image_artifact

save_image_artifact(relative_path, image)

Save a PIL image below the experiment directory.

Source code in modosaic/services/experiment.py

def save_image_artifact(self, relative_path: str | Path, image: Image) -> Path:
    """Save a PIL image below the experiment directory."""
    artifact_path = self._artifact_path(relative_path)
    artifact_path.parent.mkdir(parents=True, exist_ok=True)
    image.save(artifact_path)
    logger.debug(f"Saved image artifact to {artifact_path}")
    return artifact_path

save_json_artifact

save_json_artifact(relative_path, payload)

Save a JSON-serializable payload below the experiment directory.

Source code in modosaic/services/experiment.py

def save_json_artifact(self, relative_path: str | Path, payload: Any) -> Path:
    """Save a JSON-serializable payload below the experiment directory."""
    artifact_path = self._artifact_path(relative_path)
    artifact_path.parent.mkdir(parents=True, exist_ok=True)
    artifact_path.write_text(
        json.dumps(payload, default=self._json_default, indent=2, sort_keys=True),
        encoding="utf-8",
    )
    logger.debug(f"Saved JSON artifact to {artifact_path}")
    return artifact_path

save_normals

save_normals(normals, normal_img)

Save legacy normals array and preview image artifacts.

Source code in modosaic/services/experiment.py

def save_normals(self, normals: np.ndarray, normal_img: Image) -> list[Path]:
    """Save legacy normals array and preview image artifacts."""
    normals_path = Path("normals")

    return [
        self.save_array_artifact(normals_path / "normals.npy", normals),
        self.save_image_artifact(normals_path / "normals.png", normal_img),
    ]

save_segmentation_masks

save_segmentation_masks(segmentation_masks, segmentation_masks_img)

Save legacy segmentation mask arrays and preview image artifacts.

Source code in modosaic/services/experiment.py

def save_segmentation_masks(
        self,
        segmentation_masks: list[np.ndarray],
        segmentation_masks_img: Image,
) -> list[Path]:
    """Save legacy segmentation mask arrays and preview image artifacts."""
    segmentation_masks_path = Path("segmentation_masks")

    return [
        self.save_array_collection_artifact(
            segmentation_masks_path / "segmentation_masks.npz",
            segmentation_masks,
        ),
        self.save_image_artifact(
            segmentation_masks_path / "segmentation_masks.png",
            segmentation_masks_img,
        ),
    ]

save_text

save_text(text_caption)

Save a legacy caption artifact under text/result.txt.

Source code in modosaic/services/experiment.py

def save_text(self, text_caption: str) -> Path:
    """Save a legacy caption artifact under `text/result.txt`."""
    return self.save_text_artifact("text/result.txt", text_caption)

save_text_artifact

save_text_artifact(relative_path, text)

Save UTF-8 text below the experiment directory.

Source code in modosaic/services/experiment.py

def save_text_artifact(self, relative_path: str | Path, text: str) -> Path:
    """Save UTF-8 text below the experiment directory."""
    artifact_path = self._artifact_path(relative_path)
    artifact_path.parent.mkdir(parents=True, exist_ok=True)
    artifact_path.write_text(text, encoding="utf-8")
    logger.debug(f"Saved text artifact to {artifact_path}")
    return artifact_path