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): IfTrue, atomically replace an existing destination after complete temporary readback. IfFalse, 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.
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:
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
¶
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``
|
|
Dict[str, bool]
|
|
Dict[str, bool]
|
|
Dict[str, bool]
|
|
Dict[str, bool]
|
and |
import_gridded
staticmethod
¶
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 ( |
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 |
{}
|
Returns:
| Type | Description |
|---|---|
Any
|
The engine's |
Raises:
| Type | Description |
|---|---|
ImportError
|
ras-commander-fast-dss is not installed. |
DssCapabilityError
|
The installed engine has no |
ValueError
|
The engine refuses the run (nothing is written). |
import_arrays
staticmethod
¶
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 |
required |
output
|
PathLike
|
DSS file to write. |
required |
times
|
Sequence[Any]
|
One per frame: |
required |
transform
|
Sequence[float]
|
|
required |
crs
|
str
|
|
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 |
{}
|
Returns:
| Type | Description |
|---|---|
Any
|
The engine's |
Raises:
| Type | Description |
|---|---|
ImportError
|
ras-commander-fast-dss is not installed. |
DssCapabilityError
|
The installed engine has no |
import_zarr
staticmethod
¶
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 |
required |
sync
|
Optional[Any]
|
Flush policy, passed to the engine unchanged (see the class notes). |
None
|
**kwargs
|
Any
|
Other |
{}
|
Returns:
| Type | Description |
|---|---|
Any
|
The engine's |
Raises:
| Type | Description |
|---|---|
ImportError
|
ras-commander-fast-dss is not installed. |
DssCapabilityError
|
The installed engine has no |
list_variables
staticmethod
¶
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
¶
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 ( |
List[Dict[str, Any]]
|
|
read_zarr
staticmethod
¶
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]
|
|
required |
**kwargs
|
Any
|
|
{}
|
Returns:
| Type | Description |
|---|---|
Any
|
The engine's |
calculate
staticmethod
¶
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 |
{}
|
Returns:
| Type | Description |
|---|---|
Any
|
The engine's |
calculate_raster
staticmethod
¶
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
|
|
required |
sync
|
Optional[Any]
|
Flush policy, passed to the engine unchanged (see the class notes). |
None
|
**kwargs
|
Any
|
|
{}
|
Returns:
| Type | Description |
|---|---|
Any
|
The engine's |
sanitize
staticmethod
¶
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
|
|
{}
|
Returns:
| Type | Description |
|---|---|
Any
|
The engine's |
clip
staticmethod
¶
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
|
|
{}
|
Returns:
| Type | Description |
|---|---|
Any
|
The engine's |
normalize
staticmethod
¶
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 |
required |
sync
|
Optional[Any]
|
Flush policy, passed to the engine unchanged (see the class notes). |
None
|
**kwargs
|
Any
|
|
{}
|
Returns:
| Type | Description |
|---|---|
Any
|
The engine's |
Any
|
|
shift_times
staticmethod
¶
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
|
|
{}
|
Returns:
| Type | Description |
|---|---|
Any
|
The engine's |
resample_times
staticmethod
¶
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 |
required |
sync
|
Optional[Any]
|
Flush policy, passed to the engine unchanged (see the class notes). |
None
|
**kwargs
|
Any
|
|
{}
|
Returns:
| Type | Description |
|---|---|
Any
|
The engine's |
Any
|
the last whole window, which is not in the output. |
time_steps
staticmethod
¶
The steps resample_times takes, in minutes.
Returns:
| Type | Description |
|---|---|
List[int]
|
List of |
series_info
staticmethod
¶
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 |
read_window
staticmethod
¶
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
|
**kwargs
|
Any
|
|
{}
|
Returns:
| Type | Description |
|---|---|
Any
|
The engine's |
read_nearest
staticmethod
¶
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
|
|
{}
|
Returns:
| Type | Description |
|---|---|
Any
|
The engine's |
read_min_max
staticmethod
¶
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
|
|
{}
|
Returns:
| Type | Description |
|---|---|
Tuple[Any, Any]
|
|
grid_to_point
staticmethod
¶
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 |
None
|
**kwargs
|
Any
|
|
{}
|
Returns:
| Type | Description |
|---|---|
Any
|
The engine's |
zonal_statistics
staticmethod
¶
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
|
|
{}
|
Returns:
| Type | Description |
|---|---|
Any
|
The engine's |
Any
|
Missing statistics are NaN unless |
zone_masks
staticmethod
¶
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
|
|
{}
|
Returns:
| Type | Description |
|---|---|
Dict[str, Any]
|
|
Usage¶
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
¶
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
¶
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
¶
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
¶
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
¶
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
¶
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
|
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 |
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
¶
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
¶
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
¶
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
|
|
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 |
get_info
staticmethod
¶
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
¶
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
¶
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
¶
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 |
Raises:
| Type | Description |
|---|---|
FileNotFoundError
|
If |
ImportError
|
If ras-commander-fast-dss is not installed. |
DssLocationConflictError
|
DSS6 blocks of one dataset store different
locations (a |
read_grid
staticmethod
¶
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 |
- ``shape``
|
|
- ``units`` and ``data_type``
|
DSS parameter metadata. |
- ``grid_type``
|
|
- ``crs`` and ``cell_size``
|
Spatial reference and resolution. |
- ``start_time`` and ``end_time``
|
Naive |
- ``metadata``
|
Grid dimensions, cell indexes, origin/projection, compression, type codes, missing-value count, and raw timing. |
- ``row_order``
|
Always |
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 |
IsADirectoryError
|
If |
ValueError
|
If the pathname is malformed or uses wildcards. |
DssPathnameNotFoundError
|
If no record has the exact pathname
(a |
DssRecordTypeError
|
If the exact pathname identifies a non-grid
record (a |
DssCapabilityError
|
Native backend, unqualified wheel and no
|
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
¶
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 |
Any
|
|
Any
|
|
Raises:
| Type | Description |
|---|---|
FileNotFoundError
|
If |
ImportError
|
If ras-commander-fast-dss is not installed. |
DssPathnameNotFoundError
|
The record does not exist (a |
DssUnsupportedRecordError
|
The record is not a location record, or the file is DSS6 (DSS6 has no location records). |
read_multiple_timeseries
staticmethod
¶
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
¶
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
|
|
required |
start_date
|
Optional[Any]
|
Optional inclusive window start (as |
None
|
end_date
|
Optional[Any]
|
Optional inclusive window end. |
None
|
raw
|
bool
|
Keep HEC missing markers as stored instead of |
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
|
|
Any
|
|
Any
|
width), |
Any
|
|
Raises:
| Type | Description |
|---|---|
FileNotFoundError
|
If |
ImportError
|
If ras-commander-fast-dss is not installed. |
DssPathnameNotFoundError
|
No data for |
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 |
Example
profile = RasDss.read_profile("lake.dss", "/LAKE/DAM/TEMP-WATER//1Day/OBS/") frame = profile.to_dataframe()
read_timeseries
staticmethod
¶
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 |
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 |
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
¶
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
|
Returns:
| Type | Description |
|---|---|
Dict[str, Any]
|
The engine's result |
Dict[str, Any]
|
|
Dict[str, Any]
|
|
Dict[str, Any]
|
|
Raises:
| Type | Description |
|---|---|
FileNotFoundError
|
If |
IsADirectoryError
|
If |
FileExistsError
|
If |
ImportError
|
If ras-commander-fast-dss is not installed. |
DssCapabilityError
|
If the installed ras-commander-fast-dss has no
|
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
¶
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
¶
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::
/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 |
required |
times
|
Union[List, ndarray, DatetimeIndex]
|
Timezone-naive datetime values. Pass |
required |
grid_info
|
Dict[str, Any]
|
Grid metadata. Common keys are:
- |
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
|
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, |
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
¶
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
|
**kwargs
|
Any
|
The |
{}
|
Returns:
| Type | Description |
|---|---|
Dict[str, Any]
|
The engine's report |
Raises:
| Type | Description |
|---|---|
FileNotFoundError
|
If |
ImportError
|
If ras-commander-fast-dss is not installed. |
DssCapabilityError
|
The installed engine does not advertise
|
DssUnsupportedRecordError
|
DSS6 without a time series for |
DssLockedError
|
HEC software has the file open (a |
Example
RasDss.write_location("gages.dss", "/BASIN/GAGE1/FLOW//1Hour/OBS/", x=-90.07, y=29.95, z=3.2)
write_paired_data
staticmethod
¶
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
|
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 |
required |
y_values
|
Any
|
The curves: 1-D for one curve, or 2-D with shape
|
None
|
x_units
|
Optional[str]
|
Units of the ordinates (for example |
None
|
y_units
|
Optional[str]
|
Units of the curves. |
None
|
x_type
|
Optional[str]
|
Axis type of the ordinates (for example |
None
|
y_type
|
Optional[str]
|
Axis type of the curves. |
None
|
labels
|
Optional[Sequence[str]]
|
Curve names, one per curve. |
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
|
y_precision
|
Optional[int]
|
Decimal places to display for the curves, as |
None
|
value_type
|
str
|
|
'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
|
Returns:
| Type | Description |
|---|---|
None
|
None. As with |
Raises:
| Type | Description |
|---|---|
FileNotFoundError
|
If the DSS file doesn't exist and create_if_missing=False |
IsADirectoryError
|
If |
TypeError
|
If |
ValueError
|
If |
ImportError
|
If pyjnius ( |
DssCapabilityError
|
|
DssUnsupportedRecordError
|
|
RuntimeError
|
If the Java write fails, or returns without the record being
in the file. Native engine errors ( |
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
¶
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
|
required |
pathname
|
str
|
|
required |
depths
|
Any
|
The depth axis, 1-D, |
required |
values
|
Any
|
2-D, shape |
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 ( |
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
|
**kwargs
|
Any
|
Other |
{}
|
Returns:
| Type | Description |
|---|---|
Dict[str, Any]
|
The engine's report |
Raises:
| Type | Description |
|---|---|
FileNotFoundError
|
The file does not exist and |
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
|
DssLockedError
|
HEC software has the file open (a |
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
¶
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
|
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 |
ImportError
|
If pyjnius ( |
DssCapabilityError
|
|
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
( |
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
¶
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
|
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" ... )