Skip to content

DSS Modules

Classes for reading and writing HEC-DSS files.

RasDss

Read HEC-DSS files for boundary condition extraction and write DSS time-series or gridded precipitation records.

write_grid_timeseries() already supports direct array-to-grid writing using HEC Monolith. write_precip_grid_arrays() is an optional native alternative; pydsstools is not required for existing Monolith users.

Methods

write_precip_grid_arrays(dss_file, pathname, data, interval_bounds, *, transform, crs, units, nodata=None, overwrite=False)

Write NumPy interval-depth arrays directly to DSS7 specified-time grids using optional ras-commander[dss-native] (gyanz/pydsstools). Requires no Java/Vortex. Windows still requires the Visual C runtime and UCRT; a compatible wheel does not require a compiler. Tested pydsstools 3.1.0 provides Windows x64 wheels for CPython 3.9–3.13, not 3.14. See the runtime and Python dependency details before selecting this backend. data is (time, row, column) with row zero north. Provide n_times+1 timezone-naive whole-minute boundaries, projected CRS, square north-up Affine transform, and explicit inches or mm units. Records use PER-CUM depth. No reprojection or numeric unit conversion is performed. NaN/masked values and nodata become native DSS missing values. Existing files fail unless overwrite=True, which replaces the whole file after writing and readback.

Returns exact pathnames with D/E interval start/end times. See Direct precipitation arrays for an example and compatibility limits.

get_catalog(dss_file)

Get catalog of all paths in a DSS file.

Parameters: - dss_file (str|Path): Path to DSS file

Returns: DataFrame with one pathname column containing full DSS paths

read_timeseries(dss_file, pathname)

Read a single time series from DSS.

Parameters: - dss_file (str|Path): Path to DSS file - pathname (str): Full DSS pathname

Returns: DataFrame with datetime index and value column

read_multiple_timeseries(dss_file, pathnames)

Read multiple time series at once.

Parameters: - dss_file (str|Path): Path to DSS file - pathnames (list): List of DSS pathnames

Returns: Dict of {pathname: DataFrame}

read_paired_data(dss_file, pathname, *, ignore_d_part=True, dtype="stored")

Read one paired-data record with every curve.

Returns: DataFrame indexed by the ordinates ("ordinate"), one column per curve, stored precision by default (float32 PD, float64 PDD). attrs carry pathname, record_pathname, dss_file, record_type, dss_version, stored_dtype, n_ordinates, n_curves, x_parameter, y_parameter, x_units, x_type, y_units, y_type, labels, x_precision, y_precision and time_zone. Raises DssPathnameNotFoundError or DssRecordTypeError on every backend. See the canonical DSS API.

read_grid(dss_file, pathname, *, allow_unqualified_native=False)

Read one exact grid record as a dictionary (data float32, row zero south, row_order="south_up"). Under backend="native" it raises DssCapabilityError unless the installed ras-commander-fast-dss advertises qualified grid CRS strings (grid_srs_monolith_parity) or allow_unqualified_native=True is passed.

get_capabilities()

DataFrame of operation, java, native, shadow and note: which backend supports each public DSS operation.

write_paired_data(dss_file, pathname, x_values, y_values=None, x_units=None, y_units=None, x_type=None, y_type=None, labels=None, create_if_missing=True, *, x_precision=None, y_precision=None, value_type="auto", dss_version=None)

Write one paired-data record with one or more curves, as a new record or a whole replacement.

Parameters: - dss_file (str|Path): Path to DSS file - pathname (str): DSS pathname with exactly six parts - x_values (array|DataFrame|Series): The ordinates, or the frame from read_paired_data (then omit y_values; its attrs supply metadata left as None) - y_values (array): The curves: 1-D, or 2-D with shape (len(x_values), n_curves) - x_units, y_units, x_type, y_type (str): Units and axis types. Blank if None and not in attrs - labels (list): Curve names, one per curve. Default: a frame's string column names - create_if_missing (bool): Create a missing file, default True - x_precision, y_precision (int): Display precision, both -1 or both 0-9 - value_type (str): "auto" (float32 input stores PD, type 200; anything else PDD, type 205), "float" or "double" - dss_version (int): 6 or 7 for a new file; an existing file must match

Returns: None. A failed write raises. See Writes for what the native writer refuses.

write_timeseries(dss_file, pathname, times, values, ..., dss_version=None)

Write a single time series to DSS.

Parameters: - dss_file (str|Path): Path to DSS file - pathname (str): Full DSS pathname - times (list|DatetimeIndex|ndarray): Datetime values - values (list|ndarray): Numeric values - units (str): Units, default CFS - data_type (str): DSS data type, default INST-VAL - create_if_missing (bool): Create a missing file, default True - dss_version (int|None): Keyword-only DSS 6 or DSS 7 selection for new files. The default None preserves the bridge's current default. An explicit value must match an existing file.

Datetime values must be timezone-naive and aligned exactly to whole minutes. Callers with timezone-aware data must explicitly convert it to the intended HEC-RAS model clock and remove timezone metadata before writing. For simulations spanning a daylight-saving fallback, choose a fixed-offset or otherwise strictly increasing model clock; merely stripping timezone metadata from a repeated local hour creates ambiguous duplicate model times.

Backends: java writes through HEC Monolith. native writes through ras-commander-fast-dss (no JVM; DssCapabilityError when the wheel has no writers) and keeps the same file, version and missing-value rules. shadow writes with Java and compares a native repeat on a temporary copy. The native writer refuses some input that Java truncates (see Writes).

repair(src, dest, *, sync=None)

Copy the readable records of a damaged DSS7 file into a new DSS7 file through ras-commander-fast-dss 0.1.1 or later (sync= from 0.1.2), on every backend (there is no Java equivalent). src is opened read-only; dest must not exist. A partial recovery is still published, so always check complete and not_copied in the returned dict. See Interrupted writes and repair.

Parameters: - src (str|Path): Existing DSS7 file - dest (str|Path): New file to create - sync (keyword, optional): The engine's flush policy ("end", "step", "none", True or False), passed unchanged; None leaves the engine default

Returns: The engine's result dict (records_copied, not_copied, ledger, complete, ...). Raises FileExistsError if dest exists, ImportError without ras-commander-fast-dss and DssCapabilityError when the installed engine has no repair.

get_file_version(dss_file)

Return the HEC-DSS major file version. Uses the selected backend; a non-DSS file raises DssInvalidFileError (a ValueError).

Parameters: - dss_file (str|Path): Existing DSS file

Returns: Integer 6 or 7.

write_grid_timeseries(dss_file, pathname, data, times, grid_info, ..., dss_version=None)

Write a time-varying spatial grid series to DSS.

Parameters: - dss_file (str|Path): Path to DSS file - pathname (str): DSS grid pathname template; A/B/C/F are preserved and D/E are replaced per timestep - data (ndarray): Shape (n_times, n_rows, n_cols) - times (list|DatetimeIndex|ndarray): n_times + 1 interval boundaries or n_times interval end times - grid_info (dict): Grid metadata such as cellsize, origin, crs, units, and data_type - create_if_missing (bool): Create a missing file, default True - dss_version (int|None): Keyword-only DSS 6 or DSS 7 selection for new files. The default None preserves the bridge's current default. An explicit value must match an existing file. Explicit DSS6 writes use the Monolith's version-specific safe precipitation-compression base/scale ordering unless those values are supplied in grid_info. The native backend needs no such workaround: it stores compression_base and compression_scale_factor as named (see Writes).

Returns: List of DSS pathnames written.

Grid timestamps must also be timezone-naive. ras-commander does not infer a model timezone or silently convert aware timestamps.

copy_grid_with_zero_tail(source_dss, output_dss, pathname, tail_intervals, ...)

Create a non-destructive DSS grid derivative containing one selected grid family followed by explicit zero-valued intervals.

The intended workflow is to prepare a run-local gridded precipitation or rainfall-excess DSS derivative for a HEC-RAS rain-on-grid scenario. A caller can keep an AORC-like source immutable, optionally express UTC grid timestamps on the model clock with an explicitly chosen shift, optionally rename the forcing family and apply an approved whole-cell origin translation, then append explicit zero-forcing intervals. Those zero intervals allow the model run to continue through post-storm routing or recession after the source rainfall ends.

In the source PR workflow, RasScenario accepted this already-prepared forcing_excess_dss and wired it to Gridded/DSS precipitation. The derivative was prepared upstream; RasScenario did not directly call this method.

This method does not calculate rainfall or rainfall excess, scientifically transpose a storm, reproject, resample, or interpolate grids, infer a time zone, or decide engineering suitability. The caller remains responsible for those scientific and study-specific decisions.

Parameters:

  • source_dss (str|Path): Existing DSS6 or DSS7 source. It is never modified.
  • output_dss (str|Path): Destination derivative. It must differ from the source. An output symlink, junction, or other reparse point is rejected before it can be followed. Only its parent directory is safely resolved; the requested final path component is preserved lexically through publication.
  • pathname (str): Exact A/B/C/F family selector with blank D and E parts, such as /SHG/BASIN/PRECIPITATION///AORC/.
  • tail_intervals (int): Positive number of zero-valued intervals to append.
  • time_shift_minutes (int): Optional signed whole-minute shift applied to every source and tail window.
  • output_pathname (str|None): Optional output A/B/C/F family, also with blank D/E parts. When omitted, the caller selector's A/B/C/F casing is preserved; source selection itself remains case-insensitive and rejects case-ambiguous families.
  • x_shift, y_shift (float): Optional origin translations in the grid's horizontal units. Each must be an exact whole-cell increment.
  • overwrite (bool): If True, atomically replace an existing destination after complete temporary readback. If False, publish atomically with a create-if-absent hard link; a filesystem without hard-link support fails closed and never falls back to replacement.

Returns: A summary dictionary containing DSS version, accepted source SHA-256, source/output coverage, interval, translations, rewritten source paths, and appended paths.

The output always contains only the selected family plus its tail; unrelated source records are not copied. The source DSS major version is preserved. All matched records must form one unambiguous, uniform, contiguous family with consistent shape, spatial reference, resolution, origin, parameter metadata, NoData value and footprint, and compression configuration. Tail cells are zero where the source footprint contains data and remain NoData everywhere else. The safe-rewrite path currently supports Albers/SHG and specified grids; other grid metadata classes fail closed rather than being converted implicitly. Accepted legacy double-leading pathname syntax is canonicalized to the normal single-leading /A/B/C/D/E/F/ form before records are written. D/E parts must use exact minute-granularity DDMMMYYYY:HHMM syntax with English uppercase month tokens. The narrow valid 2400 spelling means next-day midnight; 24:01 through 24:59 are rejected. Native HEC-DSS grid catalogs spell a midnight record end as prior-day 2400 and the same instant as a following record start as next-day 0000. Returned derivative pathnames use this role-specific native spelling, while raw timing and parsed instants must still match exactly.

The method validates the source in a streaming first pass, then rereads and writes one source frame per writer call and reuses one zero frame for the tail. It does not stack the source family or materialize the complete tail in memory. The source file is hashed in chunks before catalog access, after prevalidation, and after the write-read pass. Any detected digest mismatch aborts before publication; these checkpoints are not a continuous file lock.

After writing, the temporary derivative must preserve the source DSS major version and contain the independently derived exact catalog. Every temporary record is then reopened one at a time. Rewritten source frames must match an exact normalized float32 digest (canonical NaN and signed zero), tails must contain exact zero on data cells and the stable source NoData mask, raw timing must match the expected window, and all write-relevant metadata must match the source reference except for the requested mechanical origin translation.

For overwrite=False, hard-link creation is the atomic no-clobber instruction: if another writer wins the final race, FileExistsError is raised and that destination is preserved. Unsupported hard links raise OSError and leave the destination absent. For overwrite=True, same-directory os.replace() is atomic, but the new derivative replaces the old destination's timestamps, permissions/ACL details, hard-link identity, and other file metadata. Because the final output component is not resolved or followed after its initial reparse-point check, a competing entry at that exact name either wins the no-clobber hard-link race or is itself replaced under overwrite=True; the implementation does not redirect publication through that entry to a different target.

Time, pathname, and origin changes are lexical/mechanical metadata transforms, not scientific transformations of the forcing.

Stable failures include FileNotFoundError for a missing source, FileExistsError for no-clobber conflicts, IsADirectoryError for non-file DSS paths, ValueError for unsafe inputs/families/metadata, ImportError when the optional Java bridge is unavailable, OSError for filesystem publication failures, and RuntimeError for source-stability or DSS I/O/readback failures.

Python
result = RasDss.copy_grid_with_zero_tail(
    "source.dss",
    "derivative.dss",
    "/SHG/BASIN/PRECIPITATION///AORC/",
    3,
    time_shift_minutes=-300,
    output_pathname="/SHG/BASIN/PRECIPITATION///AORC-SHIFTED/",
    x_shift=2000,
    y_shift=3000,
)
print(result["appended_pathnames"])

Common SHG precipitation metadata:

Python
grid_info = {
    "cellsize": 2000,
    "origin": (1096000, 1516000),
    "crs": "SHG",
    "units": "mm",
    "data_type": "PER-CUM",
}

extract_boundary_timeseries(boundaries_df, project_dir=None, ras_object=None)

Extract all DSS boundary conditions from a project.

Parameters: - boundaries_df (DataFrame): From ras.boundaries_df - project_dir (str|Path|None): Directory for resolving relative DSS paths - ras_object (RasPrj|None): Project object, passed by keyword

Returns: Copy of the boundary DataFrame with a dss_timeseries column. Unread or unsuccessful entries remain None; inspect logged warnings for missing paths and read failures.

get_info(dss_file)

Get DSS file information.

Parameters: - dss_file (str|Path): Path to DSS file

Returns: Dict with filepath, filename, file size, total pathname count, and a preview of the first five catalog rows.

RasDssGrid

Gridded import and grid tools for DSS files: thin wrappers around the ras_commander_fast_dss.gridded namespace. Every method runs on the optional ras-commander-fast-dss engine, whatever RasDss.backend is, and returns the engine's result unchanged. See Engine-only operations and notebook 732.

Static class for gridded import and grid processing on HEC-DSS files.

Each method is a thin wrapper around the function of the same name in ras_commander_fast_dss.gridded. All methods are static; do not instantiate.

Requires the optional ras-commander-fast-dss package (pip install "ras-commander[dss]"). A method raises ImportError when the package is missing and DssCapabilityError (a NotImplementedError) when the installed version does not provide the operation. RasDss.backend does not select anything here.

The engine plans each run before it writes: a refused run leaves the output untouched. The engine reports where its results differ from HEC-Vortex by design; those notes are in each engine function's documentation.

sync (on the methods that write): the engine's flush policy, passed through unchanged. None (default) states nothing, so the installed engine's own default applies; that default can change between engine releases. With ras-commander-fast-dss 0.1.2 a call that stores several records flushes once, after its last record, by default ("end", or True); "step" flushes at every flush point and "none" (or False) does not flush.

threads of the importers: with 0.1.2 the engine's default (None) uses every core available to the process. The records written have the same pathnames, grid values and metadata as with threads=1; the file bytes can differ, because DSS stores write timestamps.

get_features staticmethod

Python
get_features() -> Dict[str, bool]

Report which gridded feature groups the installed engine provides.

Does not raise when ras-commander-fast-dss is missing (every value is False).

Returns:

Type Description
``dict`` of engine feature name to ``bool``

gridded_import,

Dict[str, bool]

gridded_netcdf, gridded_zarr, gridded_accumulation_window,

Dict[str, bool]

gridded_grib1_stage4, gridded_prism_bil, gridded_snodas,

Dict[str, bool]

gridded_threads_all_cores, gridded_time_tools, grid_tools

Dict[str, bool]

and grid_to_point.

import_gridded staticmethod

Python
import_gridded(inputs: Union[PathLike, Sequence[PathLike]], output: PathLike, *, sync: Optional[Any] = None, **kwargs: Any) -> Any

Import grids from files into a DSS file, one frame at a time.

Parameters:

Name Type Description Default
inputs Union[PathLike, Sequence[PathLike]]

One path or a sequence, read in the order given: GRIB2, NCEP Stage IV GRIB1 (gridded_grib1_stage4), NetCDF (classic and NetCDF-4), HDF5, GeoTIFF (a loose .aux.xml sidecar may set nodata only), ASCII grid, PRISM BIL and *_bil.zip/*_asc.zip/2025 packages (gridded_prism_bil), SNODAS daily tars and .dat members (gridded_snodas), or the folder of a local Zarr v2 store.

required
output PathLike

DSS file to write. It is created when the first record is written.

required
sync Optional[Any]

Flush policy, passed to the engine unchanged (see the class notes).

None
**kwargs Any

Options of ras_commander_fast_dss.gridded.import_gridded, passed unchanged: variable, product, envelope, envelope_crs, shapefile, target_crs (default "SHG"), cell_size (metres, default 2000), method, parts, units (relabels; it does not convert), data_type, version, align, window_rule, duplicates, threads (default every core), progress, bbox, times, snodas_times ("header" default; "vortex" for HEC-Vortex timing), snodas_georeference and the reader limits. SNODAS products without a qualified interpretation are refused unless one of the two snodas_times options is named.

{}

Returns:

Type Description
Any

The engine's ImportResult (output, records, pathnames).

Raises:

Type Description
ImportError

ras-commander-fast-dss is not installed.

DssCapabilityError

The installed engine has no gridded_import.

ValueError

The engine refuses the run (nothing is written).

import_arrays staticmethod

Python
import_arrays(data: Any, output: PathLike, *, times: Sequence[Any], transform: Sequence[float], crs: str, variable: str, source_units: str, sync: Optional[Any] = None, **kwargs: Any) -> Any

Import arrays through the same warp, unit, naming and writer steps as a file.

Parameters:

Name Type Description Default
data Any

Shape (frames, rows, columns), or (rows, columns).

required
output PathLike

DSS file to write.

required
times Sequence[Any]

One per frame: None, an instant, or (start, end).

required
transform Sequence[float]

(origin_x, dx, origin_y, dy); the origin is the outer corner of the first cell, and negative dy means row 0 is north.

required
crs str

"SHG", "HRAP" or WKT of the arrays.

required
variable str

Variable name; it sets the C part.

required
source_units str

Units the cells are in.

required
sync Optional[Any]

Flush policy, passed to the engine unchanged (see the class notes).

None
**kwargs Any

Other ras_commander_fast_dss.gridded.import_arrays options.

{}

Returns:

Type Description
Any

The engine's ImportResult.

Raises:

Type Description
ImportError

ras-commander-fast-dss is not installed.

DssCapabilityError

The installed engine has no gridded_import.

import_zarr staticmethod

Python
import_zarr(inputs: Union[PathLike, Sequence[PathLike]], output: PathLike, *, variable: str, sync: Optional[Any] = None, **kwargs: Any) -> Any

Import a variable of local Zarr v2 stores (for example AORC v1.1) into DSS.

Parameters:

Name Type Description Default
inputs Union[PathLike, Sequence[PathLike]]

One store folder or a sequence of them.

required
output PathLike

DSS file to write.

required
variable str

Variable name (see zarr_variables).

required
sync Optional[Any]

Flush policy, passed to the engine unchanged (see the class notes).

None
**kwargs Any

Other ras_commander_fast_dss.gridded.import_zarr options (bbox, times, envelope, target_crs, cell_size, parts, window_rule, limits, stop, strict, ...).

{}

Returns:

Type Description
Any

The engine's ImportResult.

Raises:

Type Description
ImportError

ras-commander-fast-dss is not installed.

DssCapabilityError

The installed engine has no gridded_zarr.

list_variables staticmethod

Python
list_variables(path: PathLike) -> List[str]

Variables a source file offers, by the names variable= takes.

Parameters:

Name Type Description Default
path PathLike

A GRIB2, NetCDF, HDF5, GeoTIFF or ASCII grid file (not a DSS file). Only metadata is read.

required

Returns:

Type Description
List[str]

List of variable names.

zarr_variables staticmethod

Python
zarr_variables(path: PathLike) -> List[Dict[str, Any]]

Variables of a local Zarr v2 store, one dict each.

Parameters:

Name Type Description Default
path PathLike

The store's folder. Only metadata and axes are read.

required

Returns:

Type Description
List[Dict[str, Any]]

The engine's list of dicts (name, error, steps, ny,

List[Dict[str, Any]]

nx, units, crs, first_time, last_time, ...).

read_zarr staticmethod

Python
read_zarr(path: PathLike, variable: str, *, steps: Tuple[int, int], **kwargs: Any) -> Any

Read steps of a Zarr variable on a window, writing nothing.

Parameters:

Name Type Description Default
path PathLike

The store's folder.

required
variable str

Variable name.

required
steps Tuple[int, int]

(first, end) step indexes.

required
**kwargs Any

bbox, rows, cols, limits, stop, strict.

{}

Returns:

Type Description
Any

The engine's ZarrWindow (cells, transform, crs, times).

calculate staticmethod

Python
calculate(input: PathLike, output: PathLike, *, sync: Optional[Any] = None, **kwargs: Any) -> Any

Apply one operation by one constant to every valid cell of each grid.

Parameters:

Name Type Description Default
input PathLike

Source grids (a DSS file or a gridded source file).

required
output PathLike

DSS file to write.

required
sync Optional[Any]

Flush policy, passed to the engine unchanged (see the class notes).

None
**kwargs Any

Exactly one of multiply, divide, add, subtract; and variables, parts, units, data_type, version, align. A, B and F are empty unless parts states them.

{}

Returns:

Type Description
Any

The engine's ImportResult.

calculate_raster staticmethod

Python
calculate_raster(input: PathLike, raster: PathLike, output: PathLike, *, operation: str, sync: Optional[Any] = None, **kwargs: Any) -> Any

Combine each grid, on the left, with a raster resampled to it.

Parameters:

Name Type Description Default
input PathLike

Source grids.

required
raster PathLike

The raster operand (GeoTIFF, ASCII grid or a DSS grid).

required
output PathLike

DSS file to write.

required
operation str

multiply, divide, add or subtract.

required
sync Optional[Any]

Flush policy, passed to the engine unchanged (see the class notes).

None
**kwargs Any

method, raster_variable, variables, parts, units, data_type, version, align, static_raster.

{}

Returns:

Type Description
Any

The engine's ImportResult.

sanitize staticmethod

Python
sanitize(input: PathLike, output: PathLike, *, sync: Optional[Any] = None, **kwargs: Any) -> Any

Replace valid cells at or beyond thresholds.

Parameters:

Name Type Description Default
input PathLike

Source grids.

required
output PathLike

DSS file to write.

required
sync Optional[Any]

Flush policy, passed to the engine unchanged (see the class notes).

None
**kwargs Any

minimum, maximum (inclusive), minimum_replacement, maximum_replacement (NaN, the default, makes the cell missing), variables, parts, units, data_type, version, align.

{}

Returns:

Type Description
Any

The engine's ImportResult.

clip staticmethod

Python
clip(input: PathLike, output: PathLike, *, sync: Optional[Any] = None, **kwargs: Any) -> Any

Clip grids to an envelope, by nearest neighbour, in their own CRS.

Parameters:

Name Type Description Default
input PathLike

Source grids.

required
output PathLike

DSS file to write.

required
sync Optional[Any]

Flush policy, passed to the engine unchanged (see the class notes).

None
**kwargs Any

envelope=(min_x, min_y, max_x, max_y) with envelope_crs, or shapefile (its features' combined extent; not a polygon mask); variables, parts, units, data_type, version, align.

{}

Returns:

Type Description
Any

The engine's ImportResult.

normalize staticmethod

Python
normalize(input: PathLike, normals: PathLike, output: PathLike, *, start: Any, end: Any, interval: Any, sync: Optional[Any] = None, **kwargs: Any) -> Any

Scale each interval's source grids so their total matches its normals.

Parameters:

Name Type Description Default
input PathLike

Source grids.

required
normals PathLike

Grids holding the totals to match.

required
output PathLike

DSS file to write.

required
start Any

Start of the first interval.

required
end Any

End of the last interval.

required
interval Any

A datetime.timedelta or a number of seconds.

required
sync Optional[Any]

Flush policy, passed to the engine unchanged (see the class notes).

None
**kwargs Any

source_variables, normals_variables, parts, units, data_type, version, align.

{}

Returns:

Type Description
Any

The engine's NormalizeResult. Check sources_left_out,

Any

normals_left_out and cells_made_missing_by_normal.

shift_times staticmethod

Python
shift_times(input: PathLike, output: PathLike, *, sync: Optional[Any] = None, **kwargs: Any) -> Any

Move grid records in time. Cell values are kept.

Parameters:

Name Type Description Default
input PathLike

DSS file holding the grids.

required
output PathLike

DSS file to write.

required
sync Optional[Any]

Flush policy, passed to the engine unchanged (see the class notes).

None
**kwargs Any

shift (a datetime.timedelta), or shift_start and shift_end; select, parts, units, data_type, version, progress. A source's A and B parts are not kept unless parts states them.

{}

Returns:

Type Description
Any

The engine's TimeToolResult.

resample_times staticmethod

Python
resample_times(input: PathLike, output: PathLike, step_minutes: int, *, sync: Optional[Any] = None, **kwargs: Any) -> Any

Resample each grid series to a fixed time step.

Parameters:

Name Type Description Default
input PathLike

DSS file holding the grids.

required
output PathLike

DSS file to write.

required
step_minutes int

One of time_steps().

required
sync Optional[Any]

Flush policy, passed to the engine unchanged (see the class notes).

None
**kwargs Any

rule ("strict" or "vortex"), select, parts, units, data_type, version, progress.

{}

Returns:

Type Description
Any

The engine's TimeToolResult. dropped_tail_seconds is time after

Any

the last whole window, which is not in the output.

time_steps staticmethod

Python
time_steps() -> List[int]

The steps resample_times takes, in minutes.

Returns:

Type Description
List[int]

List of int minutes.

series_info staticmethod

Python
series_info(input: PathLike, pathname: str) -> Dict[str, Any]

What a grid series states: records, start, end, data type, units and grid.

Parameters:

Name Type Description Default
input PathLike

DSS file.

required
pathname str

Any record of the series.

required

Returns:

Type Description
Dict[str, Any]

The engine's dict.

read_window staticmethod

Python
read_window(input: PathLike, pathname: str, start: Any, end: Optional[Any] = None, **kwargs: Any) -> Any

One window of a grid series, computed as resample_times computes it.

Parameters:

Name Type Description Default
input PathLike

DSS file.

required
pathname str

Any record of the series.

required
start Any

Window start.

required
end Optional[Any]

Window end; None asks for an instant.

None
**kwargs Any

rule and missing ("nan" or "raw").

{}

Returns:

Type Description
Any

The engine's WindowGrid (data is (ny, nx), rows south to north).

read_nearest staticmethod

Python
read_nearest(input: PathLike, pathname: str, time: Any, **kwargs: Any) -> Any

The grid record of a series nearest a time.

Parameters:

Name Type Description Default
input PathLike

DSS file.

required
pathname str

Any record of the series.

required
time Any

The time to look near.

required
**kwargs Any

missing ("nan" or "raw").

{}

Returns:

Type Description
Any

The engine's WindowGrid.

read_min_max staticmethod

Python
read_min_max(input: PathLike, pathname: str, start: Any, end: Any, **kwargs: Any) -> Tuple[Any, Any]

The minimum and maximum grids of a series over a window.

Parameters:

Name Type Description Default
input PathLike

DSS file.

required
pathname str

Any record of the series.

required
start Any

Window start.

required
end Any

Window end.

required
**kwargs Any

missing ("nan" or "raw").

{}

Returns:

Type Description
Tuple[Any, Any]

(minimum, maximum), two engine WindowGrid objects.

grid_to_point staticmethod

Python
grid_to_point(grids: PathLike, zones: PathLike, zone_field: str, output: PathLike, *, sync: Optional[Any] = None, **kwargs: Any) -> Any

Zonal statistics of each grid, written as one time series per zone and statistic.

Parameters:

Name Type Description Default
grids PathLike

A DSS file, GRIB2 file, GeoTIFF or ASCII grid.

required
zones PathLike

A shapefile or GeoJSON file of zones.

required
zone_field str

The field that names each zone; it becomes the B part.

required
output PathLike

DSS file to write the time series to.

required
sync Optional[Any]

Flush policy, passed to the engine unchanged (see the class notes). ras-commander-fast-dss 0.1.2 added it to this function; an engine without it raises DssCapabilityError when it is stated.

None
**kwargs Any

statistics (default ("average",)), accumulate, parts (A and F), variables, zones_crs, area_weighted, compatibility, version, assume_no_datum_shift, allow_in_place.

{}

Returns:

Type Description
Any

The engine's GridToPointResult (records, zones, pathnames).

zonal_statistics staticmethod

Python
zonal_statistics(grids: PathLike, zones: PathLike, zone_field: str, **kwargs: Any) -> Any

The statistics of grid_to_point as a table, writing nothing.

Parameters:

Name Type Description Default
grids PathLike

A DSS file, GRIB2 file, GeoTIFF or ASCII grid.

required
zones PathLike

A shapefile or GeoJSON file of zones.

required
zone_field str

The field that names each zone.

required
**kwargs Any

variables, zones_crs, area_weighted, compatibility, assume_no_datum_shift, raw.

{}

Returns:

Type Description
Any

The engine's pandas.DataFrame, one row per frame and zone, unchanged.

Any

Missing statistics are NaN unless raw=True.

zone_masks staticmethod

Python
zone_masks(grids: PathLike, zones: PathLike, zone_field: str, **kwargs: Any) -> Dict[str, Any]

Each zone's flat cell indices on the source's last grid.

Parameters:

Name Type Description Default
grids PathLike

A DSS file, GRIB2 file, GeoTIFF or ASCII grid.

required
zones PathLike

A shapefile or GeoJSON file of zones.

required
zone_field str

The field that names each zone.

required
**kwargs Any

variables, zones_crs, assume_no_datum_shift.

{}

Returns:

Type Description
Dict[str, Any]

dict of zone name to a NumPy index array.

Usage

Python
from ras_commander.dss import RasDss

# Get catalog of DSS contents
catalog = RasDss.get_catalog("/path/to/file.dss")
print(catalog)

# Read time series
pathname = "/BASIN/GAGE1/FLOW/01JAN2020/1HOUR/OBS/"
df = RasDss.read_timeseries("/path/to/file.dss", pathname)
print(df)

# Write a small SHG gridded precipitation DSS
import numpy as np
import pandas as pd

data = np.arange(5 * 10 * 10, dtype="float32").reshape(5, 10, 10)
times = pd.date_range("2020-01-01 01:00", periods=5, freq="h")
written = RasDss.write_grid_timeseries(
    "/path/to/precip.dss",
    "/SHG/WATERSHED/PRECIP/01JAN2020:0000/01JAN2020:0100/SYNTHETIC/",
    data,
    times,
    {
        "cellsize": 2000,
        "origin": (1096000, 1516000),
        "crs": "SHG",
        "units": "mm",
        "data_type": "PER-CUM",
    },
)
print(written)

# Extract all boundary conditions from project
from ras_commander import init_ras_project, ras
init_ras_project("/path/to/project", "6.5")
bc_data = RasDss.extract_boundary_timeseries(ras.boundaries_df, ras_object=ras)

Grid Java API Mapping

write_grid_timeseries() uses the same lazy pyjnius/HEC Monolith setup as the time-series methods. The Python inputs map to Java objects as follows:

Python input HEC Monolith class/member
dss_file hec.heclib.grid.GriddedData.setDSSFileName()
A/B/C/F parts of pathname GriddedData.setGriddedPathnameParts()
Generated D/E timestep windows GridInfo.setGridTimes() and GriddedData.setGriddedTimeWindow()
data[i] flattened row-major hec.heclib.grid.GridData(float[], GridInfo)
grid_info["crs"] == "SHG" hec.heclib.grid.AlbersInfo with NAD83 SHG parameters
Other WKT CRS strings hec.heclib.grid.SpecifiedGridInfo.setSpatialReference()
cellsize, origin, cell counts GridInfo.setCellInfo()
units, data_type GridInfo.setParameterInfo()
compression settings GridInfo.setCompressionInfo()

The bundled HEC Monolith exposes hec.io.GridContainer, but the ras-commander Monolith cache does not include a SpatialGridBean class. The equivalent grid payload is GridData plus a GridInfo subclass (AlbersInfo, SpecifiedGridInfo, or HrapInfo). This writer stores records through GriddedData.storeGriddedData() because that is the stable grid write path from pyjnius for the Monolith version used by ras-commander.

RasUnsteady DSS inventory

get_dss_boundaries(unsteady_file, ras_object=None)

Return the DSS-linked boundary inventory for one unsteady-flow file. Canonical 2D identity columns are area_2d and bc_line_name, matching ras.boundaries_df. The older sa_2d_name and bc_line columns remain equal compatibility aliases but are deprecated. The returned DataFrame records this mapping in df.attrs["deprecated_columns"].

The current mutation methods retain their compatibility parameter names. For example, pass sa_2d_name=row["area_2d"] and bc_line=row["bc_line_name"] to set_boundary_dss_link(). Canonical mutation keyword aliases are not added in this release.

Read behavior

read_timeseries() accepts start_date and end_date. The Java backend returns the complete series without applying those filters; the native and shadow backends apply the window (see DSS Read and Write Backends). Returned attrs retain pathname, units, type, interval, and source path.

Java DSS handles are write-capable. Check that a source exists before opening it; some read paths can create a missing file. Use a verified disposable copy when source immutability is required. These APIs do not guarantee read-only file access.

Requirements

  • pip install pyjnius
  • Java 8+ (JRE or JDK)
  • HEC Monolith libraries (auto-downloaded on first use)

Complete source reference

RasDss source reference

Static class for DSS file operations.

Uses HEC Monolith libraries (auto-downloaded on first use). Supports both DSS V6 and V7 formats.

All heavy dependencies (pyjnius, Java) are lazy-loaded on first use.

Usage

from ras_commander import RasDss

Read time series

df = RasDss.read_timeseries("file.dss", "/BASIN/LOC/FLOW//1HOUR/OBS/")

Get catalog

paths = RasDss.get_catalog("file.dss")

Backends

RasDss.backend selects how read and write methods access DSS files: "java" (default; HEC Monolith via pyjnius), "native" (ras-commander-fast-dss, no JVM) or "shadow" (reads: native result plus a logged Java cross-check; writes: Java result plus a logged native repeat on a temporary copy). RAS_COMMANDER_DSS_BACKEND overrides it when set.

check_data_availability staticmethod

Python
check_data_availability(dss_file: Union[str, Path], pathname: str, expected_start: Optional[str] = None, expected_end: Optional[str] = None)

Check if time series data is available for the expected date range.

Parameters:

Name Type Description Default
dss_file Union[str, Path]

Path to DSS file (str or Path)

required
pathname str

DSS pathname

required
expected_start Optional[str]

Expected start date (optional, datetime or string)

None
expected_end Optional[str]

Expected end date (optional, datetime or string)

None

Returns:

Type Description
ValidationResult

Result with data availability check outcome

Example

from datetime import datetime result = RasDss.check_data_availability( ... "data.dss", ... "//BASIN/FLOW/01JAN2020/1HOUR/RUN1/", ... expected_start=datetime(2020, 1, 1), ... expected_end=datetime(2020, 12, 31) ... )

check_file_exists staticmethod

Python
check_file_exists(dss_file: Union[str, Path])

Check if DSS file exists and is accessible.

Parameters:

Name Type Description Default
dss_file Union[str, Path]

Path to DSS file (str or Path)

required

Returns:

Type Description
ValidationResult

Result with file existence check outcome

Example

from pathlib import Path result = RasDss.check_file_exists(Path("data.dss")) if result.passed: ... print("File exists and is accessible")

check_pathname staticmethod

Python
check_pathname(dss_file: Union[str, Path], pathname: str, start_date: Optional[str] = None, end_date: Optional[str] = None)

Comprehensive DSS pathname validation.

Performs: 1. Format validation 2. File existence check 3. Pathname existence check 4. Data availability check (if date range provided)

Parameters:

Name Type Description Default
dss_file Union[str, Path]

Path to DSS file (str or Path)

required
pathname str

DSS pathname to validate

required
start_date Optional[str]

Optional start date for availability check

None
end_date Optional[str]

Optional end date for availability check

None

Returns:

Type Description
ValidationReport

Result with all validation results

Example

report = RasDss.check_pathname( ... dss_file="boundary.dss", ... pathname="//BASIN/FLOW/STAGE/01JAN2020/1HOUR//", ... start_date="01JAN2020 0000", ... end_date="31DEC2020 2400" ... ) if not report.is_valid: ... print(report.summary())

check_pathname_exists staticmethod

Python
check_pathname_exists(dss_file: Union[str, Path], pathname: str)

Check if pathname exists in DSS file catalog.

Parameters:

Name Type Description Default
dss_file Union[str, Path]

Path to DSS file (str or Path)

required
pathname str

DSS pathname to check

required

Returns:

Type Description
ValidationResult

Result with existence check outcome

Example

result = RasDss.check_pathname_exists( ... "data.dss", ... "//BASIN/FLOW/01JAN2020/1HOUR/RUN1/" ... ) if result.passed: ... print("Pathname found in catalog")

check_pathname_format staticmethod

Python
check_pathname_format(pathname: str)

Check DSS pathname format validity.

Validates against DSS pathname specification: - Format: /A/B/C/D/E/F/ - A blank A-part is represented as //B/C/D/E/F/ - Parts: A (basin/project), B (location), C (parameter), D (date), E (interval), F (scenario)

Parameters:

Name Type Description Default
pathname str

DSS pathname to validate

required

Returns:

Type Description
ValidationResult

Result with detailed diagnostics

Example

from ras_commander.dss import RasDss result = RasDss.check_pathname_format("/BASIN/LOC/FLOW/01JAN2020/1HOUR/OBS/") print(result.passed) True

copy_grid_with_zero_tail staticmethod

Python
copy_grid_with_zero_tail(source_dss: Union[str, Path], output_dss: Union[str, Path], pathname: str, tail_intervals: int, *, time_shift_minutes: int = 0, output_pathname: Optional[str] = None, x_shift: float = 0.0, y_shift: float = 0.0, overwrite: bool = False, sync: Optional[Any] = None) -> Dict[str, Any]

Create a non-destructive grid derivative with an explicit zero tail.

The output contains only the uniquely matched source grid family and the appended tail. Source records are streamed one frame at a time and rewritten with their decoded values and write-relevant metadata; unrelated source records are not copied. Optional time, pathname, and whole-cell origin translations are mechanical metadata transforms.

The intended workflow is upstream preparation of a run-local gridded precipitation or rainfall-excess DSS derivative for a HEC-RAS rain-on-grid scenario. A caller can preserve an immutable AORC-like source, express UTC grid timestamps on the model clock with an explicitly chosen shift, rename the forcing family, apply an approved whole-cell origin translation, and append explicit zero-forcing intervals so post-storm routing or recession can continue after the source rainfall ends. In the source PR workflow, RasScenario accepted the already-prepared forcing_excess_dss and wired it to Gridded/DSS precipitation; it did not call this preparation method.

This method does not calculate rainfall or rainfall excess, scientifically transpose a storm, reproject, resample, or interpolate grids, infer a time zone, or decide engineering suitability. Those scientific and study-specific decisions remain caller responsibilities.

overwrite=False publishes with an atomic hard-link create-if-absent operation. Filesystems without compatible hard-link support fail closed with OSError; the method never falls back to a clobbering replace. overwrite=True atomically replaces the destination and therefore replaces its file metadata and hard-link identity. Output symlinks, junctions, and other reparse points are rejected before resolution.

Parameters:

Name Type Description Default
source_dss Union[str, Path]

Existing source DSS file, which is never modified.

required
output_dss Union[str, Path]

Destination DSS file for the derivative.

required
pathname str

Six-part family selector whose D and E parts are blank.

required
tail_intervals int

Positive number of zero-valued records to append.

required
time_shift_minutes int

Signed whole-minute shift for every window.

0
output_pathname Optional[str]

Optional output family selector with blank D/E. When omitted, caller-supplied A/B/C/F casing is preserved even though source-family selection is case-insensitive.

None
x_shift float

Signed x-origin translation in source grid units. It must be an exact whole-cell increment.

0.0
y_shift float

Signed y-origin translation in source grid units. It must be an exact whole-cell increment.

0.0
overwrite bool

Atomically replace an existing destination after full temporary readback. When false, publish only by atomic hard link if the destination still does not exist.

False
sync Optional[Any]

Flush policy of the native writer, passed to ras-commander-fast-dss unchanged; None (default) leaves the installed engine's own default. The java backend does not use it. See write_timeseries.

None

Returns:

Type Description
Dict[str, Any]

A dictionary describing source coverage, translations, DSS

Dict[str, Any]

version, accepted source SHA-256, rewritten source paths, and

Dict[str, Any]

appended tail paths.

Raises:

Type Description
FileNotFoundError

If the source DSS does not exist.

FileExistsError

If the destination exists without overwrite.

IsADirectoryError

If a DSS path is not a regular file.

ValueError

If inputs, family timing, metadata, or NoData masks are unsafe or ambiguous.

ImportError

If the optional Java bridge is unavailable.

OSError

If directory, hard-link publication, or replacement fails.

RuntimeError

If source stability, grid I/O, or complete temporary readback verification fails.

Notes

D/E tokens must use exact DDMMMYYYY:HHMM minute syntax. A narrow 2400 token is accepted as next-day midnight. Native HEC-DSS grid catalogs spell midnight record ends as prior-day 2400 and midnight record starts as same-day 0000; returned pathnames follow that role-specific convention. The source is SHA-256 checked before access, after the validation pass, and after the streaming write pass. Any detected mismatch aborts before publication. Every temporary record is reopened and compared exactly before publish.

Backends

"java" (default) reads, writes and verifies through HEC Monolith. "native" does all three through ras-commander-fast-dss with the same checks and no JVM; it keeps the source's PRECIP_2_BYTE scale and base (DSS6) and the source's DSS version. ZLIB scale and base words, which ZLIB does not use, are not compared. "shadow" returns the Java derivative, builds a native derivative in a temporary directory, and logs any difference between the two read back natively.

extract_boundary_timeseries staticmethod

Python
extract_boundary_timeseries(boundaries_df: DataFrame, project_dir: Optional[Union[str, Path]] = None, ras_object=None) -> pd.DataFrame

Extract DSS time series data for all DSS-defined boundaries.

Reads boundaries_df and extracts time series for any boundary condition defined by a DSS file. Adds the extracted data to the dataframe.

Parameters:

Name Type Description Default
boundaries_df DataFrame

DataFrame from ras.boundaries_df

required
project_dir Optional[Union[str, Path]]

Project directory (for resolving relative DSS paths)

None
ras_object RasPrj

RasPrj object (alternative to project_dir)

None

Returns:

Type Description
DataFrame

Enhanced DataFrame with 'dss_timeseries' column containing extracted data

Example

from ras_commander import init_ras_project, RasDss

ras = init_ras_project("project_path", "7.0")

Extract all DSS boundary data

enhanced_boundaries = RasDss.extract_boundary_timeseries( ras.boundaries_df, ras_object=ras )

Now enhanced_boundaries has a 'dss_timeseries' column with DataFrames

for idx, row in enhanced_boundaries.iterrows(): if row['Use DSS']: print(f"{row['bc_type']}: {len(row['dss_timeseries'])} points")

get_catalog staticmethod

Python
get_catalog(dss_file: Union[str, Path]) -> pd.DataFrame

Get catalog of all data paths in DSS file.

Parameters:

Name Type Description Default
dss_file Union[str, Path]

Path to DSS file

required

Returns:

Type Description
DataFrame

DataFrame with 'pathname' column containing all DSS pathnames

Example

catalog = RasDss.get_catalog("sample.dss") print(f"Found {len(catalog)} pathnames") for pathname in catalog['pathname']: print(pathname)

Backends

Under "native" and "shadow" a missing file raises FileNotFoundError (the Java path also refuses missing files) and a file that is not DSS raises ras_commander_fast_dss.DssFormatError (a RuntimeError; Java returns zero rows).

get_file_version staticmethod

Python
get_file_version(dss_file: Union[str, Path]) -> int

Return the major HEC-DSS file version (6 or 7).

Parameters:

Name Type Description Default
dss_file Union[str, Path]

Existing DSS file to inspect. The file is never created or modified.

required

Returns:

Type Description
int

6 or 7 (int).

Backends

"java" asks HEC Monolith (HecDataManager.getDssFileVersion). "native" reads the file header through ras-commander-fast-dss without a JVM. "shadow" returns the native answer and logs any disagreement with Java.

Raises:

Type Description
FileNotFoundError

If the path does not exist.

IsADirectoryError

If the path is not a file.

DssInvalidFileError

If the file is not a supported DSS 6 or DSS 7 database (a ValueError and DssFormatError).

get_info staticmethod

Python
get_info(dss_file: Union[str, Path]) -> Dict

Get summary information about DSS file.

Parameters:

Name Type Description Default
dss_file Union[str, Path]

Path to DSS file

required

Returns:

Type Description
Dict

Dictionary with file information

Example

info = RasDss.get_info("sample.dss") print(f"Total paths: {info['total_paths']}") print(f"File size: {info['file_size_mb']:.2f} MB")

is_pathname_available staticmethod

Python
is_pathname_available(dss_file: Union[str, Path], pathname: str, start_date: Optional[str] = None, end_date: Optional[str] = None) -> bool

Quick boolean check for pathname availability.

Parameters:

Name Type Description Default
dss_file Union[str, Path]

Path to DSS file (str or Path)

required
pathname str

DSS pathname to check

required
start_date Optional[str]

Optional start date

None
end_date Optional[str]

Optional end date

None

Returns:

Type Description
bool

True if pathname exists and has data

Example

if RasDss.is_pathname_available("data.dss", "//BASIN/FLOW/.../"): ... print("Data is available")

is_valid_pathname staticmethod

Python
is_valid_pathname(pathname: str) -> bool

Quick boolean check for pathname format.

Parameters:

Name Type Description Default
pathname str

DSS pathname to validate

required

Returns:

Type Description
bool

True if pathname format is valid

Example

if RasDss.is_valid_pathname("//BASIN/LOC/FLOW/01JAN2020/1HOUR/OBS/"): ... print("Valid format")

read_associated_location staticmethod

Python
read_associated_location(dss_file: Union[str, Path], pathname: str) -> Optional[Any]

Return the location stored for a data record, or None when there is none.

A thin wrapper around ras_commander_fast_dss.read_associated_location; it always runs on the native engine. DSS7: the location record built from the A and B parts of pathname. DSS6: the coordinates in the time-series record's own header.

Parameters:

Name Type Description Default
dss_file Union[str, Path]

Existing DSS file. It is never created or modified.

required
pathname str

Pathname of the data record (any D part).

required

Returns:

Type Description
Optional[Any]

The engine's ras_commander_fast_dss.Location, or None.

Raises:

Type Description
FileNotFoundError

If dss_file does not exist.

ImportError

If ras-commander-fast-dss is not installed.

DssLocationConflictError

DSS6 blocks of one dataset store different locations (a ras_commander_fast_dss DssError).

read_grid staticmethod

Python
read_grid(dss_file: Union[str, Path], pathname: str, *, allow_unqualified_native: bool = False) -> Dict[str, Any]

Read one spatial grid record from an exact DSS pathname.

Parameters:

Name Type Description Default
dss_file Union[str, Path]

Path to an existing DSS file.

required
pathname str

Exact six-part DSS grid pathname. Wildcards are not accepted; D and E parts identify the record's time window.

required

Returns:

Type Description
Dictionary containing
- ``dss_file``

Absolute DSS file path.

- ``pathname``

Exact pathname requested.

- ``data``

Two-dimensional float32 array in HEC row-major order. Row zero is south, columns run west to east. Flip rows before using a north-up raster transform or the native precipitation writer. The HEC grid no-data sentinel is represented as numpy.nan.

- ``shape``

(rows, columns).

- ``units`` and ``data_type``

DSS parameter metadata.

- ``grid_type``

"albers", "specified", "hrap", or the runtime grid-info class name for another grid type.

- ``crs`` and ``cell_size``

Spatial reference and resolution.

- ``start_time`` and ``end_time``

Naive pandas.Timestamp values parsed from pathname parts D and E when present.

- ``metadata``

Grid dimensions, cell indexes, origin/projection, compression, type codes, missing-value count, and raw timing.

- ``row_order``

Always "south_up" (row zero is the southern row), on every backend.

Args (keyword-only): allow_unqualified_native: Opt in to the native grid reader under backend="native" when the installed ras-commander-fast-dss does not advertise qualified grid CRS strings (feature "grid_srs_monolith_parity" in ras_commander_fast_dss.FEATURES). Cells, geometry, units and times are native; crs may be wrong or empty for legacy Albers grids, and metadata["crs_qualified"] is False. Ignored, with a warning, under "java" and "shadow". Default False.

Backends

"java" (default) reads through HEC Monolith. "native" raises DssCapabilityError unless the wheel advertises qualified grid CRS or allow_unqualified_native is True; it never falls back to Java. "shadow" always returns Java's grid (and raises Java's error, even when the native read succeeded); the native grid is only compared. It reads natively, and logs cell and metadata differences separately; a CRS disagreement is logged as the known difference G-CRS.

Raises:

Type Description
FileNotFoundError

If dss_file does not exist.

IsADirectoryError

If dss_file is not a file.

ValueError

If the pathname is malformed or uses wildcards.

DssPathnameNotFoundError

If no record has the exact pathname (a ValueError).

DssRecordTypeError

If the exact pathname identifies a non-grid record (a TypeError and DssUnsupportedRecordError).

DssCapabilityError

Native backend, unqualified wheel and no allow_unqualified_native (a NotImplementedError).

ImportError

If pyjnius (Java) or ras-commander-fast-dss (native) is not installed.

RuntimeError

If the grid read fails or returns invalid data.

read_location staticmethod

Python
read_location(dss_file: Union[str, Path], pathname: str) -> Any

Read a DSS7 location record (/A/B/Location Info////).

A thin wrapper around ras_commander_fast_dss.read_location; it always runs on the native engine. Use read_associated_location for the location of a data record.

Parameters:

Name Type Description Default
dss_file Union[str, Path]

Existing DSS7 file. It is never created or modified.

required
pathname str

Pathname of the location record.

required

Returns:

Type Description
Any

The engine's ras_commander_fast_dss.Location unchanged (x, y,

Any

z, coordinate system, units and datum codes and names, time_zone,

Any

supplemental; to_dict()).

Raises:

Type Description
FileNotFoundError

If dss_file does not exist.

ImportError

If ras-commander-fast-dss is not installed.

DssPathnameNotFoundError

The record does not exist (a ValueError).

DssUnsupportedRecordError

The record is not a location record, or the file is DSS6 (DSS6 has no location records).

read_multiple_timeseries staticmethod

Python
read_multiple_timeseries(dss_file: Union[str, Path], pathnames: List[str]) -> Dict[str, pd.DataFrame]

Read multiple time series from DSS file.

Parameters:

Name Type Description Default
dss_file Union[str, Path]

Path to DSS file

required
pathnames List[str]

List of DSS pathnames

required

Returns:

Type Description
Dict[str, DataFrame]

Dictionary mapping pathnames to DataFrames

Example

paths = ["/BASIN/LOC1/FLOW//1HOUR/OBS/", "/BASIN/LOC2/FLOW//1HOUR/OBS/"] data = RasDss.read_multiple_timeseries("file.dss", paths) for path, df in data.items(): print(f"{path}: {len(df)} points")

read_profile staticmethod

Python
read_profile(dss_file: Union[str, Path], pathname: str, start_date: Optional[Any] = None, end_date: Optional[Any] = None, *, raw: bool = False, trim_missing: bool = True) -> Any

Read a regular-interval profile dataset (DSS7 record types 102 and 107).

A thin wrapper around ras_commander_fast_dss.read_profile. It always runs on the native engine, whatever RasDss.backend is; the Java path has no profile reader.

Parameters:

Name Type Description Default
dss_file Union[str, Path]

Existing DSS file. It is never created or modified.

required
pathname str

/A/B/C/D/E/F/ with any D part (or none): the whole dataset is read, stitched from every block.

required
start_date Optional[Any]

Optional inclusive window start (as read_timeseries).

None
end_date Optional[Any]

Optional inclusive window end.

None
raw bool

Keep HEC missing markers as stored instead of NaN.

False
trim_missing bool

Remove leading and trailing rows whose every depth is missing (default), as HEC's reader does.

True

Returns:

Type Description
The engine's ``ras_commander_fast_dss.Profile`` unchanged

times,

Any

depths (n_depths), values (n_times by n_depths, stored

Any

width), depth_units, value_units, value_type, quality and

Any

to_dataframe() (rows are times, columns are depths).

Raises:

Type Description
FileNotFoundError

If dss_file does not exist.

ImportError

If ras-commander-fast-dss is not installed.

DssPathnameNotFoundError

No data for pathname (a ValueError).

DssUnsupportedRecordError

The record is not a regular profile (a scalar time series, an irregular profile 112/117, any DSS6 record).

DssCapabilityError

The installed engine has no read_profile.

Example

profile = RasDss.read_profile("lake.dss", "/LAKE/DAM/TEMP-WATER//1Day/OBS/") frame = profile.to_dataframe()

read_timeseries staticmethod

Python
read_timeseries(dss_file: Union[str, Path], pathname: str, start_date: Optional[str] = None, end_date: Optional[str] = None) -> pd.DataFrame

Read time series from DSS file.

Parameters:

Name Type Description Default
dss_file Union[str, Path]

Path to DSS file

required
pathname str

DSS pathname (e.g., "/BASIN/LOC/FLOW//1HOUR/OBS/"). The D part is ignored: the whole dataset is read.

required
start_date Optional[str]

Optional start of the window (inclusive). HEC strings such as "01JAN2020 0000", ISO strings and datetimes are accepted. Honored by the native and shadow backends; the Java backend ignores it and returns the whole dataset.

None
end_date Optional[str]

Optional end of the window (inclusive; with both ends given, an end between stamps moves forward to the next stamp). Same backend rules as start_date.

None

Returns:

Type Description
DataFrame

pandas DataFrame with DatetimeIndex and 'value' column

Backends

"native" and "shadow" return NaN for HEC missing values (the Java path returns the raw -3.4028235e38 marker). A pathname without data raises ras_commander_fast_dss.DssPathnameNotFoundError (a ValueError and RuntimeError); paired data, grids and other non-time-series records raise ras_commander_fast_dss.DssUnsupportedRecordError (a RuntimeError).

All-missing DSS6 data differs between the paths. HEC Monolith reports a DSS6 regular request whose values are all -901/-902 as not found (heclib's DSS6 "no data" rule). The native engine finds the blocks and, after trimming the missing values, raises the same DssPathnameNotFoundError; a window that also contains valid values is returned. "shadow" re-reads such a not-found case with the engine's opt-in no_data="refuse" (HEC's rule) only to label the comparison; that option is provided for Java/native parity checks and testing and never changes the returned result. Stored NaN values are values: the leading/trailing trim removes HEC missing markers only, as heclib's ztsTrim does.

Example

df = RasDss.read_timeseries("file.dss", "/BASIN/LOC/FLOW//1HOUR/OBS/") print(df.head())

repair staticmethod

Python
repair(src: Union[str, Path], dest: Union[str, Path], *, sync: Optional[Any] = None) -> Dict[str, Any]

Copy the readable records of a damaged DSS7 file into a new DSS7 file.

A thin wrapper around ras_commander_fast_dss.repair (ras-commander-fast-dss 0.1.1 and later; sync= from 0.1.2). It always runs on the native engine, whatever RasDss.backend is; there is no Java equivalent.

src is opened read-only and never written. The engine finds records by one bounded discovery procedure (bin-block chain, hash-table slots and bin overflow words), copies each readable record it reaches with the normal writer, reads the new file back, verifies every copied record against its source, and only then publishes dest. Records it could not copy are listed in not_copied; bytes that no pointer reaches are out of scope.

A partial recovery is still published. Always check result["complete"] and result["not_copied"]. complete is True exactly when no ledger entry is "not_copied"; it covers only what the discovery procedure reached and is not an integrity certificate for src. A warning is logged when complete is False.

Parameters:

Name Type Description Default
src Union[str, Path]

Existing DSS7 file to recover from.

required
dest Union[str, Path]

New file to create. It must not exist; nothing is replaced.

required
sync Optional[Any]

Flush policy, passed to the engine unchanged. None (default) states nothing, so the installed engine's own default applies. The engine builds dest under a temporary name that no reader sees until it is published; with 0.1.2, "end" (its default; True) and "step" flush it once before it is verified and published, and "none" (False) does not flush it.

None

Returns:

Type Description
Dict[str, Any]

The engine's result dict unchanged, including records_copied,

Dict[str, Any]

hidden_records_copied, not_copied ((pathname, reason) pairs),

Dict[str, Any]

ledger, src_listed_records, src_interrupted_write and

Dict[str, Any]

complete. See help(ras_commander_fast_dss.repair) for every key.

Raises:

Type Description
FileNotFoundError

If src does not exist.

IsADirectoryError

If src is not a file.

FileExistsError

If dest already exists.

ImportError

If ras-commander-fast-dss is not installed.

DssCapabilityError

If the installed ras-commander-fast-dss has no repair (attrs["native_repair_available"] in get_capabilities()).

Example

result = RasDss.repair("damaged.dss", "recovered.dss") if not result["complete"]: for pathname, reason in result["not_copied"]: print(pathname, reason)

shutdown_jvm staticmethod

Python
shutdown_jvm()

Shutdown Java Virtual Machine.

Note: With pyjnius, JVM shutdown is typically not needed. This is a placeholder for API compatibility.

Deprecated: under the native backend no JVM is started and this method is a no-op that emits DeprecationWarning. It will be removed with the Java backend.

write_grid_timeseries staticmethod

Python
write_grid_timeseries(dss_file: Union[str, Path], pathname: str, data: ndarray, times: Union[List, ndarray, DatetimeIndex], grid_info: Dict[str, Any], create_if_missing: bool = True, *, dss_version: Optional[int] = None, sync: Optional[Any] = None) -> List[str]

Write a time-varying spatial grid series to HEC-DSS.

Creates one DSS grid record per timestep using the HEC Monolith Java bridge. The method is designed for HEC-RAS gridded precipitation DSS records such as::

Text Only
/SHG/MARFC/PRECIP/01SEP2018:0200/01SEP2018:0300/NEXRAD/

Parameters:

Name Type Description Default
dss_file Union[str, Path]

Path to DSS file (created if missing and create_if_missing=True).

required
pathname str

DSS grid pathname template. Parts A, B, C, and F are preserved; Parts D and E are replaced with each timestep's start/end window.

required
data ndarray

3-D array with shape (n_times, n_rows, n_cols). HEC row order: row zero is south, columns run west to east. For north-up raster arrays pass data[:, ::-1, :]. NaN/inf values and values equal to grid_info["nodata_value"] are written as the HEC grid no-data sentinel.

required
times Union[List, ndarray, DatetimeIndex]

Timezone-naive datetime values. Pass n_times + 1 values to provide explicit interval boundaries, or n_times values to provide interval end times. For n_times period data, the interval is inferred from grid_info["interval_minutes"], consecutive times, the pathname D/E parts, or 60 minutes.

required
grid_info Dict[str, Any]

Grid metadata. Common keys are: - cellsize or cell_size: cell size in CRS units. - origin: physical lower-left coordinate (x, y). - lower_left_cell_x / lower_left_cell_y: explicit HEC cell indexes, used instead of origin when provided. - x_coord_cell_zero / y_coord_cell_zero: physical coordinate of HEC cell zero, default 0. - crs: "SHG"/"EPSG:5070" for HEC SHG Albers metadata, or WKT for a specified grid. - units: data units, default "mm". - data_type: DSS grid data type, default "PER-CUM". - compression: "PRECIP_2_BYTE", "ZLIB", or None. Defaults to "PRECIP_2_BYTE".

required
create_if_missing bool

Create DSS file if it doesn't exist.

True
dss_version Optional[int]

Major DSS version to use when creating a new file. Pass 6 or 7 explicitly, or omit it to preserve the bridge's current default. Existing files must match an explicit value. For DSS6, default precipitation compression is configured with the version-specific safe base/scale ordering.

None
sync Optional[Any]

Flush policy of the native writer, passed to ras-commander-fast-dss unchanged; None (default) leaves the installed engine's own default. The java backend does not use it. See write_timeseries.

None

Returns:

Type Description
List[str]

List of DSS pathnames written, one per timestep.

Raises:

Type Description
FileNotFoundError

If DSS file doesn't exist and create_if_missing=False.

ValueError

If inputs are malformed, timestamps are timezone-aware, grid metadata is incomplete, dss_version is invalid, or an existing file does not match the requested version.

ImportError

If pyjnius is not installed.

RuntimeError

If the Java grid write operation fails.

Notes

HEC Monolith 3.3.x exposes hec.io.GridContainer and hec.heclib.grid.GridData/GridInfo for grid records. This method writes through hec.heclib.grid.GriddedData.storeGriddedData() because it is the stable Java API path from pyjnius for grid data.

Backends

"java" (default) writes through HEC Monolith. "native" writes through ras-commander-fast-dss without a JVM and never falls back to Java. It stores what Monolith stores: DSS7 grids are always ZLIB compressed (Monolith ignores the requested method on DSS7); DSS6 grids use the requested ZLIB or PRECIP_2_BYTE. Differences: compression_base and compression_scale_factor are stored as named (the Java path passes them to Monolith's setter in swapped positions, hence its DSS6 default workaround); without them DSS6 PRECIP_2_BYTE scale and base are chosen as Monolith chooses them, adjusted for negative minima, where the Java path stores cells below base 0 as missing. The native writer refuses, where the Java path writes an unreadable or lossy record: uncompressed DSS6 grids, PRECIP_2_BYTE cells that the given scale and base would turn into missing, data types other than PER-AVER, PER-CUM, INST-VAL and INST-CUM, and DSS6 unit strings longer than 12 characters. DSS7 HRAP and Albers grids store a null value of -FLT_MAX (Monolith stores 0.0; neither reader treats it as data). Instantaneous grids are stored with the time in part D and part E blank, as Monolith stores them; the native writer returns those stored pathnames, the Java path returns D/E-filled names. "shadow" writes with Java, repeats the write natively on a temporary copy and logs any difference between the native read-backs; the comparison never raises.

write_location staticmethod

Python
write_location(dss_file: Union[str, Path], pathname: str, *, sync: Optional[Any] = None, **kwargs: Any) -> Dict[str, Any]

Store location data (coordinates, datums, supplemental text) for a pathname.

A thin wrapper around ras_commander_fast_dss.write_location; it always runs on the native engine, whatever RasDss.backend is. DSS7 stores the record /A/B/Location Info////. DSS6 rewrites the header of every block of the time series named by pathname, which must exist.

Parameters:

Name Type Description Default
dss_file Union[str, Path]

Existing DSS6 or DSS7 file. This method does not create files.

required
pathname str

DSS7: any pathname of the location (A and B are used). DSS6: a time-series pathname.

required
sync Optional[Any]

Flush policy, passed to the engine unchanged. None (default) states nothing and the installed engine's own default applies; see write_timeseries.

None
**kwargs Any

The ras_commander_fast_dss.write_location fields, passed unchanged: x, y, z, coordinate_system, coordinate_id, horizontal_units, horizontal_datum, vertical_units, vertical_datum, time_zone (DSS7), supplemental, keep_existing and allow_undetectable_readers. Supplemental text is informational: a datum named in it is never applied to values.

{}

Returns:

Type Description
Dict[str, Any]

The engine's report dict unchanged.

Raises:

Type Description
FileNotFoundError

If dss_file does not exist.

ImportError

If ras-commander-fast-dss is not installed.

DssCapabilityError

The installed engine does not advertise write_location (attrs["native_location_write_available"]).

DssUnsupportedRecordError

DSS6 without a time series for pathname.

DssLockedError

HEC software has the file open (a RuntimeError).

Example

RasDss.write_location("gages.dss", "/BASIN/GAGE1/FLOW//1Hour/OBS/", x=-90.07, y=29.95, z=3.2)

write_paired_data staticmethod

Python
write_paired_data(dss_file: Union[str, Path], pathname: str, x_values: Any, y_values: Any = None, x_units: Optional[str] = None, y_units: Optional[str] = None, x_type: Optional[str] = None, y_type: Optional[str] = None, labels: Optional[Sequence[str]] = None, create_if_missing: bool = True, *, x_precision: Optional[int] = None, y_precision: Optional[int] = None, value_type: str = 'auto', dss_version: Optional[int] = None, sync: Optional[Any] = None) -> None

Write one paired-data record (rating curve, damage curve, temporal pattern, elevation-storage table, ...) with one or more curves.

A new record is added; a record already at pathname is replaced whole. Passing the DataFrame from read_paired_data as x_values writes the same ordinates, curves, stored precision, labels, units, types and display precision (the record time zone is not written; see Backends).

Parameters:

Name Type Description Default
dss_file Union[str, Path]

Path to DSS file (created if missing and create_if_missing=True)

required
pathname str

DSS pathname with exactly six parts, for example "/BASIN/LOC/STAGE-FLOW///RATING/". The C part usually names the two parameters. D, E and F are free text and kept as given.

required
x_values Any

The ordinates (1-D array-like), or a DataFrame or Series indexed by the ordinates with one column per curve. With a DataFrame or Series, omit y_values. attrs from read_paired_data supply any metadata argument left as None.

required
y_values Any

The curves: 1-D for one curve, or 2-D with shape (len(x_values), n_curves).

None
x_units Optional[str]

Units of the ordinates (for example "FEET"). None: from attrs, otherwise blank.

None
y_units Optional[str]

Units of the curves. None: as x_units.

None
x_type Optional[str]

Axis type of the ordinates (for example "LINEAR", "LOG", "PROB"). None: as x_units.

None
y_type Optional[str]

Axis type of the curves. None: as x_units.

None
labels Optional[Sequence[str]]

Curve names, one per curve. None: a DataFrame's string column names (the default curve_1 .. curve_n names are not labels; then attrs["labels"] when it has one entry per curve), a Series' name, otherwise no labels.

None
create_if_missing bool

Create the DSS file if it doesn't exist (default True).

True
x_precision Optional[int]

Decimal places to display for the ordinates, 0-9, or -1 for unset. Give both precisions or neither; they must be both -1 or both 0-9. None: from attrs when usable in the target file, otherwise -1. Inherited precision that DSS6 cannot store is dropped: see Backends.

None
y_precision Optional[int]

Decimal places to display for the curves, as x_precision.

None
value_type str

"auto" (default) stores float32 (record type 200, PD) when both the ordinates and the curves are float32 and float64 (type 205, PDD) otherwise, so a frame read with dtype="stored" keeps its type. "float" or "double" choose.

'auto'
dss_version Optional[int]

Major DSS version (6 or 7) for a new file. Omit it for DSS7. An existing file must match an explicit value.

None
sync Optional[Any]

Flush policy of the native writer, passed to ras-commander-fast-dss unchanged. None (default) states nothing, so the installed engine's own default applies; that default is the engine's to define and can change between its releases. With ras-commander-fast-dss 0.1.2 the policies are "end" (its default; True means the same): one flush at the end of the write call; "step": a flush at every flush point, the 0.1.1 behaviour of True; and "none" (False means the same): no flush. The process-death recovery guarantee is the same in every mode; no value is a power-loss guarantee. The java backend does not use it; shadow applies it to the native repeat only. Stated under native with an engine that has no write_sync_policy feature: DssCapabilityError.

None

Returns:

Type Description
None

None. As with write_timeseries, a failed write raises.

Raises:

Type Description
FileNotFoundError

If the DSS file doesn't exist and create_if_missing=False

IsADirectoryError

If dss_file is a directory

TypeError

If pathname or a unit, type or label is not a string

ValueError

If pathname does not have exactly six parts; the arrays are not numeric, empty, or have mismatched shapes; labels does not have one entry per curve; a precision or value_type is invalid; dss_version is invalid or does not match an existing file. Under native, also when the engine refuses the input (see Backends).

ImportError

If pyjnius (java) or ras-commander-fast-dss (native) is not installed

DssCapabilityError

native with a ras-commander-fast-dss wheel that has no writers (a NotImplementedError)

DssUnsupportedRecordError

native, when the pathname holds a record of another kind, or for the ELEV cases below

RuntimeError

If the Java write fails, or returns without the record being in the file. Native engine errors (DssLockedError when HEC software has the file open, other DssError subclasses) are RuntimeError subclasses too.

Backends

"java" (default) writes hec.io.PairedDataContainer through HEC Monolith. "native" writes through ras-commander-fast-dss without a JVM and never falls back to Java: an existing file keeps its DSS version, a new file is DSS7 unless dss_version=6. Both store NaN as stored bits, and DSS6 pathnames in upper case. The native writer refuses input the Java path accepts; the user guide lists each case: DSS6 units or types longer than 8 characters (Java truncates them), some DSS6 labels and precisions, non-ASCII pathnames, infinite values, a record of another kind at the pathname, and two ELEV cases (a | in an elevation-side unit and, for DSS7, a location record holding vertical-datum information). A failed native write that created the file removes it. "shadow" writes with Java, repeats the write natively on a temporary copy and logs any difference between the native read-back of the two files; the comparison never raises. The time_zone that read_paired_data reports is not written on any backend, because PairedDataContainer does not store it. DSS6 cannot store x_precision=0; a value inherited from attrs becomes -1 there (the native reader reports 0 for some DSS6 records written without precision). See docs/user-guide/dss-native-backend.md.

Example

from ras_commander import RasDss RasDss.write_paired_data( ... "rating.dss", "/BASIN/LOC/STAGE-FLOW///RATING/", ... [1.0, 2.0, 3.0], [10.0, 25.0, 60.0], ... x_units="FEET", y_units="CFS", x_type="LINEAR", y_type="LINEAR", ... ) rating = RasDss.read_paired_data("rating.dss", "/BASIN/LOC/STAGE-FLOW///RATING/") RasDss.write_paired_data("copy.dss", "/BASIN/LOC/STAGE-FLOW///COPY/", rating)

write_profile staticmethod

Python
write_profile(dss_file: Union[str, Path], pathname: str, depths: Any, values: Any, *, start: Any, depth_units: str, value_units: str, data_type: str, create_if_missing: bool = True, sync: Optional[Any] = None, **kwargs: Any) -> Dict[str, Any]

Store a regular-interval profile (values by time and depth) in a DSS7 file.

A thin wrapper around ras_commander_fast_dss.write_profile. It always runs on the native engine, whatever RasDss.backend is; the Java writers of this class do not store profiles. Profiles exist only in DSS7.

Parameters:

Name Type Description Default
dss_file Union[str, Path]

DSS7 file. A new file is created as DSS7 when create_if_missing is true, and removed again if the write fails.

required
pathname str

/A/B/C/D/E/F/; E is a standard regular interval and D is replaced for each block.

required
depths Any

The depth axis, 1-D, n_depths values. Every block of a dataset has one axis; a write whose depths differ from a stored block is refused.

required
values Any

2-D, shape (n_times, n_depths). Never flattened or reshaped.

required
start Any

Time of the first row; the rows follow at the E-part interval.

required
depth_units str

Units of the depth axis.

required
value_units str

Units of the values.

required
data_type str

HEC data type (INST-VAL, PER-AVER, ...).

required
create_if_missing bool

Create the file when it does not exist (default True).

True
sync Optional[Any]

Flush policy, passed to the engine unchanged. None (default) states nothing and the installed engine's own default applies; see write_timeseries.

None
**kwargs Any

Other ras_commander_fast_dss.write_profile options, passed unchanged (quality, time_zone, precision, value_type, raw, allow_undetectable_readers).

{}

Returns:

Type Description
Dict[str, Any]

The engine's report dict unchanged.

Raises:

Type Description
FileNotFoundError

The file does not exist and create_if_missing is false.

ValueError

An existing file is not DSS7, or the engine refuses the input.

ImportError

If ras-commander-fast-dss is not installed.

DssCapabilityError

The installed engine does not advertise write_profile (attrs["native_profile_write_available"] in get_capabilities()).

DssLockedError

HEC software has the file open (a RuntimeError).

Example

RasDss.write_profile( "lake.dss", "/LAKE/DAM/TEMP-WATER//1Day/OBS/", depths=[0.0, 5.0, 10.0], values=temperatures, start="01JAN2024 2400", depth_units="ft", value_units="DEG F", data_type="INST-VAL", )

write_timeseries staticmethod

Python
write_timeseries(dss_file: Union[str, Path], pathname: str, times: Union[List, ndarray, DatetimeIndex], values: Union[List, ndarray], units: str = 'CFS', data_type: str = 'INST-VAL', create_if_missing: bool = True, *, dss_version: Optional[int] = None, sync: Optional[Any] = None) -> None

Write a time series to a DSS file.

Creates or updates a time series record in a DSS file using the HEC Monolith Java bridge. Supports DSS V6 and V7 formats.

Parameters:

Name Type Description Default
dss_file Union[str, Path]

Path to DSS file (created if missing and create_if_missing=True)

required
pathname str

DSS pathname (e.g., "//BASIN/LOCATION/FLOW//1HOUR/FORECAST/")

required
times Union[List, ndarray, DatetimeIndex]

Array of timezone-naive datetime values (datetime objects, DatetimeIndex, or numpy datetime64 array). Values must be aligned exactly to whole minutes.

required
values Union[List, ndarray]

Array of numeric values (same length as times)

required
units str

Data units string (e.g., "CFS", "FEET", "MM", "IN")

'CFS'
data_type str

DSS data type string: - "INST-VAL" - Instantaneous values (default) - "PER-AVER" - Period average (e.g., precipitation) - "PER-CUM" - Period cumulative - "INST-CUM" - Instantaneous cumulative

'INST-VAL'
create_if_missing bool

Create DSS file if it doesn't exist (default True)

True
dss_version Optional[int]

Major DSS version to use when creating a new file. Pass 6 or 7 explicitly, or omit it to preserve the bridge's current default. Existing files must match an explicit value.

None
sync Optional[Any]

Flush policy of the native writer, passed to ras-commander-fast-dss unchanged. None (default) states nothing, so the installed engine's own default applies; that default is the engine's to define and can change between its releases. With ras-commander-fast-dss 0.1.2 the policies are "end" (its default; True means the same): one flush at the end of the write call; "step": a flush at every flush point, the 0.1.1 behaviour of True; and "none" (False means the same): no flush. The process-death recovery guarantee is the same in every mode; no value is a power-loss guarantee. The java backend does not use it; shadow applies it to the native repeat only. Stated under native with an engine that has no write_sync_policy feature: DssCapabilityError.

None

Raises:

Type Description
FileNotFoundError

If DSS file doesn't exist and create_if_missing=False

ValueError

If times and values have different lengths, are empty, or contain timestamps that cannot be represented exactly as HEC int32 epoch minutes; if dss_version is invalid; or if an existing file does not match the requested version. Under native, also when the engine refuses the input (see Backends).

ImportError

If pyjnius (java) or ras-commander-fast-dss (native) is not installed

DssCapabilityError

native with a ras-commander-fast-dss wheel that has no writers (a NotImplementedError)

RuntimeError

If Java write operation fails, including a read-only target, a refusal the HEC-DSS library only reports as a message, and a record missing from the file's catalog afterwards. Native engine errors (DssLockedError when HEC software has the file open, other DssError subclasses) are RuntimeError subclasses too.

Backends

"java" (default) writes through HEC Monolith. "native" writes through ras-commander-fast-dss without a JVM and never falls back to Java: an existing file keeps its DSS version, a new file is DSS7 unless dss_version=6 (the Java default). The E part decides regular or irregular (IR-DAY .. IR-CENTURY) storage on both backends. The native writer refuses, where Java truncates or reinterprets: times that are not exactly regular for a regular E part, DSS6 units or types longer than 8 characters, malformed pathnames, and infinite values. NaN is stored as Java stores it: as NaN in DSS7 files and as -901 in DSS6 files. A failed native write that created the file removes it. "shadow" writes with Java, repeats the write natively on a temporary copy and logs any difference between the native read-back of the two files; the comparison never raises. See docs/user-guide/dss-native-backend.md.

Example

import pandas as pd import numpy as np from ras_commander import RasDss

Create time series data

times = pd.date_range("2024-01-01", periods=24, freq="h") values = np.random.uniform(100, 500, 24)

Write to DSS file

RasDss.write_timeseries( ... "output.dss", ... "//BASIN/UPSTREAM/FLOW//1HOUR/FORECAST/", ... times, values, ... units="CFS", ... data_type="INST-VAL" ... )

Note

The Java bridge (pyjnius + HEC Monolith) is configured automatically on first use. The HEC epoch is 1899-12-31 00:00:00; times are stored as integer minutes since that epoch.

write_timeseries_from_dataframe staticmethod

Python
write_timeseries_from_dataframe(dss_file: Union[str, Path], pathname: str, df: DataFrame, value_column: str = 'value', units: str = 'CFS', data_type: str = 'INST-VAL', create_if_missing: bool = True, *, dss_version: Optional[int] = None, sync: Optional[Any] = None) -> None

Write a time series DataFrame to a DSS file.

Convenience wrapper around write_timeseries() that accepts a DataFrame with a DatetimeIndex and a value column.

Parameters:

Name Type Description Default
dss_file Union[str, Path]

Path to DSS file

required
pathname str

DSS pathname

required
df DataFrame

DataFrame with a timezone-naive DatetimeIndex and value column

required
value_column str

Name of column containing values (default "value")

'value'
units str

Data units string

'CFS'
data_type str

DSS data type string

'INST-VAL'
create_if_missing bool

Create DSS file if it doesn't exist

True
dss_version Optional[int]

Major DSS version (6 or 7) for new-file creation. Omit it to preserve the current default. Existing files must match an explicit value.

None
sync Optional[Any]

Flush policy of the native writer, passed to ras-commander-fast-dss unchanged; None (default) leaves the installed engine's own default. The java backend does not use it. See write_timeseries.

None
Example

Read from one DSS file, write to another

df = RasDss.read_timeseries("input.dss", pathname) RasDss.write_timeseries_from_dataframe( ... "output.dss", new_pathname, df, units="CFS" ... )