dolphin 0.22.0__py3-none-any.whl

dolphin/__init__.py

@@ -0,0 +1,9 @@
+# flake8: noqa
+# version.py is autogenerated by setuptools_scm
+from dolphin._version import version as __version__
+
+from ._log import *
+from ._show_versions import *
+from ._types import *
+from .goldstein import goldstein
+from .interpolation import interpolate

dolphin/__main__.py

@@ -0,0 +1,9 @@
+"""Main module to provide command line interface to the workflows."""
+
+import sys
+
+from .cli import main
+
+# https://docs.python.org/3/library/__main__.html#packaging-considerations
+# allows `python -m dolphin` to work
+sys.exit(main())

dolphin/_cli_timeseries.py

@@ -0,0 +1,144 @@
+import argparse
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from dolphin.workflows import CallFunc
+
+if TYPE_CHECKING:
+    _SubparserType = argparse._SubParsersAction[argparse.ArgumentParser]
+else:
+    _SubparserType = Any
+
+
+def get_parser(subparser=None, subcommand_name="timeseries") -> argparse.ArgumentParser:
+    """Set up the command line interface."""
+    metadata = {
+        "description": "Create a configuration file for a displacement workflow.",
+        "formatter_class": argparse.ArgumentDefaultsHelpFormatter,
+        # https://docs.python.org/3/library/argparse.html#fromfile-prefix-chars
+        "fromfile_prefix_chars": "@",
+    }
+    if subparser:
+        # Used by the subparser to make a nested command line interface
+        parser = subparser.add_parser(subcommand_name, **metadata)
+    else:
+        parser = argparse.ArgumentParser(**metadata)  # type: ignore[arg-type]
+
+    # parser._action_groups.pop()
+    parser.add_argument(
+        "-o",
+        "--output-dir",
+        default=Path(),
+        help="Path to output directory to store results",
+    )
+    parser.add_argument(
+        "--unwrapped-paths",
+        nargs=argparse.ZERO_OR_MORE,
+        help=(
+            "List the paths of all unwrapped interferograms. Can pass a "
+            "newline delimited file with @ifg_filelist.txt"
+        ),
+    )
+    parser.add_argument(
+        "--conncomp-paths",
+        nargs=argparse.ZERO_OR_MORE,
+        help=(
+            "List the paths of all connected component files. Can pass a "
+            "newline delimited file with @conncomp_filelist.txt"
+        ),
+    )
+    parser.add_argument(
+        "--corr-paths",
+        nargs=argparse.ZERO_OR_MORE,
+        help=(
+            "List the paths of all correlation files. Can pass a newline delimited"
+            " file with @cor_filelist.txt"
+        ),
+    )
+    parser.add_argument(
+        "--condition-file",
+        help=(
+            "A file with the same size as each raster, like amplitude dispersion or"
+            "temporal coherence to find reference point. default: amplitude dispersion"
+        ),
+    )
+    parser.add_argument(
+        "--condition",
+        type=CallFunc,
+        default=CallFunc.MIN,
+        help=(
+            "A condition to apply to condition file to find the reference point"
+            "Options are [min, max]. default=min"
+        ),
+    )
+    parser.add_argument(
+        "--num-threads",
+        type=int,
+        default=5,
+        help="Number of threads for the inversion",
+    )
+    parser.add_argument(
+        "--run-velocity",
+        action="store_true",
+        help="Run the velocity estimation from the phase time series",
+    )
+    parser.add_argument(
+        "--reference-point",
+        type=int,
+        nargs=2,
+        metavar=("ROW", "COL"),
+        default=(-1, -1),
+        help=(
+            "Reference point (row, col) used if performing a time series inversion. "
+            "If not provided, a point will be selected from a consistent connected "
+            "component with low amplitude dispersion or high temporal coherence."
+        ),
+    )
+    parser.add_argument(
+        "--correlation-threshold",
+        type=range_limited_float_type,
+        default=0.2,
+        metavar="[0-1]",
+        help="Pixels with correlation below this value will be masked out.",
+    )
+
+    parser.set_defaults(run_func=_run_timeseries)
+
+    return parser
+
+
+def range_limited_float_type(arg):
+    """Type function for argparse - a float within some predefined bounds."""
+    try:
+        f = float(arg)
+    except ValueError as err:
+        raise argparse.ArgumentTypeError("Must be a floating point number") from err
+    if f < 0 or f > 1:
+        raise argparse.ArgumentTypeError(
+            "Argument must be < " + str(1) + "and > " + str(0)
+        )
+    return f
+
+
+def _run_timeseries(*args, **kwargs):
+    """Run `dolphin.timeseries.run`.
+
+    Wrapper for the dolphin.timeseries to invert and create velocity.
+    """
+    from dolphin import timeseries
+
+    return timeseries.run(*args, **kwargs)
+
+
+def main(args=None):
+    """Get the command line arguments for timeseries inversion."""
+    from dolphin import timeseries
+
+    parser = get_parser()
+    parsed_args = parser.parse_args(args)
+
+    timeseries.run(**vars(parsed_args))
+
+
+if __name__ == "__main__":
+    main()

dolphin/_cli_unwrap.py

@@ -0,0 +1,150 @@
+import argparse
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from dolphin.workflows.config import UnwrapMethod
+
+if TYPE_CHECKING:
+    _SubparserType = argparse._SubParsersAction[argparse.ArgumentParser]
+else:
+    _SubparserType = Any
+
+
+def get_parser(subparser=None, subcommand_name="unwrap") -> argparse.ArgumentParser:
+    """Set up the command line interface."""
+    metadata = {
+        "description": "Create a configuration file for a displacement workflow.",
+        "formatter_class": argparse.ArgumentDefaultsHelpFormatter,
+        # https://docs.python.org/3/library/argparse.html#fromfile-prefix-chars
+        "fromfile_prefix_chars": "@",
+    }
+    if subparser:
+        # Used by the subparser to make a nested command line interface
+        parser = subparser.add_parser(subcommand_name, **metadata)
+    else:
+        parser = argparse.ArgumentParser(**metadata)  # type: ignore[arg-type]
+
+    # parser._action_groups.pop()
+    parser.add_argument(
+        "-o",
+        "--output-path",
+        default=Path(),
+        help="Path to output directory to store results",
+    )
+    # Get Inputs from the command line
+    inputs = parser.add_argument_group("Input options")
+    inputs.add_argument(
+        "--ifg-filenames",
+        nargs=argparse.ZERO_OR_MORE,
+        help=(
+            "List the paths of all ifg files to include. Can pass a newline delimited"
+            " file with @ifg_filelist.txt"
+        ),
+    )
+    inputs.add_argument(
+        "--cor-filenames",
+        nargs=argparse.ZERO_OR_MORE,
+        help=(
+            "List the paths of all ifg files to include. Can pass a newline delimited"
+            " file with @cor_filelist.txt"
+        ),
+    )
+    inputs.add_argument(
+        "--mask-filename",
+        help=(
+            "Path to Byte mask file used to ignore low correlation/bad data (e.g water"
+            " mask). Convention is 0 for no data/invalid, and 1 for good data."
+        ),
+    )
+    inputs.add_argument(
+        "--temp-coh-filename",
+        help="Path to temporal coherence file from phase linking",
+    )
+    parser.add_argument(
+        "--nlooks",
+        type=int,
+        help="Effective number of looks used to form correlation",
+    )
+
+    parser.add_argument(
+        "--max-jobs",
+        type=int,
+        default=1,
+        help="Number of parallel files to unwrap",
+    )
+
+    algorithm_opts = parser.add_argument_group("Algorithm options")
+    algorithm_opts.add_argument(
+        "--unwrap-method",
+        type=UnwrapMethod,
+        choices=[m.value for m in UnwrapMethod],
+        default=UnwrapMethod.SNAPHU.value,
+        help="Choice of unwrapping algorithm to use.",
+    )
+    algorithm_opts.add_argument(
+        "--run-goldstein",
+        action="store_true",
+        help="Run Goldstein filter before unwrapping.",
+    )
+    algorithm_opts.add_argument(
+        "--run-interpolation",
+        action="store_true",
+        help="Run interpolation before unwrapping.",
+    )
+
+    spurt_opts = parser.add_argument_group("Spurt options")
+    spurt_opts.add_argument(
+        "--temp-coh-threshold",
+        type=float,
+        help="Cutoff on temporal_coherence raster to choose pixels for unwrapping.",
+    )
+
+    tophu_opts = parser.add_argument_group("Tophu options")
+    # Add ability for downsampling/tiling with tophu
+    tophu_opts.add_argument(
+        "--ntiles",
+        type=int,
+        nargs=2,
+        metavar=("ROW_TILES", "COL_TILES"),
+        default=(1, 1),
+        help=(
+            "(using tophu) Split the interferograms into this number of tiles along the"
+            " (row, col) axis."
+        ),
+    )
+    tophu_opts.add_argument(
+        "--downsample-factor",
+        type=int,
+        nargs=2,
+        default=(1, 1),
+        help=(
+            "(using tophu) Downsample the interferograms by this factor "
+            " during multiresolution unwrapping."
+        ),
+    )
+    parser.set_defaults(run_func=_run_unwrap)
+
+    return parser
+
+
+def _run_unwrap(*args, **kwargs):
+    """Run `dolphin.unwrap.run`.
+
+    Wrapper for the dolphin.unwrap to delay import time.
+    """
+    from dolphin import unwrap
+
+    return unwrap.run(*args, **kwargs)
+
+
+def main(args=None):
+    """Get the command line arguments and unwrap files."""
+    from dolphin import unwrap
+
+    parser = get_parser()
+    parsed_args = parser.parse_args(args)
+    unwrap.run(**vars(parsed_args))
+
+
+if __name__ == "__main__":
+    main()

dolphin/_decorators.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import functools
+import logging
+import shutil
+import tempfile
+from pathlib import Path
+from typing import Any, Callable
+
+logger = logging.getLogger(__name__)
+
+__all__ = [
+    "atomic_output",
+]
+
+
+def atomic_output(
+    output_arg: str = "output_file",
+    is_dir: bool = False,
+    use_tmp: bool = False,
+    overwrite: bool = False,
+) -> Callable:
+    """Use a temporary file/directory for the `output_arg` until the function finishes.
+
+    Decorator is used on a function which writes to an output file/directory in blocks.
+    If the function were interrupted, the file/directory would be partially complete.
+
+    This decorator replaces the final output name with a temp file/dir, and then
+    renames the temp file/dir to the final name after the function finishes.
+
+    Note that when `is_dir=True`, `output_arg` can be a directory (if multiple files
+    are being written to). In this case, the entire directory is temporary, and
+    renamed after the function finishes.
+
+    Parameters
+    ----------
+    output_arg : str, optional
+        The name of the argument to replace, by default 'output_file'
+    is_dir : bool, default = False
+        If `True`, the output argument is a directory, not a file
+    use_tmp : bool, default = False
+        If `False`, uses the parent directory of the desired output, with
+        a random suffix added to the name to distinguish from actual output.
+        If `True`, uses the `/tmp` directory (or wherever the default is
+        for the `tempfile` module).
+    overwrite : bool, default = False
+        Overwrite an existing file.
+        If `False` raises `FileExistsError` if the file already exists.
+
+    Returns
+    -------
+    Callable
+        The decorated function
+
+    Raises
+    ------
+    FileExistsError
+        if the file for `output_arg` already exists (if out_dir=False), or
+        if the directory at `output_arg` exists and is non-empty.
+
+    Notes
+    -----
+    The output at `output_arg` *must not* exist already, or the decorator will error
+    (though if `is_dir=True`, it is allowed to be an empty directory).
+    The function being decorated *must* be called with keyword args for `output_arg`.
+
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs) -> Any:
+            # Extract the output file path
+            if kwargs.get(output_arg):
+                final_out_name = kwargs[output_arg]
+            else:
+                msg = (
+                    f"Argument {output_arg} not passed to function {func.__name__}:"
+                    f" {kwargs}"
+                )
+                raise FileExistsError(msg)
+
+            final_path = Path(final_out_name)
+            # Make sure the desired final output doesn't already exist
+            _raise_if_exists(final_path, is_dir=is_dir, overwrite=overwrite)
+            # None means that tempfile will use /tmp
+            tmp_dir = final_path.parent if not use_tmp else None
+
+            # Make the tempfile start the same as the desired output
+            prefix = final_path.name
+            if is_dir:
+                # Create a temporary directory
+                temp_path = tempfile.mkdtemp(dir=tmp_dir, prefix=prefix)
+            else:
+                # Create a temporary file
+                suffix = final_path.suffix
+                _, temp_path = tempfile.mkstemp(
+                    dir=tmp_dir, prefix=prefix, suffix=suffix
+                )
+            logger.debug("Writing to temp file %s instead of %s", temp_path, final_path)
+
+            try:
+                # Replace the output file path with the temp file
+                # It would be like this if we only allows keyword:
+                kwargs[output_arg] = temp_path
+                # Execute the original function
+                result = func(*args, **kwargs)
+                # Move the temp file to the final location
+                logger.debug("Moving %s to %s", temp_path, final_path)
+                shutil.move(temp_path, final_path)
+
+                return result
+            finally:
+                logger.debug("Cleaning up temp file %s", temp_path)
+                # Different cleanup is needed
+                if is_dir:
+                    shutil.rmtree(temp_path, ignore_errors=True)
+                else:
+                    Path(temp_path).unlink(missing_ok=True)
+
+        return wrapper
+
+    return decorator
+
+
+def _raise_if_exists(final_path: Path, is_dir: bool, overwrite: bool):
+    msg = f"{final_path} already exists"
+    if final_path.exists():
+        logger.debug(f"{final_path} already exists")
+        if overwrite:
+            if final_path.is_dir():
+                shutil.rmtree(final_path)
+            else:
+                final_path.unlink()
+            return
+
+        if is_dir and final_path.is_dir():
+            # We can work with an empty directory
+            try:
+                final_path.rmdir()
+            except OSError as e:
+                err_msg = str(e)
+                if "Directory not empty" in err_msg:
+                    raise FileExistsError(msg) from e
+                else:
+                    # Some other error we don't know
+                    raise
+        else:
+            raise FileExistsError(msg)

dolphin/_log.py

@@ -0,0 +1,137 @@
+import json
+import logging
+import logging.config
+import os
+import sys
+import time
+from collections.abc import Callable
+from datetime import datetime, timezone
+from functools import wraps
+from pathlib import Path
+
+from dolphin._types import P, PathOrStr, T
+
+LOG_RECORD_BUILTIN_ATTRS = {
+    "args",
+    "asctime",
+    "created",
+    "exc_info",
+    "exc_text",
+    "filename",
+    "funcName",
+    "levelname",
+    "levelno",
+    "lineno",
+    "module",
+    "msecs",
+    "message",
+    "msg",
+    "name",
+    "pathname",
+    "process",
+    "processName",
+    "relativeCreated",
+    "stack_info",
+    "thread",
+    "threadName",
+    "taskName",
+}
+__all__ = ["log_runtime"]
+
+
+def setup_logging(debug: bool = False, filename: PathOrStr | None = None):
+    config_file = Path(__file__).parent / Path("log-config.json")
+    with open(config_file) as f_in:
+        config = json.load(f_in)
+
+    if debug:
+        config["loggers"]["dolphin"]["level"] = "DEBUG"
+
+    if filename:
+        config["loggers"]["dolphin"]["handlers"].append("file")
+        config["handlers"]["file"]["filename"] = os.fspath(filename)
+        Path(filename).parent.mkdir(exist_ok=True, parents=True)
+
+    if "filename" not in config["handlers"]["file"]:
+        # We never passed in a filename: don't log to a file
+        config["handlers"].pop("file")
+
+    logging.config.dictConfig(config)
+    # Temp work around for tqdm on py312
+    if sys.version_info.major == 3 and sys.version_info.minor == 12:
+        os.environ["TQDM_DISABLE"] = "1"
+
+
+def log_runtime(f: Callable[P, T]) -> Callable[P, T]:
+    """Decorate a function to time how long it takes to run.
+
+    Usage
+    -----
+    @log_runtime
+    def test_func():
+        return 2 + 4
+    """
+    logger = logging.getLogger(__name__)
+
+    @wraps(f)
+    def wrapper(*args: P.args, **kwargs: P.kwargs):
+        t1 = time.time()
+
+        result = f(*args, **kwargs)
+
+        t2 = time.time()
+        elapsed_seconds = t2 - t1
+        elapsed_minutes = elapsed_seconds / 60.0
+        time_string = (
+            f"Total elapsed time for {f.__module__}.{f.__name__} : "
+            f"{elapsed_minutes:.2f} minutes ({elapsed_seconds:.2f} seconds)"
+        )
+
+        logger.info(time_string)
+
+        return result
+
+    return wrapper
+
+
+class JSONFormatter(logging.Formatter):
+    def __init__(
+        self,
+        *,
+        fmt_keys: dict[str, str] | None = None,
+    ):
+        super().__init__()
+        self.fmt_keys = fmt_keys if fmt_keys is not None else {}
+
+    def format(self, record: logging.LogRecord) -> str:
+        message = self._prepare_log_dict(record)
+        return json.dumps(message, default=str)
+
+    def _prepare_log_dict(self, record: logging.LogRecord):
+        always_fields = {
+            "message": record.getMessage(),
+            "timestamp": datetime.fromtimestamp(
+                record.created, tz=timezone.utc
+            ).isoformat(),
+        }
+        if record.exc_info is not None:
+            always_fields["exc_info"] = self.formatException(record.exc_info)
+
+        if record.stack_info is not None:
+            always_fields["stack_info"] = self.formatStack(record.stack_info)
+
+        message = {
+            key: (
+                msg_val
+                if (msg_val := always_fields.pop(val, None)) is not None
+                else getattr(record, val)
+            )
+            for key, val in self.fmt_keys.items()
+        }
+        message.update(always_fields)
+
+        for key, val in record.__dict__.items():
+            if key not in LOG_RECORD_BUILTIN_ATTRS:
+                message[key] = val
+
+        return message