The head observations module

Functions for processing head observations

mfobs.heads.get_head_obs(perioddata, modelgrid_transform, model_output_file, observed_values_file, gwf_obs_input_file, observed_values_metadata_file=None, variable_name='head', observed_values_site_id_col='obsprefix', observed_values_datetime_col='datetime', obsnme_date_suffix=True, obsnme_suffix_format='%Y%m', observed_values_obsval_col='obsval', observed_values_x_col='x', observed_values_y_col='y', observed_values_screen_top_col='screen_top', observed_values_screen_botm_col='screen_botm', observed_values_layer_col=None, observed_values_group_column='obgnme', observed_values_unc_column='uncertainty', aggregrate_observed_values_by='mean', gwf_obs_block=None, drop_groups=None, hk_arrays=None, top_array=None, botm_arrays=None, label_period_as_steady_state=None, steady_state_period_start=None, steady_state_period_end=None, forecast_sites=None, forecast_start_date=None, forecast_end_date=None, forecasts_only=False, forecast_sites_only=False, min_open_interval_frac_in_model=0.5, verbose=True, write_ins=False, outfile=None)

Post-processes model output to be read by PEST, and optionally, writes a corresponding PEST instruction file. Reads model output using get_mf6_single_variable_obs(). General paradigm is to include all model layers in the MODFLOW input for each observation, and then post-process the model results to a single value by computing a transmissivity-weighted average.

Observation names to match observed values to their simulated equivalents are constructed in the format of <obsprefix>_<date suffix>, where obsprefix is a site identifier taken from the observed_values_site_id_col in observed_values_file. In creating observation names for MODFLOW output, the column names in the observation CSV output are used for the prefixes. Therefore, the identifiers in observed_values_site_id_col should correspond to observations in the MODFLOW observation input. The date suffix is formatted using the obsnme_date_suffix_format parameter, which is also passed to get_mf6_single_variable_obs() for assigning observation names to the MODFLOW observation output.

Optionally, a model stress period can be labeled as steady-state (label_period_as_steady_state), representing average conditions over a time period bracked by a steady_state_period_start and steady_state_period_end. In this case, the simulated values for the labeled stress period are matched to average values for the steady-state time period.

Parameters:

perioddatastr

Path to csv file with start/end dates for stress periods. Must have columns ‘time’ (modflow time, in days), ‘start_datetime’ (start date for the stress period) and ‘end_datetime’ (end date for the stress period).

modelgrid_transformstr

An affine.Affine object describing the orientation of the model grid. Modflow-setup MFsetupGrid have this attached via the transform() property. Example:

modelgrid_transform=affine.Affine(1000.0, 0.0, 500955,
                                  0.0, -1000.0, 1205285)

for a uniform spacing of 1000 and upper left corner of 500955, 1205285 with a rotation of 45 degrees, counter-clockwise about the upper left corner:

modelgrid_transform=affine.Affine(1000.0, 0.0, 500955,
                                  0.0, -1000.0, 1205285).rotation(45.)

An affine.Affine instance can also be created from a Modflow-setup grid JSON file via the get_modelgrid_transform() function.

model_output_filestr

Modflow-6 head observation CSV output file. Read by get_mf6_single_variable_obs().

observed_values_filestr or DataFrame

CSV file or DataFrame with observed values. Must have the following columns (default names are shown, other names can be specified with observed_values_**_col variables below):

site_id	site identifier
datetime	date/time of observation
obsval	observed value

can optionally include these columns, or this information can be supplied in an observed_values_metadata_file, which will be joined on site_id

x	x location
y	y location
screen_top	screen top elevation
screen_botm	screen bottom elevation

If supplied, observation group and uncertainty information will be passed through to the output base_data DataFrame:

obgnme	observation group
uncertainty	estimated measurement uncertainty

Locations and screen tops and bottoms are assumed to be in the same CRS and length units as the model.

observed_values_metadata_filestr, optional

Site information for the observed values timeseries. Should include a site_id column that is the same as observed_values_site_id_col, and any of the following columns that are not in the observed_values_file:

x	x location
y	y location
screen_top	screen top elevation
screen_botm	screen bottom elevation

gwf_obs_input_filestr

Input file to MODFLOW-6 observation utility (contains layer information).

variable_namestr, optional

Column with simulated output will be named “sim_<variable_name”, by default ‘head’

observed_values_site_id_colstr, optional

Column name in observed_values_file with site identifiers, by default ‘obsprefix’

observed_values_datetime_colstr, optional

Column name in observed_values_file with observation date/times, by default ‘datetime’

obsnme_date_suffixbool

If true, give observations a date-based suffix. Otherwise, assign a stress period-based suffix. In either case, the format of the suffix is controlled by obsnme_suffix_format. by default True

obsnme_suffix_formatstr, optional

Format for suffix of obsnmes. Observation names are created following the format of <obsprefix>_<date or stress period suffix>. By default, '%Y%m', which would yield '202001' for a Jan, 2020 observation (obsnme_date_suffix=True). If obsnme_date_suffix=False, obsnme_suffix_format should be a decimal format in the “new-style” string format (e.g. ‘{:03d}’, which would yield '001' for stress period 1.)

observed_values_obsval_colstr, optional

Column name in observed_values_file with observed values, by default ‘obsval’

observed_values_x_colstr, optional

Column name in observed_values_file with x-coordinates, by default ‘x’

observed_values_y_colstr, optional

Column name in observed_values_file with y-coordinates, by default ‘y’

observed_values_screen_top_colstr, optional

Column name in observed_values_file with screen top elevations, by default ‘screen_top’

observed_values_screen_botm_colstr, optional

Column name in observed_values_file with screen bottom elevations, by default ‘screen_botm’

observed_values_layer_colstr, optional

As an alternative to providing screen tops and bottoms, the model layer for each observation can be specified directly via a layer column of zero-based layer numbers. by default None

observed_values_group_columnstr, optional

Column name in observed_values_file with observation group information. Passed through to output base_data DataFrame, otherwise not required. by default ‘obgnme’

observed_values_unc_columnstr, optional

Column name in observed_values_file with observation uncertainty values. Passed through to output base_data DataFrame, otherwise not required. by default ‘uncertainty’

aggregrate_observed_values_bystr

Method for aggregating observed values to the model stress periods, if there are multiple observed values in a stress period. Can be any of the method calls on the pandas Resampler object. By default, ‘mean’

gwf_obs_blockNone or int

Argument to read a specific observation block or all blocks from GWF observation utility file. Value of None returns observations from all blocks. Integer value returns obs from a specifc block, in (zero-based) order, from top to bottom. For example, a value of 0 would return the first obs block, value of 1 would return the second obs block, and so on. Modflow-setup writes all of the observation input to a single block, but observation input can be broken out into multiple blocks (one per file). by default, None (All blocks)

drop_groupssequence, optional

Observation groups to exclude from output, by default None

hk_arrayslist-like of pathlikes or ndarray, optional

File paths to text arrays with hydraulic conductivity values (ordered by model layer). Used in the transmissivity-weighted averaging. by default None

top_arraystr, pathlike or ndarray, optional

File paths to text array with model top elevations. Used in the transmissivity-weighted averaging. by default None

botm_arraysstr, pathlike or ndarray, optional

File paths to text arrays with model cell bottom elevations. (ordered by model layer). Used in the transmissivity-weighted averaging. by default None

label_period_as_steady_stateint, optional

Zero-based model stress period where observations will be assigned the suffix ‘ss’ instead of a date suffix. By default, None, in which case all model output is assigned a date suffix based on the start date of the stress period. Passed to get_mf6_single_variable_obs().

steady_state_period_startstr, optional

Start date for the period representing steady-state conditions. Observations between steady_state_period_start and steady_state_period_end will be averaged to create additional observations with the suffix ‘ss’. The steady-state averages will be matched to model output from the stress period specified by label_period_as_steady_state. By default None, in which case all observations are used (if observed_values_datetime_col is None) or no steady-state observations are created (observed_values_datetime_col exists).

steady_state_period_endstr, optional

End date for the period representing steady-state conditions. By default None, in which case all observations are used (if observed_values_datetime_col is None) or no steady-state observations are created (observed_values_datetime_col exists).

forecast_sitesstr or sequence, optional

At these sites, observations will be created for each simulated value, regardless is there is an observed equivalent. Can be supplied as a sequence of site numbers (site_id`s) or `’all’`` to include all sites. By default, None (no forecast sites).

forecast_start_datestr, optional

Start date for forecast period. When forecast_sites is not None, forecast observations will be generated for each time between forecast_start_date and forecast_end_date. By default, None (generate forecasts for any time with missing values).

forecast_end_datestr, optional

End date for forecast period. When forecast_sites is not None, forecast observations will be generated for each time between forecast_start_date and forecast_end_date. By default, None (generate forecasts for any time with missing values).

forecasts_onlybool, optional

Use this option to only output forecast observations (those without an observed equivalent), subject to the parameters of forecast_sites, forecast_start_date, and forecast_end_date.

forecast_sites_onlybool, optional

Option to only output observations at sites specified with forecast_sites (has no effect if forecast_sites='all'). If forecasts_only=False, the output will include forecast and non-forecast observations (for a continuous time-series).

min_open_interval_frac_in_modelfloat ranging from 0 to 1, optional

Option to cull observations with less than min_open_interval_frac_in_model fraction of their open interval within the model domain. Dropped head observation locations will be reported in dropped_head_observations_above_or_below_model.csv. by default, 0.5 (only retain observations with 50% or more of their open interval within the model domain)

verbosebool

Controls the verbosity of screen outputs. If True, warnings will be printed when there are no observations within a stress period and forecast_sites is None (meaning no observation results will be processed for that stress period). by default, True

outfilestr, optional

CSV file to write output to. By default, None (no output written)

write_insbool, optional

Option to write instruction file, by default False

Returns:

base_dataDataFrame

With the following columns:

datetime	pandas datetimes for the start of each stress period
per	model stress period
obsprefix	observation site identifier
obsnme	observation name based on format of <obsprefix>_’%Y%m’
obs_<variable_name>	observed values
sim_<variable_name>	simulated observation equivalents
screen_top	screen top elevation
screen_botm	screen bottom elevation

Example observation names:

site1000_202001, for a Jan. 2020 observation at site1000 (obsnme_date_suffix=True)

site1000_001, for a stress period 1 observation at site1000 (obsnme_date_suffix=False)

a steady-state stress period specified with label_period_as_steady_state is given the suffix of ‘ss’ e.g. site1000_ss

Notes

All observation names and observation prefixes are converted to lower case to avoid potential case issues.