suxarray.core package

Submodules

suxarray.core.api module

suxarray.core.api.open_grid(files_out2d: str | PathLike | list | tuple, files_zcoords: str | PathLike | list | tuple | None = None, chunks: Dict[str, int] | None = None) → Dataset[source]

Open SCHISM out2d and zCoordinates files and return a grid object

Parameters

files_out2dstr, os.PathLike, list, tuple

SCHISM out2d files

files_zcoordsstr, os.PathLike, list, tuple

SCHISM zCoordinates files

chunksdict, optional

Chunks for dask

Returns

suxarray.Grid

suxarray.core.api.open_hgrid_gr3(path_hgrid: str | PathLike) → Grid[source]

Read SCHISM hgrid.gr3 file and return a suxarray grid

Parameters

suxarray.core.api.read_grid(ds_out2d: Dataset, ds_zcoords: Dataset | None = None) → Grid[source]

Read grid information from xarray datasets and return a suxarray grid

Parameters

ds_out2dxr.Dataset

Dataset containing SCHISM out2d-like information

ds_zcoordsxr.Dataset, optional

Dataset containing SCHISM z-coordinate like information

Returns

suxarray.Grid

suxarray.core.api.read_schism_nc(grid: Grid, ds_data: Dataset) → SxDataset[source]
suxarray.core.api.write_gr3(sxda: SxDataArray, file_gr3: str | PathLike, fill_value: float | None = -9999.0) → None[source]

Write a SCHISM grid to a gr3 file

Parameters

sxdaSxDataArray

SCHISM data array to write out

file_gr3str or Path

Path to the output gr3 file

fill_valuefloat, optional

Fill value to use for missing values

suxarray.core.api.write_schism_grid(grid: Grid, file_gridout: str | PathLike, da: DataArray | None = None) → None[source]

Write a SCHISM grid to a NetCDF file

The goal of this function is to write a SCHISM grid information to a NetCDF file that can be understood by SCHISM VisIt plugin.

Parameters

file_gridoutstr or Path

Path to the output NetCDF file

gridGrid

SCHISM grid object

suxarray.core.api.write_schism_nc(sxda: SxDataArray, file_dataout: str | PathLike | None = None) → None[source]

Write a SCHISM data array to NetCDF files

NOTE: WIP. The API is not finalized.

Parameters

sxdaSxDataset

SCHISM data array

file_dataoutstr or Path, optional

Path to the output NetCDF file

suxarray.core.dataarray module

class suxarray.core.dataarray.SxDataArray(*args, sxgrid: Grid = None, **kwargs)[source]

Bases: UxDataArray

depth_average() → SxDataArray[source]

Calculate depth-average of a variable

This may need to be moved to a separate file. TODO: Currently this assumes nodal values. Need to support other element. TODO: Maybe this can be moved to another file.

Parameters

None

Returns

daSxDataArray

Depth averaged variable

integrate(quadrature_rule: str | None = 'triangular', order: int | None = 2) → SxDataArray[source]

Computes the integral of a data variable.

Parameters

quadrature_rulestr, optional

Quadrature rule to use. Defaults to “triangular”.

orderint, optional

Order of quadrature rule. Defaults to 4.

Returns

uxdaUxDataArray

UxDataArray containing the integrated data variable

Examples

Open a Uxarray dataset and compute the integral

>>> import uxarray as ux
>>> uxds = ux.open_dataset("grid.ug", "centroid_pressure_data_ug")
>>> integral = uxds["psi"].integrate()
isel(ignore_grid=False, *args, **kwargs)[source]

Grid-aware index selection.

Performs xarray-style integer-location indexing along specified dimensions. If a single grid dimension (‘n_node’, ‘n_edge’, or ‘n_face’) is provided and ignore_grid=False, the underlying grid is sliced accordingly, and remaining indexers are applied to the resulting DataArray.

Parameters

indexersMapping[Any, Any], optional

A mapping of dimension names to indexers. Each indexer may be an integer, slice, array-like, or DataArray. Mutually exclusive with indexing via kwargs.

dropbool, default=False

If True, drop any coordinate variables indexed by integers instead of retaining them as length-1 dimensions.

missing_dims{‘raise’, ‘warn’, ‘ignore’}, default=’raise’

Behavior when indexers reference dimensions not present in the array. - ‘raise’: raise an error - ‘warn’: emit a warning and ignore missing dimensions - ‘ignore’: ignore missing dimensions silently

ignore_gridbool, default=False

If False (default), allow slicing on one grid dimension to automatically update the associated UXarray grid. If True, fall back to pure xarray behavior.

inverse_indicesbool, default=False

For grid-based slicing, pass this flag to Grid.isel to invert indices when selecting (useful for staggering or reversing order).

**indexers_kwargsdimension=indexer pairs, optional

Alternative syntax for specifying indexers via keyword arguments.

Returns

UxDataArray

A new UxDataArray indexed according to indexers and updated grid if applicable.

Raises

TypeError

If indexers is provided and is not a Mapping.

ValueError

If more than one grid dimension is selected and ignore_grid=False.

item(*args)

Copy an element of an array to a standard Python scalar and return it.

Parameters

*args : Arguments (variable number and type)

  • none: in this case, the method only works for arrays with one element (a.size == 1), which element is copied into a standard Python scalar object and returned.

  • int_type: this argument is interpreted as a flat index into the array, specifying which element to copy and return.

  • tuple of int_types: functions as does a single int_type argument, except that the argument is interpreted as an nd-index into the array.

Returns

zStandard Python scalar object

A copy of the specified element of the array as a suitable Python scalar

Notes

When the data type of a is longdouble or clongdouble, item() returns a scalar array object because there is no available Python scalar that would not lose information. Void arrays return a buffer object for item(), unless fields are defined, in which case a tuple is returned.

item is very similar to a[args], except, instead of an array scalar, a standard Python scalar is returned. This can be useful for speeding up access to elements of the array and doing arithmetic on elements of the array using Python’s optimized math.

Examples

>>> import numpy as np
>>> np.random.seed(123)
>>> x = np.random.randint(9, size=(3, 3))
>>> x
array([[2, 2, 6],
       [1, 3, 6],
       [1, 0, 1]])
>>> x.item(3)
1
>>> x.item(7)
0
>>> x.item((0, 1))
2
>>> x.item((2, 2))
1

For an array with object dtype, elements are returned as-is.

>>> a = np.array([np.int64(1)], dtype=object)
>>> a.item() #return np.int64
np.int64(1)
searchsorted(v, side='left', sorter=None)

Find indices where elements of v should be inserted in a to maintain order.

For full documentation, see numpy.searchsorted

See Also

numpy.searchsorted : equivalent function

subset

alias of DataArraySubsetAccessor

property sxgrid: Grid

suxarray.core.dataset module

suxarray module

suxarray is a module that extends the functionality of uxarray for the SCHISM grid.

class suxarray.core.dataset.SxDataset(*args, sxgrid: Grid = None, source_datasets: str | None = None, **kwargs)[source]

Bases: UxDataset

property sxgrid

suxarray.core.utils module

Module contents

class suxarray.core.SxDataArray(*args, sxgrid: Grid = None, **kwargs)[source]

Bases: UxDataArray

depth_average() → SxDataArray[source]

Calculate depth-average of a variable

This may need to be moved to a separate file. TODO: Currently this assumes nodal values. Need to support other element. TODO: Maybe this can be moved to another file.

Parameters

None

Returns

daSxDataArray

Depth averaged variable

integrate(quadrature_rule: str | None = 'triangular', order: int | None = 2) → SxDataArray[source]

Computes the integral of a data variable.

Parameters

quadrature_rulestr, optional

Quadrature rule to use. Defaults to “triangular”.

orderint, optional

Order of quadrature rule. Defaults to 4.

Returns

uxdaUxDataArray

UxDataArray containing the integrated data variable

Examples

Open a Uxarray dataset and compute the integral

>>> import uxarray as ux
>>> uxds = ux.open_dataset("grid.ug", "centroid_pressure_data_ug")
>>> integral = uxds["psi"].integrate()
isel(ignore_grid=False, *args, **kwargs)[source]

Grid-aware index selection.

Performs xarray-style integer-location indexing along specified dimensions. If a single grid dimension (‘n_node’, ‘n_edge’, or ‘n_face’) is provided and ignore_grid=False, the underlying grid is sliced accordingly, and remaining indexers are applied to the resulting DataArray.

Parameters

indexersMapping[Any, Any], optional

A mapping of dimension names to indexers. Each indexer may be an integer, slice, array-like, or DataArray. Mutually exclusive with indexing via kwargs.

dropbool, default=False

If True, drop any coordinate variables indexed by integers instead of retaining them as length-1 dimensions.

missing_dims{‘raise’, ‘warn’, ‘ignore’}, default=’raise’

Behavior when indexers reference dimensions not present in the array. - ‘raise’: raise an error - ‘warn’: emit a warning and ignore missing dimensions - ‘ignore’: ignore missing dimensions silently

ignore_gridbool, default=False

If False (default), allow slicing on one grid dimension to automatically update the associated UXarray grid. If True, fall back to pure xarray behavior.

inverse_indicesbool, default=False

For grid-based slicing, pass this flag to Grid.isel to invert indices when selecting (useful for staggering or reversing order).

**indexers_kwargsdimension=indexer pairs, optional

Alternative syntax for specifying indexers via keyword arguments.

Returns

UxDataArray

A new UxDataArray indexed according to indexers and updated grid if applicable.

Raises

TypeError

If indexers is provided and is not a Mapping.

ValueError

If more than one grid dimension is selected and ignore_grid=False.

item(*args)

Copy an element of an array to a standard Python scalar and return it.

Parameters

*args : Arguments (variable number and type)

  • none: in this case, the method only works for arrays with one element (a.size == 1), which element is copied into a standard Python scalar object and returned.

  • int_type: this argument is interpreted as a flat index into the array, specifying which element to copy and return.

  • tuple of int_types: functions as does a single int_type argument, except that the argument is interpreted as an nd-index into the array.

Returns

zStandard Python scalar object

A copy of the specified element of the array as a suitable Python scalar

Notes

When the data type of a is longdouble or clongdouble, item() returns a scalar array object because there is no available Python scalar that would not lose information. Void arrays return a buffer object for item(), unless fields are defined, in which case a tuple is returned.

item is very similar to a[args], except, instead of an array scalar, a standard Python scalar is returned. This can be useful for speeding up access to elements of the array and doing arithmetic on elements of the array using Python’s optimized math.

Examples

>>> import numpy as np
>>> np.random.seed(123)
>>> x = np.random.randint(9, size=(3, 3))
>>> x
array([[2, 2, 6],
       [1, 3, 6],
       [1, 0, 1]])
>>> x.item(3)
1
>>> x.item(7)
0
>>> x.item((0, 1))
2
>>> x.item((2, 2))
1

For an array with object dtype, elements are returned as-is.

>>> a = np.array([np.int64(1)], dtype=object)
>>> a.item() #return np.int64
np.int64(1)
searchsorted(v, side='left', sorter=None)

Find indices where elements of v should be inserted in a to maintain order.

For full documentation, see numpy.searchsorted

See Also

numpy.searchsorted : equivalent function

subset

alias of DataArraySubsetAccessor

property sxgrid: Grid
class suxarray.core.SxDataset(*args, sxgrid: Grid = None, source_datasets: str | None = None, **kwargs)[source]

Bases: UxDataset

property sxgrid
suxarray.core.read_schism_nc(grid: Grid, ds_data: Dataset) → SxDataset[source]