roms-tools 2.6.0__py3-none-any.whl → 2.6.2__py3-none-any.whl

roms_tools/setup/initial_conditions.py

@@ -21,7 +21,7 @@ from roms_tools.vertical_coordinate import (
     compute_depth_coordinates,
     compute_depth,
 )
-from roms_tools.setup.datasets import GLORYSDataset, CESMBGCDataset
+from roms_tools.setup.datasets import GLORYSDataset, CESMBGCDataset, UnifiedBGCDataset
 from roms_tools.setup.utils import (
     nan_check,
     substitute_nans_by_fillvalue,
@@ -29,6 +29,7 @@ from roms_tools.setup.utils import (
     get_target_coords,
     rotate_velocities,
     compute_barotropic_velocity,
+    compute_missing_bgc_variables,
     _to_yaml,
     _from_yaml,
 )
@@ -122,6 +123,12 @@ class InitialConditions:
 
         if self.bgc_source is not None:
             processed_fields = self._process_data(processed_fields, type="bgc")
+            processed_fields = compute_missing_bgc_variables(processed_fields)
+
+        for var_name in processed_fields:
+            processed_fields[var_name] = transpose_dimensions(
+                processed_fields[var_name]
+            )
 
         d_meta = get_variable_metadata()
         ds = self._write_into_dataset(processed_fields, d_meta)
@@ -158,19 +165,42 @@ class InitialConditions:
         self._set_variable_info(data, type=type)
         attr_name = f"variable_info_{type}"
         variable_info = getattr(self, attr_name)
-        var_names = variable_info.keys()
+
+        # Create the var_names dictionary, associating each variable with its location
+        # Avoid looping over processed_fields.keys() directly, as they may already contain
+        # finalized physics variables. This is especially important when transitioning
+        # to processing biogeochemical (BGC) variables, ensuring that only relevant
+        # variables are processed.
+        var_names = {
+            var: {
+                "name": data.var_names[var],
+                "location": variable_info[var]["location"],
+            }
+            for var in data.var_names.keys()
+            if data.var_names[var] in data.ds.data_vars
+        }
+        # Update the dictionary with optional variables and their locations
+        var_names.update(
+            {
+                var: {
+                    "name": data.opt_var_names[var],
+                    "location": variable_info[var]["location"],
+                }
+                for var in data.opt_var_names.keys()
+                if data.opt_var_names[var] in data.ds.data_vars
+            }
+        )
 
         # lateral regridding
         lateral_regrid = LateralRegridToROMS(target_coords, data.dim_names)
 
         for var_name in var_names:
-            if var_name in data.var_names.keys():
-                processed_fields[var_name] = lateral_regrid.apply(
-                    data.ds[data.var_names[var_name]]
-                )
+            processed_fields[var_name] = lateral_regrid.apply(
+                data.ds[var_names[var_name]["name"]]
+            )
 
         # rotation of velocities and interpolation to u/v points
-        if "u" in variable_info and "v" in variable_info:
+        if "u" in var_names and "v" in var_names:
             processed_fields["u"], processed_fields["v"] = rotate_velocities(
                 processed_fields["u"],
                 processed_fields["v"],
@@ -178,18 +208,9 @@ class InitialConditions:
                 interpolate=True,
             )
 
-        var_names_dict = {
-            location: [
-                name
-                for name, info in variable_info.items()
-                if info["location"] == location and info["is_3d"]
-            ]
-            for location in ["rho", "u", "v"]
-        }
-
         if type == "bgc":
             # Ensure time coordinate matches that of physical variables
-            for var_name in variable_info.keys():
+            for var_name in var_names:
                 processed_fields[var_name] = processed_fields[var_name].assign_coords(
                     {"time": processed_fields["temp"]["time"]}
                 )
@@ -200,17 +221,23 @@ class InitialConditions:
         )
 
         for location in ["rho", "u", "v"]:
-            if len(var_names_dict[location]) > 0:
+            # Filter var_names by location and check for 3D variables
+            filtered_vars = [
+                var_name
+                for var_name, info in var_names.items()
+                if info["location"] == location and variable_info[var_name]["is_3d"]
+            ]
+
+            if filtered_vars:
+                # Handle depth coordinates
                 self._get_depth_coordinates(zeta, location, "layer")
 
-        # Vertical regridding
-        for location in ["rho", "u", "v"]:
-            if len(var_names_dict[location]) > 0:
+                # Vertical regridding
                 vertical_regrid = VerticalRegridToROMS(
                     self.ds_depth_coords[f"layer_depth_{location}"],
                     data.ds[data.dim_names["depth"]],
                 )
-                for var_name in var_names_dict[location]:
+                for var_name in filtered_vars:
                     if var_name in processed_fields:
                         field = processed_fields[var_name]
                         if self.use_dask:
@@ -220,7 +247,7 @@ class InitialConditions:
                         processed_fields[var_name] = vertical_regrid.apply(field)
 
         # Compute barotropic velocities
-        if "u" in variable_info and "v" in variable_info:
+        if "u" in var_names and "v" in var_names:
             for location in ["u", "v"]:
                 self._get_depth_coordinates(zeta, location, "interface")
                 processed_fields[f"{location}bar"] = compute_barotropic_velocity(
@@ -228,11 +255,6 @@ class InitialConditions:
                     self.ds_depth_coords[f"interface_depth_{location}"],
                 )
 
-        for var_name in processed_fields.keys():
-            processed_fields[var_name] = transpose_dimensions(
-                processed_fields[var_name]
-            )
-
         return processed_fields
 
     def _input_checks(self):
@@ -295,9 +317,17 @@ class InitialConditions:
                 climatology=self.bgc_source["climatology"],
                 use_dask=self.use_dask,
             )
+        elif self.bgc_source["name"] == "UNIFIED":
+            data = UnifiedBGCDataset(
+                filename=self.bgc_source["path"],
+                start_time=self.ini_time,
+                climatology=self.bgc_source["climatology"],
+                use_dask=self.use_dask,
+            )
+
         else:
             raise ValueError(
-                'Only "CESM_REGRIDDED" is a valid option for bgc_source["name"].'
+                'Only "CESM_REGRIDDED" and "UNIFIED" are valid options for bgc_source["name"].'
             )
 
         return data
@@ -384,7 +414,10 @@ class InitialConditions:
 
         if type == "bgc":
             variable_info = {}
-            for var_name in data.var_names.keys():
+
+            for var_name in list(data.var_names.keys()) + list(
+                data.opt_var_names.keys()
+            ):
                 if var_name == "ALK":
                     variable_info[var_name] = {**default_info, "validate": True}
                 else:
@@ -453,10 +486,13 @@ class InitialConditions:
         # save in new dataset
         ds = xr.Dataset()
 
-        for var_name in processed_fields.keys():
-            ds[var_name] = processed_fields[var_name].astype(np.float32)
-            ds[var_name].attrs["long_name"] = d_meta[var_name]["long_name"]
-            ds[var_name].attrs["units"] = d_meta[var_name]["units"]
+        for var_name in processed_fields:
+            if var_name in d_meta:
+
+                # drop auxiliary variables
+                ds[var_name] = processed_fields[var_name].astype(np.float32)
+                ds[var_name].attrs["long_name"] = d_meta[var_name]["long_name"]
+                ds[var_name].attrs["units"] = d_meta[var_name]["units"]
 
         # initialize vertical velocity to zero
         ds["w"] = xr.zeros_like(

roms_tools/setup/river_forcing.py

@@ -44,6 +44,7 @@ class RiverForcing:
             - A single string (with or without wildcards).
             - A single Path object.
             - A list of strings or Path objects containing multiple files.
+
           - "climatology" (bool): Indicates if the data is climatology data. Defaults to False.
 
         The default is the Dai and Trenberth global river dataset (updated in May 2019), which does not require a path.
@@ -441,24 +442,25 @@ class RiverForcing:
         return river_indices
 
     def _write_indices_into_dataset(self, ds):
-        """Adds river location indices to the dataset as the "river_location" variable.
+        """Adds river location indices to the dataset as the "river_index" and
+        "river_fraction" variables.
 
-        This method creates a new "river_location" variable
-        using river station indices from `self.indices` and assigns it to the dataset.
-        The indices specify the river station locations in terms of eta_rho and xi_rho grid cell indices.
+        This method creates new "river_index" and "river_fraction" variables using river station indices
+        from `self.indices` and assigns them to the dataset.
 
         Parameters
         ----------
         ds : xarray.Dataset
-            The dataset to which the "river_location" variable will be added.
+            The dataset to which the "river_index" and "river_fraction" variables will be added.
 
         Returns
         -------
         xarray.Dataset
-            The modified dataset with the "river_location" variable added.
+            The modified dataset with the "river_index" and "river_fraction" variables added.
         """
 
-        river_locations = xr.zeros_like(self.grid.ds.h)
+        river_index = xr.zeros_like(self.grid.ds.h)
+        river_fraction = xr.zeros_like(self.grid.ds.h)
 
         for nriver in ds.nriver:
             river_name = str(ds.river_name.sel(nriver=nriver).values)
@@ -467,14 +469,18 @@ class RiverForcing:
 
             for eta_index, xi_index in indices:
 
-                river_locations[eta_index, xi_index] = (
-                    nriver  # assign unique nriver ID (Fortran-based indexing)
-                    + fraction  # Fractional contribution for multiple grid points
-                )
+                # Assign unique nriver ID (Fortran-based indexing)
+                river_index[eta_index, xi_index] = nriver
+                # Fractional contribution for multiple grid points
+                river_fraction[eta_index, xi_index] = fraction
+
+        river_index.attrs["long_name"] = "River ID"
+        river_index.attrs["units"] = "none"
+        ds["river_index"] = river_index
 
-        river_locations.attrs["long_name"] = "River ID plus local volume fraction"
-        river_locations.attrs["units"] = "none"
-        ds["river_location"] = river_locations
+        river_fraction.attrs["long_name"] = "River volume fraction"
+        river_fraction.attrs["units"] = "none"
+        ds["river_fraction"] = river_fraction
 
         ds = ds.drop_vars(["lat_rho", "lon_rho"])
 

roms_tools/setup/surface_forcing.py

@@ -8,13 +8,14 @@ from pathlib import Path
 import logging
 from typing import Dict, Union, List, Optional
 from roms_tools import Grid
-from roms_tools.utils import save_datasets
+from roms_tools.utils import save_datasets, transpose_dimensions
 from roms_tools.regrid import LateralRegridToROMS
 from roms_tools.plot import _plot
 from roms_tools.setup.datasets import (
     ERA5Dataset,
     ERA5Correction,
     CESMBGCSurfaceForcingDataset,
+    UnifiedBGCSurfaceDataset,
 )
 from roms_tools.setup.utils import (
     get_target_coords,
@@ -24,6 +25,7 @@ from roms_tools.setup.utils import (
     get_variable_metadata,
     group_dataset,
     rotate_velocities,
+    compute_missing_surface_bgc_variables,
     convert_to_roms_time,
     _to_yaml,
     _from_yaml,
@@ -160,6 +162,15 @@ class SurfaceForcing:
         if self.type == "physics" and self.correct_radiation:
             processed_fields = self._apply_correction(processed_fields, data)
 
+        if self.type == "bgc":
+            processed_fields = compute_missing_surface_bgc_variables(processed_fields)
+
+        # Reorder dimensions
+        for var_name in processed_fields:
+            processed_fields[var_name] = transpose_dimensions(
+                processed_fields[var_name]
+            )
+
         d_meta = get_variable_metadata()
 
         ds = self._write_into_dataset(processed_fields, data, d_meta)
@@ -265,9 +276,12 @@ class SurfaceForcing:
             if self.source["name"] == "CESM_REGRIDDED":
 
                 data = CESMBGCSurfaceForcingDataset(**data_dict)
+            elif self.source["name"] == "UNIFIED":
+
+                data = UnifiedBGCSurfaceDataset(**data_dict)
             else:
                 raise ValueError(
-                    'Only "CESM_REGRIDDED" is a valid option for source["name"] when type is "bgc".'
+                    'Only "CESM_REGRIDDED" and "UNIFIED" are valid options for source["name"] when type is "bgc".'
                 )
 
         return data
@@ -331,7 +345,9 @@ class SurfaceForcing:
             }
         elif self.type == "bgc":
             variable_info = {}
-            for var_name in data.var_names.keys():
+            for var_name in list(data.var_names.keys()) + list(
+                data.opt_var_names.keys()
+            ):
                 variable_info[var_name] = default_info
                 if var_name == "pco2_air":
                     variable_info[var_name] = {**default_info, "validate": True}

roms_tools/setup/utils.py

@@ -1,6 +1,6 @@
 import xarray as xr
 import numpy as np
-from typing import Union, Any, Dict, Type
+from typing import Union, Any, Dict, Type, Sequence
 import pandas as pd
 import cftime
 from pathlib import Path
@@ -125,41 +125,108 @@ def assign_dates_to_climatology(ds: xr.Dataset, time_dim: str) -> xr.Dataset:
     return ds
 
 
+def interpolate_cyclic_time(
+    data_array: xr.DataArray,
+    time_dim_name: str,
+    day_of_year: Union[
+        int, float, np.ndarray, xr.DataArray, Sequence[Union[int, float]]
+    ],
+) -> xr.DataArray:
+    """Interpolates a DataArray cyclically across the start and end of the year.
+
+    This function extends the data cyclically by appending the last time step
+    (shifted back by one year) at the beginning and the first time step
+    (shifted forward by one year) at the end. It then performs linear interpolation
+    to match the specified `day_of_year` values.
+
+    Parameters
+    ----------
+    data_array : xr.DataArray
+        The input data array containing a time-like dimension.
+    time_dim_name : str
+        The name of the time dimension in the dataset.
+    day_of_year : Union[int, float, np.ndarray, xr.DataArray, Sequence[Union[int, float]]]
+        The target day(s) of the year for interpolation. This can be:
+        - A single integer or float representing the day of the year.
+        - A NumPy array or xarray DataArray containing multiple days.
+        - A list or tuple of integers or floats for multiple target days.
+
+    Returns
+    -------
+    xr.DataArray
+        The interpolated DataArray, ensuring cyclic continuity across year boundaries.
+
+    Notes
+    -----
+    - This function is useful for interpolating climatological data, where the time axis
+      represents a repeating annual cycle.
+    - The `day_of_year` values should be within the range [1, 365] or [1, 366] for leap years.
+    """
+
+    # Concatenate across the beginning and end of the year
+    time_concat = xr.concat(
+        [
+            data_array[time_dim_name][-1] - 365.25,  # Shift last time backward
+            data_array[time_dim_name],
+            data_array[time_dim_name][0] + 365.25,  # Shift first time forward
+        ],
+        dim=time_dim_name,
+    )
+
+    data_array_concat = xr.concat(
+        [
+            data_array.isel(
+                **{time_dim_name: -1}
+            ),  # Append last value at the beginning
+            data_array,
+            data_array.isel(**{time_dim_name: 0}),  # Append first value at the end
+        ],
+        dim=time_dim_name,
+    )
+    data_array_concat[time_dim_name] = time_concat
+
+    # Interpolate to specified times
+    data_array_interpolated = data_array_concat.interp(
+        **{time_dim_name: day_of_year}, method="linear"
+    )
+
+    return data_array_interpolated
+
+
 def interpolate_from_climatology(
     field: Union[xr.DataArray, xr.Dataset],
     time_dim_name: str,
     time: Union[xr.DataArray, pd.DatetimeIndex],
 ) -> Union[xr.DataArray, xr.Dataset]:
-    """Temporally interpolates a field based on specified time points.
+    """Interpolates a climatological field to specified time points.
 
-    This function performs temporal interpolation on the input `field` to match the provided `time` values.
-    If the input `field` is an `xarray.Dataset`, the interpolation is applied to all its data variables individually.
+    This function interpolates the input `field` based on `day_of_year` values
+    extracted from the provided `time` points. If `field` is an `xarray.Dataset`,
+    interpolation is applied to all its data variables individually.
 
     Parameters
     ----------
     field : xarray.DataArray or xarray.Dataset
         The input field to be interpolated.
-        - If `field` is an `xarray.DataArray`, it should have a time dimension identified by `time_dim_name`.
-        - If `field` is an `xarray.Dataset`, all variables within the dataset are interpolated along the specified time dimension.
+        - If `field` is an `xarray.DataArray`, it must have a time dimension identified by `time_dim_name`.
+        - If `field` is an `xarray.Dataset`, all variables within the dataset are interpolated along `time_dim_name`.
         The time dimension is assumed to represent `day_of_year` for climatological purposes.
     time_dim_name : str
-        The name of the time dimension in the `field`. This dimension is used for interpolation.
+        The name of the time dimension in `field`. This dimension is used for interpolation.
     time : xarray.DataArray or pandas.DatetimeIndex
-        The target time points for interpolation. The time values should be compatible with the time format used in the `field`.
+        The target time points for interpolation. These are internally converted to `day_of_year`
+        before performing interpolation.
 
     Returns
     -------
     xarray.DataArray or xarray.Dataset
-        The interpolated field, with the same type as the input (`xarray.DataArray` or `xarray.Dataset`),
+        The interpolated field, maintaining the same type (`xarray.DataArray` or `xarray.Dataset`)
         but aligned to the specified `time` values.
 
     Notes
     -----
-    - The interpolation assumes the time dimension in `field` corresponds to `day_of_year`.
-      If the input time values are in a datetime format, ensure they are converted to `day_of_year` before calling this function.
-      For example, you can preprocess the time as follows:
-
-      >>> field["time"] = field["time"].dt.dayofyear
+    - This function assumes that `field` represents a climatological dataset, where time is expressed as `day_of_year` (1-365).
+    - The `time` input is automatically converted to `day_of_year`, so manual conversion is not required before calling this function.
     """
 
     def interpolate_single_field(data_array: xr.DataArray) -> xr.DataArray:
@@ -170,33 +237,27 @@ def interpolate_from_climatology(
         else:
             if np.size(time) == 1:
                 # Convert single datetime64 object to pandas.Timestamp
-                day_of_year = pd.Timestamp(time).dayofyear
+                date = pd.Timestamp(time)
+                day_of_year = (
+                    date.dayofyear
+                    + (date.hour / 24)
+                    + (date.minute / 1440)
+                    + (date.second / 86400)
+                )
             else:
-                # Convert each datetime64 object in the array to pandas.Timestamp
-                day_of_year = np.array([pd.Timestamp(t).dayofyear for t in time])
-
-        # Concatenate across the beginning and end of the year
-        time_concat = xr.concat(
-            [
-                data_array[time_dim_name][-1] - 365.25,
-                data_array[time_dim_name],
-                365.25 + data_array[time_dim_name][0],
-            ],
-            dim=time_dim_name,
-        )
-        data_array_concat = xr.concat(
-            [
-                data_array.isel(**{time_dim_name: -1}),
-                data_array,
-                data_array.isel(**{time_dim_name: 0}),
-            ],
-            dim=time_dim_name,
-        )
-        data_array_concat[time_dim_name] = time_concat
-
-        # Interpolate to specified times
-        data_array_interpolated = data_array_concat.interp(
-            **{time_dim_name: day_of_year}, method="linear"
+                # Convert each datetime64 object in the array to pandas.Timestamp and compute fractional day of year
+                day_of_year = np.array(
+                    [
+                        pd.Timestamp(t).dayofyear
+                        + (pd.Timestamp(t).hour / 24)
+                        + (pd.Timestamp(t).minute / 1440)
+                        + (pd.Timestamp(t).second / 86400)
+                        for t in time
+                    ]
+                )
+
+        data_array_interpolated = interpolate_cyclic_time(
+            data_array, time_dim_name, day_of_year
         )
 
         if np.size(time) == 1:
@@ -428,6 +489,126 @@ def get_variable_metadata():
     return d
 
 
+def compute_missing_bgc_variables(bgc_data):
+    """Fills in missing biogeochemical (BGC) variables in the input dictionary.
+
+    This function checks for missing BGC variables in the provided dictionary and
+    computes them based on predefined relationships with existing variables. The
+    relationships specify either a multiplication factor applied to an existing
+    variable or a constant value if no related variable is available. The resulting
+    variables are added to the dictionary.
+
+    Parameters
+    ----------
+    bgc_data : dict
+        A dictionary containing biogeochemical variables as xarray DataArrays.
+        Missing variables are computed and added to this dictionary.
+
+        Assumptions:
+        - If `Fe` is part of the input dictionary, it is in units of mmol m-3.
+        - If `CHL` is part of the input dictionary, it is in units of mg m-3.
+        - If `ALK` is part of the input dictionary, it is in units of meq m-3 = mmol m-3.
+        - If `DIC` is part of the input dictionary, it is in units of mmol m-3.
+
+    Returns
+    -------
+    dict
+        The updated dictionary with missing BGC variables filled in.
+
+    Notes
+    -----
+    - If `NH4`, `DOC`, `DON`, `DOP`, `DOCr`, `DONr`, and `DOPr` are not part of the input
+      dictionary, they are filled with constant values.
+    - `CHL` is removed from the dictionary after the necessary calculations.
+    """
+
+    # Define the relationships for missing variables
+    variable_relations = {
+        "NH4": (None, 10**-6),  # mmol m-3
+        "Lig": ("Fe", 3),  # mmol m-3
+        "DIC_ALT_CO2": ("DIC", 1),  # mmol m-3
+        "ALK_ALT_CO2": ("ALK", 1),  # meq m-3 = mmol m-3
+        "DOC": (None, 10**-6),  # mmol m-3
+        "DON": (None, 1.0),  # mmol m-3
+        "DOP": (None, 0.1),  # mmol m-3
+        "DOCr": (None, 10**-6),  # mmol m-3
+        "DONr": (None, 0.8),  # mmol m-3
+        "DOPr": (None, 0.003),  # mmol m-3
+        "zooC": ("CHL", 1.35),  # mmol m-3
+        "spChl": ("CHL", 0.675),  # mg m-3
+        "spC": ("CHL", 3.375),  # mmol m-3
+        "spP": ("CHL", 0.03),  # mmol m-3
+        "spFe": ("CHL", 1.35e-5),  # mmol m-3
+        "spCaCO3": ("CHL", 0.0675),  # mmol m-3
+        "diatChl": ("CHL", 0.0675),  # mg m-3
+        "diatC": ("CHL", 0.2025),  # mmol m-3
+        "diatP": ("CHL", 0.02),  # mmol m-3
+        "diatFe": ("CHL", 1.35e-6),  # mmol m-3
+        "diatSi": ("CHL", 0.0675),  # mmol m-3
+        "diazChl": ("CHL", 0.0075),  # mg m-3
+        "diazC": ("CHL", 0.0375),  # mmol m-3
+        "diazP": ("CHL", 0.01),  # mmol m-3
+        "diazFe": ("CHL", 7.5e-7),  # mmol m-3
+    }
+
+    # Fill in missing variables using the defined relationships
+    for var_name, (base_var, factor) in variable_relations.items():
+        if var_name not in bgc_data:
+            if base_var:
+                bgc_data[var_name] = bgc_data[base_var] * factor
+            else:
+                bgc_data[var_name] = factor * xr.ones_like(bgc_data["ALK"])
+
+    bgc_data.pop("CHL", None)
+
+    return bgc_data
+
+
+def compute_missing_surface_bgc_variables(bgc_data):
+    """Fills in missing surface biogeochemical (BGC) variables in the input dictionary.
+
+    This function checks for missing surface BGC variables in the provided dictionary and
+    computes them based on predefined relationships with existing variables. The relationships
+    specify either a multiplication factor applied to an existing variable or a constant value
+    if no related variable is available. The resulting variables are added to the dictionary.
+
+    Parameters
+    ----------
+    bgc_data : dict
+        A dictionary containing surface biogeochemical variables as xarray DataArrays.
+        Missing variables are computed and added to this dictionary.
+
+        Assumptions:
+        - If `pco2_air` is part of the input dictionary, it is in units of ppmv.
+
+    Returns
+    -------
+    dict
+        The updated dictionary with missing surface BGC variables filled in.
+
+    Notes
+    -----
+    - If `nox` and `nhy` are not part of the input dictionary, the are assigned constant values.
+    """
+
+    # Define the relationships for missing variables
+    variable_relations = {
+        "pco2_air_alt": ("pco2_air", 1.0),
+        "nox": (None, 1e-13),  # has incorrect unit nmol/cm2/s, we need kg/m2/s
+        "nhy": (None, 5e-12),  # has incorrect unit nmol/cm2/s, we need kg/m2/s
+    }
+
+    # Fill in missing variables using the defined relationships
+    for var_name, (base_var, factor) in variable_relations.items():
+        if var_name not in bgc_data:
+            if base_var:
+                bgc_data[var_name] = bgc_data[base_var] * factor
+            else:
+                bgc_data[var_name] = factor * xr.ones_like(bgc_data["pco2_air"])
+
+    return bgc_data
+
+
 def extract_single_value(data):
     """Extracts a single value from an xarray.DataArray or numpy array.