pydsstools.heclib.dss.HecDss.Open

class pydsstools.heclib.dss.HecDss.Open(dss_path, version=None, mode='rw')

Bases: Open

Open a DSS file and create a dataset object that supports input/output operations.

This class provides a high-level, user-friendly interface for working with HEC-DSS files. It supports reading and writing time series, paired data, and spatial grid data.

Parameters:

• dss_path (str or Path or PathLike) – Path to the DSS file.

• version ({6, 7} or None, optional) – DSS file version. If None, detect automatically. If creating a new file, None creates a version 7 file. Default is None.

• mode ({"rw", "r"}, optional) – File open mode. "rw" allows read/write; "r" is read-only. Default is “rw”.

Variables:

• mode (str) – The file access mode.

• version (int) – The DSS file version (6 or 7).

• filename (str) – Path to the DSS file.

Examples

Open a DSS file for reading and writing:

>>> from pydsstools.heclib.dss.HecDss import Open
>>> fid = Open("example.dss", mode="rw")

Open a DSS file as read-only:

>>> fid = Open("example.dss", mode="r")
>>> fid.close()

Use context manager for automatic cleanup:

>>> with Open("example.dss") as fid:
...     ts = fid.read_ts("/A/B/C/01JAN2020/1HOUR/F/")

See also

TimeSeriesContainer

Container for time series data

PairedDataContainer

Container for paired data

SpatialGridStruct

Structure for spatial grid data

__init__(dss_path, version=None, mode='rw')

Methods

__init__(dss_path[, version, mode])
check_file()	Run a thorough integrity check on this DSS file.
close(self)	Close the DSS file handle.
copy_from_file(src[, status_wanted])	Bulk-copy records from src into this file.
copy_path(pathname_in[, pathname_out, ...])	Copy one or more DSS records, optionally to a different file or pathname.
del_path(pathname)	Delete DSS record(s) matching the given pathname pattern.
export_binary(pathname[, output_dir, ...])	Read a binary record and save it to a file on disk.
export_file(dst_path[, version, overwrite, ...])	Export this DSS file to dst_path, optionally changing the DSS version.
get_status(self)	Get file operation status codes.
import_binary(filepath[, pathname, a, b, f])	Read a file from disk and store it as a binary DSS record.
path_dict([sub_type])	Get all pathnames in DSS file organized by data type.
path_exists(pathname)	Check if a DSS pathname exists in the file.
pd_info(pathname)	Get information about a paired data record.
preallocate_pd(pathname, shape, **kwargs)	Preallocate space for paired data record in DSS file.
put_array(pathname, *[, int_array, ...])	Write an array record to the DSS file.
put_binary(pathname, data, *[, data_type])	Write a binary record to the DSS file.
put_grid(data[, pathname, gridinfo, flipud, ...])	Write spatial grid to DSS-7 file.
put_grid0(data[, pathname, gridinfo, ...])	Write spatial grid to DSS-6 file.
put_pd(data[, location])	Write new paired data or edit an existing paired data record in the DSS file.
put_text(pathname, data)	Write a text or text-table record to the DSS file.
put_ts(data[, location, store_flag])	Write time-series data to DSS file.
read_array(pathname)	Read an array record from the DSS file.
read_binary(pathname)	Read a binary (FILE, IMAGE, or BLOB) record from the DSS file.
read_grid(pathname[, metadata_only])	Read spatial grid data from DSS file.
read_grid2(pathname[, metadata_only])	Read spatial grid data from DSS file and return as tuple.
read_pd(pathname[, window, dataframe, location])	Read paired data from DSS file.
read_pd_labels(pathname)	Read paired data labels from DSS file.
read_text(pathname)	Read a text or text-table record from the DSS file.
read_ts(pathname[, window, trim_missing, ...])	Read time-series record from DSS file.
ren_path(pathname_in[, pathname_out, transform])	Rename one or more DSS records.
search_path([pathname, sort])	Search for DSS pathnames matching a pattern.

Attributes

file_status
filename
read_status
version
write_status

read_ts(pathname, window=None, trim_missing=False, window_flag=0, value_precision='float', quality_notes=False, reg=False, ireg=False, location=None)

Read time-series record from DSS file.

Parameters:

• pathname (str or DssPathName) – DSS record pathname.

• window (tuple of (start, end) or None, optional) – Time window to read. If None, the date range encoded in the D-part of the pathname is used. Default is None.

• trim_missing (bool, optional) – If True, removes missing values at the beginning and end of the data set. Applies to regular time-series only. Default is False.

• window_flag ({0, 1, 2, 3}, optional) –

  Applies to irregular time series only. Controls how the time window is applied. Default is 0.

  Possible values:

  • 0 : Strictly adhere to the time window.

  • 1 : Also retrieve one value immediately before the start of the window.

  • 2 : Also retrieve one value immediately after the end of the window.

  • 3 : Retrieve one value immediately before the start and one immediately after the end of the window.

• value_precision ({"float", "double", "native"}, optional) –

  Controls the numeric precision of the retrieved values. Default is “float”.

  • ”float” : Return values as 32-bit floats.

  • ”double” : Return values as 64-bit doubles.

  • ”native” : Return values as stored; missing values returned as doubles.

• quality_notes (bool, optional) – If True, retrieve quality notes associated with each value when they exist. Default is False.

• reg (bool, optional) – If True, treat the data as a regular time series. Default is False.

• ireg (bool, optional) –

  If True, treat the data as an irregular time series. Default is False.

  If both reg and ireg are False or both are True, the type of time series will be determined from the E-part of pathname.

• location (bool or None, optional) – If True, also read the location record associated with the pathname and return (TimeSeriesStruct, LocationInfo). If no location record exists a warning is logged and None is returned in its place. Default is None (return TimeSeriesStruct only).

Returns:

• TimeSeriesStruct – Time series data structure containing the requested data.

• tuple of (TimeSeriesStruct, LocationInfo or None) – Returned when location=True.

Raises:

ValueError – If pathname does not correspond to a valid time series record or if window_flag is invalid.

Examples

Read time series with a specific time window:

>>> ts = fid.read_ts(pathname, window=('10MAR2006 24:00:00', '09APR2006 24:00:00'))

Read entire time series:

>>> ts = fid.read_ts(pathname)

Read regular time series with trimming:

>>> ts = fid.read_ts(pathname, trim_missing=True, reg=True)

Read time series and its location record together:

>>> ts, loc = fid.read_ts(pathname, location=True)

put_ts(data, location=None, store_flag=0, **kwargs)

Write time-series data to DSS file.

Parameters:

• data (str or DssPathName or TimeSeriesContainer) – Either a pathname string or a TimeSeriesContainer object.

• location (LocationInfo or None, optional) – If provided, write this location record after writing the time series. Default is None.

• store_flag (RegStoreFlag or IrregStoreFlag or int, optional) –

  Controls how existing data is handled on write. Default is 0.

  For regular time series (use RegStoreFlag):

  • 0 : Always replace data.

  • 1 : Only replace missing values.

  • 2 : Write even if all values are missing.

  • 3 : If all missing, do not write and delete record if it exists.

  • 4 : Do not allow a missing input value to replace a valid value.

  For irregular time series (use IrregStoreFlag):

  • 0 : Merge — insert new values; replace existing values at the same time.

  • 1 : Replace — remove all data in the start-to-end range and rewrite.

• **kwargs (Any) –

  Keyword arguments for TimeSeriesContainer when data is a pathname.

  Required kwargs when data is pathname:

  • valueslist or array-like

    Time series values.

  • For regular time-series (interval > 0):

    • start_timestr

      Starting date/time.

  • For irregular time-series (interval < 0):

    • timeslist of str

      List of date/time strings.

    • julian_basestr, optional

      Julian base date.

Return type:

None

Raises:

• TypeError – If data is not of expected type.

• ValueError – If required parameters are missing or invalid.

Examples

Write using TimeSeriesContainer:

>>> from pydsstools.heclib.dss.HecDss import Open
>>> from pydsstools.core import TimeSeriesContainer
>>> fid = Open("dss_file.dss", mode="rw")
>>> pathname = r"/A/B/C//1HOUR/F/"
>>> values = [10, 20, 30, 40, 50]
>>> interval = 1
>>> start_time = r"01JAN2025 1500"
>>> data_units = "ft"
>>> data_type = "inst"
>>> timezone = "UTC"
>>> tsc = TimeSeriesContainer(pathname, len(values), interval, values=values,
...                           start_time=start_time, data_units=data_units,
...                           data_type=data_type, tzid=timezone)
>>> fid.put_ts(tsc)

locationLocationInfo or None, optional

If provided, write this location record to the DSS file immediately after writing the time series. Default is None.

Write irregular time series without using TimeSeriesContainer:

>>> pathname = r"/A/B/C//IR-DAY/F/"
>>> julian_base = "01JAN2000"
>>> times = ["02JUL2010 1200", "05JAN2012 0000", "15MAR2014 0200",
...          "25FEB2018 0500", "19DEC2024 1200"]
>>> values = [1, 20, 30, 40, 50]
>>> fid.put_ts(pathname, values=values, times=times, julian_base=julian_base,
...            data_units=data_units, data_type=data_type, tzid=timezone)

Write time series with location metadata:

>>> from pydsstools.core.location import LocationInfo
>>> loc = LocationInfo("/A/B/C//1HOUR/F/", x=-118.5, y=34.0)
>>> fid.put_ts(tsc, location=loc)

read_pd(pathname, window=None, dataframe=True, location=None)

Read paired data from DSS file.

Parameters:

• pathname (str or DssPathName) – DSS record pathname.

• window (tuple of (int, int, int, int) or None, optional) –

  Index window to read. If None, all rows and columns are read. Default is None.

  Supported forms:

  • (row_start, row_end, col_start, col_end)

  Indexing rules:

  • Zero-based and inclusive at both ends.

  • row_start / col_start >= 0 (first row/column is 0).

  • row_end / col_end <= last valid index.

  • None for any bound selects the respective first/last index.

  • Negative indices are allowed (Python-style) and are wrapped.

  • If an end index overflows the table size, it is clipped.

  • Any other out-of-range condition raises IndexError.

• dataframe (bool, optional) – If True, return a pandas DataFrame. If False, return a PairedDataStruct object. Default is True.

• location (bool or None, optional) – If True, also read the location record associated with the pathname and return (result, LocationInfo). If no location record exists a warning is logged and None is returned in its place. Default is None (return data only). DSS-6 files raise NotImplementedError.

Returns:

• pandas.DataFrame or PairedDataStruct – Paired data in the requested format.

• tuple of (pandas.DataFrame or PairedDataStruct, LocationInfo or None) – Returned when location=True.

Raises:

• IndexError – If window indices are invalid or out of range.

• NotImplementedError – If location=True and the file is DSS-6.

Examples

Read paired data with a window:

>>> df = fid.read_pd(pathname, window=(2, 5, 0, None))

Read all paired data:

>>> df = fid.read_pd(pathname)

Read as PairedDataStruct:

>>> pds = fid.read_pd(pathname, dataframe=False)

Read paired data and its location record together:

>>> df, loc = fid.read_pd(pathname, location=True)

read_pd_labels(pathname)

Read paired data labels from DSS file.

Parameters:

pathname (str or DssPathName) – DSS record pathname.

Returns:

Dictionary mapping primary column names to label names.

Return type:

dict of str to str

Examples

>>> labels = fid.read_pd_labels("/A/B/STAGE-FLOW/D/E/F/")
>>> print(labels)
{'y0': 'Stage', 'y1': 'Flow'}

pd_info(pathname)

Get information about a paired data record.

Parameters:

pathname (str or DssPathName) – DSS record pathname.

Returns:

Dictionary containing paired data information with keys:

• ’curve_no’int

  Number of curves (columns).

• ’data_no’int

  Number of data points (rows).

• ’dtype’int

  Data type code.

• ’label_size’int

  Average label size in characters.

Return type:

dict

Examples

>>> info = fid.pd_info("/A/B/STAGE-FLOW/D/E/F/")
>>> print(f"Curves: {info['curve_no']}, Points: {info['data_no']}")
Curves: 2, Points: 100

put_pd(data, location=None, **kwargs)

Write new paired data or edit an existing paired data record in the DSS file.

Parameters:

• data (PairedDataContainer or str or DssPathName) –

  Input data to write. Can be:

  • A PairedDataContainer object.

  • A string or DssPathName specifying an existing or new DSS record pathname.

• location (LocationInfo or None, optional) – If provided, write this location record after writing the paired data. DSS-7 only; DSS-6 files raise NotImplementedError. Default is None.

• **kwargs (Any) –

  Additional keyword arguments or attributes for the PairedDataContainer.

  When writing a DataFrame:

  • y_datapandas.DataFrame

    DataFrame containing paired data.

  • x_unitsstr

    Units for x-axis data.

  • x_typestr

    Type of x-axis data (e.g., “linear”).

  • y_unitsstr

    Units for y-axis data.

  • y_typestr

    Type of y-axis data (e.g., “linear”).

  When writing a single curve to preallocated record:

  • col_indexint

    Column index (0-based) to write to.

  • y_datalist or array-like

    Y-axis values for the curve.

  • windowtuple of (int, int), optional

    Row range (start, end) for writing.

  • y_labelslist of str, optional

    Labels for y-axis curves.

Return type:

None

Raises:

• ValueError – If incompatible parameters are provided or indices are out of range.

• IndexError – If data has too many values.

Examples

Write PairedDataContainer:

>>> from pydsstools.core import PairedDataContainer
>>> pathname = "/A/B/STAGE-FLOW/D/E/F/"
>>> curves = 2
>>> rows = 5
>>> pdc = PairedDataContainer(pathname, (rows, curves))
>>> pdc.x_data = [0.1, 0.2, 0.3, 0.4, 0.5]
>>> pdc.y_data = [[10, 20, 30, 40, 50], [1, 2, 3, 4, 5]]
>>> pdc.x_units = "ft"
>>> pdc.x_type = "linear"
>>> pdc.y_units = "cfs"
>>> pdc.y_type = "linear"
>>> fid.put_pd(pdc)

Write DataFrame:

>>> import pandas as pd
>>> pathname = "/A/B/STAGE-FLOW/D/E/F/"
>>> df = pd.DataFrame({"Curve #1": [1, 2], "Curve #2": [3, 4]}, index=[0.5, 0.6])
>>> fid.put_pd(pathname, x_units="ft", x_type="linear", y_data=df,
...            y_units="cfs", y_type="linear")

Write a curve to preallocated paired data record:

>>> pathname = "/A/B/STAGE-FLOW/D/E/PREALLOC/"
>>> fid.put_pd(pathname, col_index=2, y_data=[1, 2, 3, 4], window=(2, 5))

preallocate_pd(pathname, shape, **kwargs)

Preallocate space for paired data record in DSS file.

This method creates an empty paired data structure in the DSS file that can later be filled with individual curves using put_pd with col_index parameter.

Parameters:

• pathname (str or DssPathName) – DSS record pathname.

• shape (list of int or tuple of (int, int)) – Shape of the paired data as (rows, columns).

• **kwargs (Any) – Additional keyword arguments for PairedDataContainer initialization, such as x_units, y_units, x_type, y_type, etc.

Return type:

None

Examples

>>> pathname = "/A/B/STAGE-FLOW/D/E/PREALLOC/"
>>> fid.preallocate_pd(pathname, shape=(100, 5), x_units="ft", y_units="cfs")

read_array(pathname)

Read an array record from the DSS file.

Parameters:

pathname (str or DssPathName) – DSS record pathname.

Returns:

Dictionary with any of the following keys, depending on what was stored:

• 'int_array' : numpy.ndarray of int32

• 'float_array' : numpy.ndarray of float32

• 'double_array' : numpy.ndarray of float64

Return type:

dict

Examples

>>> result = fid.read_array("/A/B/COUNTS/D/E/F/")
>>> int_vals = result.get('int_array')
>>> float_vals = result.get('float_array')

put_array(pathname, *, int_array=None, float_array=None, double_array=None)

Write an array record to the DSS file.

Parameters:

• pathname (str or DssPathName) – DSS record pathname.

• int_array (array-like or None, optional) – Integer values to store. Converted to int32.

• float_array (array-like or None, optional) – Float values to store. Converted to float32.

• double_array (array-like or None, optional) – Double values to store. Converted to float64.

Notes

At least one of the three array arguments must be provided.

Examples

>>> import numpy as np
>>> fid.put_array("/A/B/COUNTS/D/E/F/", int_array=[1, 2, 3])
>>> fid.put_array("/A/B/DATA/D/E/F/", float_array=np.array([1.0, 2.0]),
...               double_array=np.array([3.14, 2.72]))

read_text(pathname)

Read a text or text-table record from the DSS file.

Parameters:

pathname (str or DssPathName) – DSS record pathname.

Returns:

Structure wrapping the raw C record. Applicable to both plain text and text-table records.

Key properties:

• text : str or None — plain text content.

• table : list of list of str, or None — table content. Outer list is rows, inner list is columns.

• labels : list of str — column labels (empty list if none).

• rows : int — number of table rows (0 for text-only records).

• cols : int — number of table columns (0 for text-only).

• dtype : str or None — one of 'text', 'text_list', 'text_table', or None.

Return type:

TextStruct

Examples

>>> ts = fid.read_text("/A/B/NOTE/D/E/F/")
>>> ts.text
'some note'
>>> ts = fid.read_text("/A/B/COLORS-PROPS/D/E/F/")
>>> ts.table
[['Red', 'long'], ['Blue', 'short']]
>>> ts.rows, ts.cols
(2, 2)

put_text(pathname, data)

Write a text or text-table record to the DSS file.

Parameters:

• pathname (str or DssPathName) – DSS record pathname.

• data (TextContainer or TextStruct or pandas.DataFrame) –

  Content to write. The text, table, and labels properties are read from the object and control which C-level write function is called:

  • text only → plain text record (DSS-6 and DSS-7).

  • table only → text-table record (DSS-7 only).

  • text and table → combined record (DSS-7 only).

  Passing a TextStruct returned by read_text allows round-trip reads and writes without unpacking.

  Passing a pandas.DataFrame saves it as a text table (DSS-7 only). Column names become the table labels. Numeric columns are converted to strings using float32 → 7 significant figures and float64 → 15 significant figures (g format, trailing zeros stripped). NaN values become "".

Raises:

• TypeError – If data is not a TextContainer, TextStruct, or pandas.DataFrame.

• ValueError – If the data has no text or table content, or if the DSS file version does not support the requested record type.

Examples

Plain text (DSS-6 or DSS-7):

>>> fid.put_text("/A/B/NOTE/D/E/F/", TextContainer("/A/B/NOTE/D/E/F/", text="Hello"))

Text list (DSS-7 only):

>>> tc = TextContainer("/A/B/COLORS/D/E/F/", table=[["Red"], ["Blue"], ["Yellow"]])
>>> fid.put_text("/A/B/COLORS/D/E/F/", tc)

Full table with labels (DSS-7 only):

>>> tc = TextContainer(
...     "/A/B/COLORS-PROPS/D/E/F/",
...     table=[["long", "hot"], ["short", "cool"]],
...     labels=["wave length", "temperature"],
... )
>>> fid.put_text("/A/B/COLORS-PROPS/D/E/F/", tc)

Round-trip via TextStruct:

>>> ts = fid.read_text("/A/B/NOTE/D/E/F/")
>>> fid2.put_text("/A/B/NOTE/D/E/F/", ts)

DataFrame (DSS-7 only):

>>> import pandas as pd
>>> df = pd.DataFrame({"Color": ["Red", "Blue"], "Wavelength": [700.0, 450.0]})
>>> fid.put_text("/A/B/COLORS/D/E/F/", df)

read_binary(pathname)

Read a binary (FILE, IMAGE, or BLOB) record from the DSS file.

Parameters:

pathname (str or DssPathName) – DSS record pathname.

Returns:

Structure wrapping the raw C record.

Key properties:

• data : bytes — raw binary content, exact byte count.

• filename : str — filename from the C-part of the pathname.

• extension : str — file extension from the E-part (no dot).

• data_type : BinaryType — FILE, IMAGE, or UNDEFINED.

• is_image : bool — True for IMAGE records.

• size : int — byte count.

• save_to(path) — write bytes to a file; returns Path.

Return type:

BinaryStruct

Examples

>>> bs = fid.read_binary("/a/b/report.pdf/FILE/pdf/f/")
>>> bs.data
b'%PDF-1.4 ...'
>>> bs.filename
'report.pdf'
>>> bs.data_type
<BinaryType.FILE: 600>

put_binary(pathname, data, *, data_type=None)

Write a binary record to the DSS file.

Parameters:

• pathname (str or DssPathName) – DSS record pathname. D-part is forced to match data_type.

• data (BinaryContainer or BinaryStruct or bytes) – Content to write. When data is a BinaryContainer or BinaryStruct the embedded data and data_type are used directly. When data is bytes, the record is constructed from pathname and optional data_type.

• data_type (BinaryType or None, optional) – Override only when data is bytes. If None the type is inferred from the D-part or E-part of pathname. Ignored when data is BinaryContainer or BinaryStruct.

Raises:

TypeError – If data is not a BinaryContainer, BinaryStruct, or bytes.

Examples

>>> fid.put_binary("/a/b/report.pdf/FILE/pdf/f/", pdf_bytes)
>>> fid.put_binary("/a/b/photo.jpg/IMAGE/jpg/f/", jpeg_bytes,
...                data_type=BinaryType.IMAGE)
>>> container = BinaryContainer("/a/b/report.pdf/FILE/pdf/f/", pdf_bytes)
>>> fid.put_binary("/a/b/report.pdf/FILE/pdf/f/", container)

export_binary(pathname, output_dir='.', output_path=None)

Read a binary record and save it to a file on disk.

Parameters:

• pathname (str or DssPathName) – DSS record pathname to read.

• output_dir (str or Path, optional) – Directory to write to. The filename is taken from the C-part of pathname. Defaults to the current directory.

• output_path (str or Path, optional) – Full destination path. When given, output_dir is ignored.

Returns:

Path to the written file.

Return type:

Path

Examples

>>> dest = fid.export_binary("/a/b/report.pdf/FILE/pdf/f/",
...                          output_dir="C:/output")
>>> dest
PosixPath('C:/output/report.pdf')

import_binary(filepath, pathname=None, *, a='', b='', f='')

Read a file from disk and store it as a binary DSS record.

The data_type and D-part are always derived automatically from the file extension; known image extensions yield BinaryType.IMAGE (610), all other extensions yield BinaryType.FILE (600).

Parameters:

• filepath (str or Path) – Path to the file to import.

• pathname (str or None, optional) – DSS pathname to store under. If None, an auto-built pathname is used: C-part = filename, D-part = 'IMAGE' or 'FILE', E-part = extension without dot.

• a (str) – A, B, F parts of the auto-built pathname (used only when pathname is None).

• b (str) – A, B, F parts of the auto-built pathname (used only when pathname is None).

• f (str) – A, B, F parts of the auto-built pathname (used only when pathname is None).

Examples

>>> fid.import_binary("C:/reports/summary.pdf", b="ProjectX")
>>> fid.import_binary("C:/photos/site.jpg")

read_grid(pathname, metadata_only=False)

Read spatial grid data from DSS file.

Reads both version 0 (DSS-6 format) and version 100 (latest DSS-7 format) spatial grid data from DSS file. The method automatically detects the grid version and converts older formats to the modern format.

Parameters:

• pathname (str or DssPathName) – DSS record pathname.

• metadata_only (bool, optional) – If True, read only metadata without grid data. Default is False.

Returns:

Spatial grid data structure containing grid data and metadata.

Return type:

SpatialGridStruct

Examples

Read grid data:

>>> sg = fid.read_grid("/A/B/PRECIP/01JAN2020:0000/01JAN2020:2400/GRIDTYPE/")

Read only metadata:

>>> sg = fid.read_grid(pathname, metadata_only=True)
>>> print(sg.gridinfo.shape)
(100, 200)

Notes

There are slight differences in grid metadata between version-0 and version-100 grids. For example, the RLE-style compression used for precipitation data is supported only in version-0 grids. When a version-0 grid is read using read_grid, this compression method is reported in the returned gridinfo as undefined compression. Consequently, if a version-0 grid needs to be read and written back while preserving its original format, the read_grid2 method should be used instead.

read_grid2(pathname, metadata_only=False)

Read spatial grid data from DSS file and return as tuple.

Reads both version 0 (DSS-6 format) and version 100 (latest DSS-7 format) spatial grid data. This method provides an alternative return format compared to read_grid.

Parameters:

• pathname (str or DssPathName) – DSS record pathname.

• metadata_only (bool, optional) – If True, return only metadata (gridinfo). Default is False.

Returns:

If metadata_only is False, returns tuple of (numpy.ndarray, gridinfo). If metadata_only is True, returns gridinfo only. Returns None if grid data is invalid.

Return type:

tuple of (numpy.ndarray, GridInfo) or GridInfo or None

Examples

Read grid as array and gridinfo:

>>> data, gridinfo = fid.read_grid2(pathname)
>>> print(data.shape, gridinfo.grid_type)

Read only gridinfo:

>>> gridinfo = fid.read_grid2(pathname, metadata_only=True)

put_grid(data, pathname=None, gridinfo=None, flipud=True, inplace=False, compute_stats=True, transform=None, normalize=True)

Write spatial grid to DSS-7 file.

Writing to DSS-6 file is not allowed. Use put_grid0 for DSS-6 files.

Parameters:

• data (SpatialGridStruct or numpy.ndarray or numpy.ma.MaskedArray) –

  Grid data to write.

  • numpy.ndarray: np.nan and nodata (from gridinfo)

    and UNDEFINED values are treated as nodata.

  • numpy.ma.MaskedArray: masked elements are treated as nodata.

  • SpatialGridStruct: a structured object containing grid and metadata.

• pathname (str or DssPathName or None, optional) – Pathname for the DSS record. It can be None for SpatialGridStruct. The dates in parts D and E are automatically reformatted to correct convention. Part D uses the beginning of the day (e.g., 02JAN2025:0000) while Part E uses the end of the previous day convention (e.g., 01JAN2025:2400). Default is None.

• gridinfo (GridInfo or subclass or None, optional) –

  Metadata describing the grid. Can be one of:

  • GridInfo, HrapInfo, or AlbersInfo: requires data_type, cell_size, shape at minimum.

  • SpecifiedInfo: additionally nodata and crs.

  Default is None.

• flipud (bool, optional) – If True, flips the rows of the data array upside down before writing. This is necessary when the input data is numpy array with origin at top-left (e.g., array representing raster image in rasterio). Default is True.

• inplace (bool, optional) – If True, tries to modify the data in place to reduce memory usage. Default is False.

• compute_stats (bool or list of float, optional) –

  Controls whether and how statistics are computed for the grid data. Default is True.

  Possible values:

  • True: compute min, max, mean, range values, and range counts.

  • False: do not compute statistics.

  • list of float: compute “greater than or equal to” counts for the specified values (maximum of 19 thresholds, excluding nodata).

• transform (Any or None, optional) – Spatial transform information (e.g., affine transform). If provided, it overrides transform parameters in gridinfo. Default is None.

• normalize (bool, optional) – If True, tries to normalize coords_cell0 and lower_left_cell based on min_xy or input transform parameter. Default is True.

Return type:

None

Raises:

Exception – If D-part or E-part is not a valid datetime string for time-stamped grids.

Examples

Write grid from array:

>>> import numpy as np
>>> from pydsstools.core.gridinfo import SpecifiedGridInfo
>>> data = np.random.rand(100, 200).astype(np.float32)
>>> pathname = "/A/B/PRECIP/01JAN2020:0000/01JAN2020:2400/SHG/"
>>> gridinfo = SpecifiedGridInfo(data_type="PER-CUM", cell_size=2000.0,
...                              lower_left_x=100000, lower_left_y=200000,
...                              rows=100, cols=200, nodata=-999.0)
>>> fid.put_grid(data, pathname, gridinfo)

Write with custom statistics thresholds:

>>> fid.put_grid(data, pathname, gridinfo, compute_stats=[0, 10, 50, 100])

put_grid0(data, pathname=None, gridinfo=None, flipud=True, inplace=False, compute_stats=True, transform=None, normalize=True)

Write spatial grid to DSS-6 file.

Writing to DSS-7 file using this method is experimental and may cause problems. Use put_grid for DSS-7 files instead.

Parameters:

• data (SpatialGridStruct or numpy.ndarray or numpy.ma.MaskedArray) –

  Grid data to write.

  • numpy.ndarray: np.nan and nodata (from gridinfo)

    and UNDEFINED values are treated as nodata.

  • numpy.ma.MaskedArray: masked elements are treated as nodata.

  • SpatialGridStruct: a structured object containing grid and metadata.

• pathname (str or DssPathName or None, optional) – Pathname for the DSS record. It can be None for SpatialGridStruct. The dates in parts D and E are automatically reformatted to correct convention. Part D uses the beginning of the day (e.g., 02JAN2025:0000) while Part E uses the end of the previous day convention (e.g., 01JAN2025:2400). Default is None.

• gridinfo (GridInfo or GridInfo6 or None, optional) – Metadata describing the grid for version 6 and 7. Default is None.

• flipud (bool, optional) – If True, flips the rows of the data array upside down before writing. This is necessary when the input data is numpy array with origin at top-left (e.g., array representing raster image in rasterio). Default is True.

• inplace (bool, optional) – If True, tries to modify the data in place to reduce memory usage. Default is False.

• compute_stats (bool or list of float, optional) –

  Controls whether and how statistics are computed for the grid data. Default is True.

  Possible values:

  • True: compute min, max, mean, range values, and range counts.

  • False: do not compute statistics.

  • list of float: compute “greater than or equal to” counts for the specified values (maximum of 19 thresholds, excluding nodata).

• transform (Any or None, optional) – Spatial transform information (e.g., affine transform). If provided, it overrides transform parameters in gridinfo. Default is None.

• normalize (bool, optional) – If True, tries to normalize coords_cell0 and lower_left_cell based on min_xy or input transform parameter. Default is True.

Return type:

None

Raises:

Exception – If D-part or E-part is not a valid datetime string for time-stamped grids.

Notes

This method writes grid data in DSS-6 (version 0) format. It is primarily intended for maintaining compatibility with legacy DSS-6 files.

copy_path(pathname_in, pathname_out=None, *, dss_out=None, transform=None)

Copy one or more DSS records, optionally to a different file or pathname.

Parameters:

• pathname_in (str or DssPathName) – Source pathname. May contain * wildcards when using transform or doing a same-path batch copy to dss_out.

• pathname_out (str or DssPathName, optional) – Destination pathname. Defaults to pathname_in when omitted, which is the common case when copying to a different file. Must not be combined with transform, and must not be used when pathname_in contains wildcards.

• dss_out (Open, keyword-only, optional) – Destination DSS file. Must be open in "rw" mode. When omitted the copy is within this file (useful for duplicating a record under a new name).

• transform (callable, keyword-only, optional) – A function (str) -> str applied to every pathname matched by pathname_in. Receives the full source pathname string and must return a valid DSS pathname string for the destination. Must not be combined with pathname_out.

Returns:

Number of records copied.

Return type:

int

Raises:

ValueError – If pathname_out and transform are both supplied; if pathname_in contains wildcards and pathname_out is also supplied; or if the destination file is not open in "rw" mode.

Examples

Copy within the same file (rename-by-copy):

>>> fid.copy_path("/A/B/C/D/E/F/", "/A/B/C_COPY/D/E/F/")

Cross-file copy, keeping the same pathname (no need to repeat it):

>>> with Open("target.dss", mode="rw") as dst:
...     fid.copy_path("/A/B/C/D/E/F/", dss_out=dst)

Batch copy all matching records to another file, same pathnames:

>>> with Open("target.dss", mode="rw") as dst:
...     n = fid.copy_path("/A/B/*/D/E/F/", dss_out=dst)

Batch copy with path rewriting via transform:

>>> with Open("target.dss", mode="rw") as dst:
...     fid.copy_path(
...         "/A/B/*/D/E/F/",
...         transform=lambda p: p.replace("/OLD_BASIN/", "/NEW_BASIN/"),
...         dss_out=dst,
...     )

ren_path(pathname_in, pathname_out=None, transform=None)

Rename one or more DSS records.

Exactly one of pathname_out or transform must be supplied.

For time-series records (RTS/ITS) the D and E parts encode the time window and cannot be changed by rename; a ValueError is raised if the caller attempts to do so.

Parameters:

• pathname_in (str or DssPathName) – Source pathname, or a wildcard pattern (when using transform).

• pathname_out (str or DssPathName, optional) – New pathname for a direct one-to-one rename. Must not be given together with transform.

• transform (callable, optional) – A function (str) -> str applied to every pathname that matches pathname_in. Receives the full pathname string and must return a valid DSS pathname string. Must not be given together with pathname_out.

Return type:

None

Raises:

ValueError – If both pathname_out and transform are supplied, if neither is supplied, or if a rename would change the D or E part of a time-series record.

Examples

Direct rename:

>>> fid.ren_path("/A/B/FLOW/D/E/F/", "/A/B/FLOW_CFS/D/E/F/")

Batch rename using a transform (change C-part for all matching records):

>>> fid.ren_path("/A/B/*/D/E/F/", transform=lambda p: p.replace("/OLD/", "/NEW/", 1))

del_path(pathname)

Delete DSS record(s) matching the given pathname pattern.

Parameters:

pathname (str or DssPathName) – Pathname or pathname pattern to delete. Supports wildcards (*).

Return type:

None

Examples

Delete specific record:

>>> fid.del_path("/A/B/C/D/E/F/")

Delete multiple records with wildcards:

>>> fid.del_path("/A/B/*/D/E/F/")

search_path(pathname='', sort=False)

Search for DSS pathnames matching a pattern.

Parameters:

• pathname (str or DssPathName, optional) – Pathname pattern which can include wildcard (*) for defining search pattern. Empty string returns all pathnames. Default is “”.

• sort (bool, optional) – If True, sort the returned pathnames. Default is False.

Returns:

List of matching pathnames.

Return type:

list of str

Examples

Get all pathnames:

>>> paths = fid.search_path()

Search with pattern:

>>> paths = fid.search_path("/A/B/*/D/E/F/")

Get sorted results:

>>> paths = fid.search_path("/A/*/*/*/*/F/", sort=True)

path_exists(pathname)

Check if a DSS pathname exists in the file.

For pathnames whose D-part and E-part both contain a date and time component (e.g. 2 June 2026:0000), both parts are normalized before the lookup: the D-part expresses midnight as 0000 of the current day and the E-part expresses midnight as 2400 of the previous day. This resolves day-boundary ambiguity without changing non-datetime parts (interval names, empty parts, etc.).

Note

Grid D-part and E-part dates are stored verbatim in the DSS file. The standard DSS date format used here is date_style=104 (HecTime), which produces "02JUN2026" — e.g. "02JUN2026:1400". DSS pathname lookup is case-insensitive so date_style=4 ("02Jun2026") is equivalent, but 104 is used to match the canonical uppercase DSS convention. Normalization here uses the same style so the lookup pathname matches exactly what is stored on disk.

Parameters:

pathname (str or DssPathName) – DSS pathname to check.

Returns:

True if the record exists, False otherwise.

Return type:

bool

Examples

>>> fid.path_exists("/A/B/PRECIP/01JAN2020:0000/01JAN2020:2400/F/")
True

>>> # Day-boundary variant is normalized before lookup
>>> fid.path_exists("/A/B/PRECIP/31DEC2019:2400/01JAN2020:2400/F/")
True

path_dict(sub_type=False)

Get all pathnames in DSS file organized by data type.

Parameters:

sub_type (bool, optional) – If True, separate time series into regular and irregular, and grids by type. If False, group all time series together and all grids together. Default is False.

Returns:

Dictionary mapping data type names to lists of pathnames.

When sub_type is True, keys include:

• ”ts-reg”: Regular time series

• ”ts-irreg”: Irregular time series

• ”pd”: Paired data

• ”text”: Text data

• ”text-table”: Text tables

• ”grid-undefined”: Undefined grid type

• ”grid-hrap”: HRAP grids

• ”grid-albers”: Albers grids

• ”grid-spec”: Specified grids

• ”tin”: TIN data

• ”location”: Location data

• ”array”: Array data

• ”image”: Image data

• ”generic”: Generic data

• ”undefined”: Undefined data types

When sub_type is False, keys include:

• ”ts”: All time series (regular + irregular)

• ”grid”: All grids (undefined + hrap + albers + specified)

• Other keys same as above

Return type:

dict of str to list of str

Examples

Get all paths grouped by general type:

>>> paths = fid.path_dict()
>>> print(f"Time series: {len(paths['ts'])}")
>>> print(f"Paired data: {len(paths['pd'])}")

Get paths with detailed sub-types:

>>> paths = fid.path_dict(sub_type=True)
>>> print(f"Regular TS: {len(paths['ts-reg'])}")
>>> print(f"Irregular TS: {len(paths['ts-irreg'])}")

check_file()

Run a thorough integrity check on this DSS file.

Wraps zcheckFile via check_file(). Runs sub-checks in sequence and returns on the first failure, so the returned count reflects only the first failing sub-check:

• DSS-6: page/node blocks, links, pathname tables.

• DSS-7: links, pathname tables, pathname bins, hash table.

This is the most resource-intensive function in the DSS library; use it for diagnostics and file-recovery workflows, not routine access.

Returns:

• 0 — file is clean.

• > 0 — error count from the first failing sub-check.

Return type:

int

Raises:

DssStatusException – If zcheckFile returns a negative DSS error code (severe / unrecoverable error).

Examples

>>> with Open("data.dss") as fid:
...     errors = fid.check_file()
...     if errors:
...         print(f"{errors} integrity error(s) found")

copy_from_file(src, status_wanted=CopyRecordFlag.valid)

Bulk-copy records from src into this file.

Wraps copy_file(). Both files must already be open. See export_file() for full behaviour details, including existing-record semantics.

Parameters:

• src (Open) – Source DSS file handle (already open).

• status_wanted (CopyRecordFlag, optional) – Which records to copy. Default is CopyRecordFlag.valid.

Returns:

0 (STATUS_OKAY) on success, negative DSS error code on failure.

Return type:

int

Examples

>>> with Open("source.dss") as src, Open("dest.dss") as dst:
...     dst.copy_from_file(src)

export_file(dst_path, version=None, *, overwrite=False, status_wanted=CopyRecordFlag.valid, squeeze_after=False)

Export this DSS file to dst_path, optionally changing the DSS version.

Uses zcopyFile for all cases — both same-version and cross-version — so status_wanted applies uniformly regardless of the target version. Cross-version data translation (DSS-6 ↔ DSS-7) is handled transparently by the C library at the record level.

The destination version is controlled entirely by how dst_path is opened or created:

• New file — created at target_version.

• Existing file, matching version — opened as-is; records are merged in (time series) or replaced (all other types).

• Existing file, wrong version — ValueError is raised unless overwrite=True, in which case the file is deleted and recreated at target_version.

Parameters:

• dst_path (str or Path) – Path for the output file.

• version ({6, 7} or None, optional) – Target DSS version. None (default) uses self.version.

• overwrite (bool, keyword-only, optional) – If dst_path exists at a different version than target_version, delete it before writing. Default False.

• status_wanted (CopyRecordFlag, keyword-only, optional) – Which records to copy. Default CopyRecordFlag.valid.

• squeeze_after (bool, keyword-only, optional) – If True, squeeze dst_path after copying to reclaim freed space left by replaced records. Default False.

Returns:

0 (STATUS_OKAY) on success.

Return type:

int

Raises:

• ValueError – If dst_path exists at a different version than target_version and overwrite is False.

• DssStatusException – If zcopyFile returns a negative error code.

Examples

Copy to a new file (same version):

>>> fid.export_file("backup.dss")

Convert DSS-7 to DSS-6:

>>> fid.export_file("data_v6.dss", version=6)

Overwrite an existing file at a different version:

>>> fid.export_file("data_v6.dss", version=6, overwrite=True)

Copy primary records only and compact the result:

>>> fid.export_file("primary.dss", status_wanted=CopyRecordFlag.primary,
...                 squeeze_after=True)