riverarchitect.recruitment

Riparian seedling recruitment potential: the Recruitment Box Model.

The open-source replacement for the ArcGIS RiparianRecruitment module. Cottonwood and willow seedlings establish only where four things happen in the right order over a single season, and this maps where all four coincide:

Objective	Question
Bed preparation	did a winter flow mobilise the bed, clearing a seedbed?
Recession rate (desiccation)	did the water table drop slowly enough for roots to follow?
Prolonged inundation	did the seedling stay under water long enough to drown?
Scour	did a later flow uproot it?

Each is scored 1 (good), 0.5 (stressed) or 0 (fatal), and the recruitment potential is their product - a seedling has to survive every one of them, so a zero anywhere is a zero overall. That is the model of Braatne et al. (2007) as the original implemented it.

What it needs

A daily flow record for the season in question, which is the input the other modules do not use: bed preparation, recession and scour are all about when flows happened, not just which flows are possible. Pass it as a two-column table of date and mean daily discharge.

Relation to the original

The original tracked recession and inundation by looping day by day over the flow record and rebuilding an ArcGIS raster per day. The same loop is here, but a day costs one numpy array operation, and the water surface for a day’s discharge is linearly interpolated between the two bracketing modelled discharges rather than re-interpolated from points each time.

class riverarchitect.recruitment.RecruitmentParameters(species='Fremont Cottonwood', seed_start=(5, 2), seed_end=(6, 20), baseflow_start=(9, 15), bed_prep_years=1, tau_cr_full=0.047, tau_cr_partial=0.03, recession_stress=2.5, recession_lethal=5.0, inundation_stress=14, inundation_lethal=28, band_lower=None, band_upper=None)

Bases: object

Species and threshold values for the recruitment model.

Defaults reproduce the Fremont Cottonwood template of the original recruitment_parameters.xlsx. Dates carry a year that is ignored: only month and day matter, and the analysis year is chosen per run.

Parameters:

• seed_start (date) – the seed dispersal window.

• seed_end (date) – the seed dispersal window.

• baseflow_start (date) – when the recession ends and baseflow begins.

• bed_prep_years (int) – how many years back a bed-preparing flow still counts.

• tau_cr_full (float) – dimensionless bed shear stress above which the bed counts as fully or partially mobilised.

• tau_cr_partial (float) – dimensionless bed shear stress above which the bed counts as fully or partially mobilised.

• recession_stress (float) – water table decline in cm/day that stresses or kills a seedling.

• recession_lethal (float) – water table decline in cm/day that stresses or kills a seedling.

• inundation_stress (int) – days of inundation that stress or kill.

• inundation_lethal (int) – days of inundation that stress or kill.

• band_lower (float) – optional elevation band above the baseflow water surface, in cm, to restrict recruitment to.

• band_upper (float) – optional elevation band above the baseflow water surface, in cm, to restrict recruitment to.

classmethod from_workbook(path=None)

Read the parameters from a recruitment_parameters.xlsx.

date_in(year, month_day)

class riverarchitect.recruitment.RecruitmentPotential(condition, flow_series, year=None, parameters=None, unit='us', manning_n=0.0473934, existing_vegetation=None, grading_extent=None)

Bases: object

Recruitment box model for one condition and one season.

Parameters:

• condition (Condition or str) – the condition, or its name.

• flow_series (dict or str) – {date: discharge}, or a path to read one from.

• year (int) – the season to analyse. Defaults to the last year in the record.

• parameters (RecruitmentParameters) – thresholds. Defaults to the template values.

• unit (str) – "us" or "si"; must match the condition’s rasters.

• manning_n (float) – Manning’s n in s/m^(1/3), for the shear stress.

• existing_vegetation (str) – optional raster; cells that already carry vegetation are excluded from the recruitment area.

• grading_extent (str) – optional raster of graded areas, which count as bed-prepared.

Variables:

error (bool) – True when a step could not be completed.

property dem

The DEM, on the reference grid.

wle_at(discharge)

Water surface elevation of a modelled discharge, interpolated across the reach.

wle_for(discharge)

Water surface for any discharge, linearly interpolated between modelled ones.

A daily flow record contains discharges the 2D model never ran. The original interpolated the stage between the bracketing modelled discharges; so does this.

shields_stress(depth, velocity, grain)

Dimensionless bed shear stress, as riverarchitect.lifespan computes it.

q_mobile(tau_cr)

Lowest modelled discharge at which each cell’s bed becomes mobile.

NoData where no modelled discharge mobilises the cell, which reads as “never prepared” downstream.

crop_area()

Where recruitment is possible at all.

Either the elevation band above the baseflow water surface, when the parameters give one, or the area between the lowest and highest wetted extent during seed dispersal - seeds only land where the water reached.

bed_preparation(crop)

Objective 1: did a flow in the bed preparation period mobilise the seedbed?

recession_and_inundation(crop)

Objectives 2 and 3, tracked in a single pass over the flow record.

Both need the same day-by-day walk: the recession rate is how fast the water surface drops at a cell, and the inundation count is how long it stays under water.

Three details decide the result, and all three follow the original (cRecruitmentPotential.rec_inund_survival):

• a stressful or lethal recession day is only counted where the cell is dry that day. While a cell is still submerged its seedling is not desiccating, however fast the surface is dropping;

• a cell that goes dry during seed dispersal starts again from there - that is when its seed actually landed - so both the counts and the denominator are per cell;

• the inundation objective uses the longest run of consecutive submerged days, not their total. Fourteen days under water in one stretch drowns a seedling; fourteen days spread over a season does not.

Returns:

(desiccation, inundation, mortality) rasters, cropped.

Return type:

tuple

scour_survival(crop)

Objective 4: did a flow after seed dispersal uproot the seedling?

run(output_dir=None, write_rasters=True)

Run all four objectives and combine them.

Returns:

the area at each recruitment potential level, the per-objective areas and the paths written.

Return type:

dict

riverarchitect.recruitment.read_flow_series(path, date_column=0, discharge_column=1, sheet=None)

Read a daily flow record from a spreadsheet or CSV.

Parameters:

• path (str) – .xlsx, .xls or .csv with a date column and a mean daily discharge column.

• date_column (int) – zero-based index of the date column.

• discharge_column (int) – zero-based index of the discharge column.

• sheet (str or int) – worksheet, for a workbook with more than one.

Returns:

{datetime.date: discharge}, ascending by date.

Return type:

dict