pygypsy package

Submodules

pygypsy.GYPSYNonSpatial module

pygypsy.asaCompileAgeGivenSpSiHt module

pygypsy.asaCompileAgeGivenSpSiHt.ComputeGypsySiteIndex(species='Aw', totalHeight=1.3, bhage=0, totalAge=0)[source]

Total age is unknown Breast height age is known Total height is known

Equations and logic derived from: Huang, S., Meng, S.X., and Yang, Y. 2009. A growth and yield projection system (GYPSY) for natural and post-harvest stands in Alberta. Technical Report Pb. No.:T/216. Forest Management Branch, Alberta Sustainable Resource Development, Edmonton, AB, CAN. Appendix I. Pp. 21,22.

Error in white spruce equation discovered Dec 5 2014

pygypsy.asaCompileAgeGivenSpSiHt.ComputeGypsyTreeHeightGivenSiteIndexAndTotalAge(species='Aw', siteIndex=1.3, totalAge=0)[source]

Equations and logic derived from: Huang, S., Meng, S.X., and Yang, Y. 2009. A growth and yield projection system (GYPSY) for natural and post-harvest stands in Alberta. Technical Report Pb. No.:T/216. Forest Management Branch, Alberta Sustainable Resource Development, Edmonton, AB, CAN. Appendix I. Pp. 21,22.

Error in white spruce equation discovered Dec 5 2014

pygypsy.asaCompileAgeGivenSpSiHt.computeGypsyY2BHGivenSpSI(species='Aw', si0=5)[source]

Compute years to breast height given species and site index

Huang, S., Meng, S.X., and Yang, Y. 2009. A growth and yield projection system (GYPSY) for natural and post-harvest stands in Alberta. Technical Report Pb. No.:T/216. Forest Management Branch, Alberta Sustainable Resource Development, Edmonton, AB, CAN. Appendix I. Pp. 21,22.

pygypsy.asaCompileAgeGivenSpSiHt.computeTreeAge(siSp='', treeHt=20, treeSi=15, maxTreeAge=450, rowIndex=0)[source]

pygypsy.basal_area_factor module

Basal Area correction factor estimators

pygypsy.basal_area_factor.estimate_basal_area_factor_aw(**kwargs)[source]

This function guarantees that the trajectory of the species basal area passes through the basal area measured when the data was collected (inventory data)

There is a trade-off between the precision one wants this estimate, which is given by the parameter - acceptableDiff -, and the time the convergence time

Parameters:
  • startTage (float) – Clock that uses the oldest species as a reference to become the stand age
  • SI_bh_Aw (float) – site index of species Aw
  • N_bh_AwT (float) – density of sp Aw at time T (it varies over time)
  • BA_Aw0 (float) – basal area of Aw at breast height age, assumed to be very small
  • BA_AwT (float) – basal area of Aw at time T
  • SDF_Aw0 (float) – Stand Density Factor of species Aw
  • N0_Aw (float) – initial density of species Aw at breast height age
  • densities (list) – array of ‘densities’ objects
pygypsy.basal_area_factor.estimate_basal_area_factor_pl(**kwargs)[source]

Lodgepole pine basal area factor estimator

This function guarantees that the trajectory of the species basal area passes through the basal area measured when the data was collected (inventory data)

Parameters:
  • startTage (float) – Clock that uses the oldest species as a reference to become the stand age
  • SI_bh_Pl (float) – site index of species Pl
  • N_bh_PlT (float) – density of sp Pl at time T (it varies over time)
  • BA_Pl0 (float) – basal area of Pl at breast height age, assumed to be very small
  • BA_PlT (float) – basal area of Pl at time T
  • N0_Pl (float) – initial density of species Pl at breast height age
  • y2bh_Pl (float) – time elapseed in years from zero to breast height age of sp Pl
  • startTagePl (float) – species specific ages counted independently
  • SC_Pl (float) – proportion of species Pl in the stand
  • SDF_Sw0 (float) – Stand Density Factor of species Sw
  • SDF_Aw0 (float) – Stand Density Factor of species Aw
  • SDF_Sb0 (float) – Stand Density Factor of species Sb
  • densities (list) – array of ‘densities’ objects
pygypsy.basal_area_factor.estimate_basal_area_factor_sb(**kwargs)[source]

Black spruce basal area factor estimator

This function guarantees that the trajectory of the species basal area passes through the basal area measured when the data was collected (inventory data)

Parameters:
  • startTage (float) – Clock that uses the oldest species as a reference to become the stand age
  • SI_bh_Sb (float) – site index of species Sb
  • N_bh_SbT (float) – density of sp Sb at time T (it varies over time)
  • BA_Sb0 (float) – basal area of Sb at breast height age, assumed to be very small
  • BA_SbT (float) – basal area of Sb at time T
  • N0_Sb (float) – initial density of species Sb at breast height age
  • y2bh_Sb (float) – time elapseed in years from zero to breast height age of sp Sb
  • startTageSb (float) – species specific ages counted independently
  • SC_Sb (float) – proportion of species Sb in the stand
  • densities (list) – array of ‘densities’ objects
pygypsy.basal_area_factor.estimate_basal_area_factor_sw(**kwargs)[source]

White Spruce basal area factor estimator

This function guarantees that the trajectory of the species basal area passes through the basal area measured when the data was collected (inventory data)

Parameters:
  • startTage (float) – Clock that uses the oldest species as a reference to become the stand age
  • SI_bh_Sw (float) – site index of species Sw
  • N_bh_SwT (float) – density of sp Sw at time T (it varies over time)
  • BA_Sw0 (float) – basal area of Sw at breast height age, assumed to be very small
  • BA_SwT (float) – basal area of Sw at time T
  • N0_Sw (float) – initial density of species Sw at breast height age
  • y2bh_Sw (float) – time elapseed in years from zero to breast height age of sp Sw
  • startTageSw (float) – species specific ages counted independently
  • SC_Sw (float) – proportion of species Sw in the stand
  • SDF_Pl0 (float) – Stand Density Factor of species Pl
  • SDF_Aw0 (float) – Stand Density Factor of species Aw
  • SDF_Sb0 (float) – Stand Density Factor of species Sb
  • densities (list) – array of ‘densities’ objects
pygypsy.basal_area_factor.get_basal_area_factors_for_all_species(**kwargs)[source]

pygypsy.basal_area_increment module

Increment functions

This module contains functions to increment plot characteristics at an annual resolution.

It uses the non-spatial implementaion.

pygypsy.basal_area_increment.increment_basal_area_aw()

Predicts the increment in basal area for the subsequent year for the species.

This function is also used to make basal area projections and as a function called by factor finder functions during estimation of correction factor for the species.

Parameters:
  • SI_bh (float) – site index of species Aw
  • bhage (float) – breast height age of speceis Aw
  • N_bh (float) – density of species Aw
  • SC (float) – proportion of species Aw in the stand
  • BA (float) – Basal area of the species Aw
  • N0 (float) – initial density of species Aw at breast height age
pygypsy.basal_area_increment.increment_basal_area_pl()

Predicts the increment in basal area for the subsequent year for the species.

This function is used to make basal area projections and as a function called by factor finder functions during estimation of correction factor for the species.

Parameters:
  • SC (float) – proportion of species Pl in the stand
  • SI_bh (float) – site index of species Pl
  • bhage (float) – breast height age of species Pl
  • N_bh (float) – density of species Pl
  • BA (float) – Basal area of the species Pl
  • N0 (float) – initial density of species Pl at total age
  • SDFSw0 (float) – Stand Density Factor of species Sw
  • SDF_Aw0 (float) – Stand Density Factor of species Aw
  • SDF_Sb0 (float) – Stand Density Factor of species Sb
pygypsy.basal_area_increment.increment_basal_area_sb()

Predicts the increment in basal area for the subsequent year for the species.

This function is used to make basal area projections and as a function called by factor finder functions during estimation of correction factor for the species.

Parameters:
  • SI_bh (float) – site index of species Sb
  • bhage (float) – breast height age of speceis Sb
  • N_bh (float) – density of species Sb
  • SC (float) – proportion of species Sb in the stand
  • BA (float) – Basal area of the species Sb
  • N0 (float) – initial density of species Sb at total age
pygypsy.basal_area_increment.increment_basal_area_sw()

Predicts the increment in basal area for the subsequent year for the species.

This function is used to make basal area projections and as a function called by factor finder functions during estimation of correction factor for the species.

Parameters:
  • SI_bh (float) – site index of species Sw
  • bhage (float) – breast height age of speceis Sw
  • N_bh (float) – density of species Sw
  • SC (float) – proportion of species Sw in the stand
  • BA (float) – Basal area of the species Sw
  • N0 (float) – initial density of species Sw at total age
  • SDF_Pl0 (float) – Stand Density Factor of species Pl
  • SDF_Aw0 (float) – Stand Density Factor of species Aw
  • SDF_Sb0 (float) – Stand Density Factor of species Sb

pygypsy.basal_area_simulate module

Basal Area Simulation

pygypsy.basal_area_simulate.sim_basal_area_aw(initial_age, site_index, density_at_bh_age, basal_area_at_bh_age, sdf_aw, correction_factor, densities, use_correction_factor_future=False, stop_at_initial_age=True, fix_proportion_and_density_to_initial_age=False, species_proportion_at_bh_age=None, present_density=None, force_use_densities=False)[source]

Simlulate basal area forward in time for White Aspen

It creates the trajectory of basal area from bhage up to the inventory year given a correction factor that is being optimized

Parameters:
  • initial_age (float) – Clock that uses the oldest species as a reference to become the stand age
  • site_index (float) – site index of species Aw
  • basal_area_at_bh_age (float) – basal area of Aw at breast height age
  • SDF_Aw0 (float) – Stand Density Factor of species Aw
  • density_at_bh_age (float) – initial density of species Aw at breast height age
  • correction_factor (float) – correction factor that guarantees that trajectory passes through data obtained with inventory
  • use_correction_factor_future (bool) – switch that determine whether the correction factor will be used for the future years
  • stop_at_initial_age (bool) – switch that determines whether simulation will stop at the date of the inventory or will continue for the length of the densities object
  • fix_proportion_and_density_to_initial_age (bool) – if true, uses the

proportion and density from the initial age for all years of the simulation. this is provided for consistency with a previous version which did this implicityly in for estiamting the basal area factors :param bool force_use_densities: ignore other parameters and just use them densities object for calculating basal

area increment
pygypsy.basal_area_simulate.sim_basal_area_pl(initial_age, site_index, density_at_bh_age, sdf_aw, sdf_sw, sdf_sb, basal_area_at_bh_age, correction_factor, densities, use_correction_factor_future=False, stop_at_initial_age=True, fix_proportion_and_density_to_initial_age=False, species_proportion_at_bh_age=None, present_density=None, force_use_densities=False)[source]

Simlulate basal area forward in time for Lodgepole Pine

Parameters:
  • initial_age (float) – Clock that uses the oldest species as a reference to become the stand age
  • site_index (float) – site index of species Pl
  • basal_area_at_bh_age (float) – basal area of Pl at breast height age
  • density_at_bh_age (float) – initial density of species Pl at breast height age
  • sdf_sw (float) – Stand Density Factor of species Sw
  • sdf_aw (float) – Stand Density Factor of species Aw
  • sdf_sb (float) – Stand Density Factor of species Sb
  • correction_factor (float) – correction factor that guarantees that trajectory passes through data obtained with inventory
  • use_correction_factor_future (bool) – switch that determine whether the correction factor will be used for the future years
  • stop_at_initial_age (bool) – switch that determines whether simulation will stop at the date of the inventory or will continue for the length of the densities object
  • fix_proportion_and_density_to_initial_age (bool) – if true, uses the

proportion and density from the initial age for all years of the simulation. this is provided for consistency with a previous version which did this implicityly in for estiamting the basal area factors :param bool force_use_densities: ignore other parameters and just use them densities object for calculating basal

area increment
pygypsy.basal_area_simulate.sim_basal_area_sb(initial_age, site_index, density_at_bh_age, basal_area_at_bh_age, correction_factor, densities, use_correction_factor_future=False, stop_at_initial_age=True, fix_proportion_and_density_to_initial_age=False, species_proportion_at_bh_age=None, present_density=None, force_use_densities=False)[source]

Simlulate basal area forward in time for Black Spruce

It creates the trajectory of basal area from bhage up to the inventory year given a correction factor that is being optimized

Parameters:
  • initial_age (float) – Clock that uses the oldest species as a reference to become the stand age
  • initial_age_sb (float) – species specific age counted independently
  • site_index (float) – site index of species Sb
  • basal_area_at_bh_age (float) – basal area of Sb at breast height age
  • density_at_bh_age (float) – initial density of species Sb at breast height age
  • correction_factor (float) – correction factor that guarantees that trajectory passes through data obtained with inventory
  • use_correction_factor_future (bool) – switch that determine whether the correction factor will be used for the future years
  • stop_at_initial_age (bool) – switch that determines whether simulation will stop at the date of the inventory or will continue for the length of the densities object
  • fix_proportion_and_density_to_initial_age (bool) – if true, uses the

proportion and density from the initial age for all years of the simulation. this is provided for consistency with a previous version which did this implicityly in for estiamting the basal area factors :param bool force_use_densities: ignore other parameters and just use them densities object for calculating basal

area increment
pygypsy.basal_area_simulate.sim_basal_area_sw(initial_age, site_index, density_at_bh_age, sdf_aw, sdf_pl, sdf_sb, basal_area_at_bh_age, correction_factor, densities, use_correction_factor_future=False, stop_at_initial_age=True, fix_proportion_and_density_to_initial_age=False, species_proportion_at_bh_age=None, present_density=None, force_use_densities=False)[source]

Simlulate basal area forward in time for White Spruce It created the trajectory of basal area from bhage up to the inventory year given a correction factor that is being optimized

Parameters:
  • initial_age (float) – Clock that uses the oldest species as a reference to become the stand age
  • site_index (float) – site index of species Sw
  • basal_area_at_bh_age (float) – basal area of Sw at breast height age
  • density_at_bh_age (float) – initial density of species Sw at breast height age
  • sdf_pl (float) – Stand Density Factor of species Pl
  • sdf_aw (float) – Stand Density Factor of species Aw
  • sdf_sb (float) – Stand Density Factor of species Sb
  • correction_factor (float) – correction factor that guarantees that trajectory passes through data obtained with inventory
  • use_correction_factor_future (bool) – switch that determine whether the correction factor will be used for the future years
  • stop_at_initial_age (bool) – switch that determines whether simulation will stop at the date of the inventory or will continue for the length of the densities object
  • fix_proportion_and_density_to_initial_age (bool) – if true, uses the

proportion and density from the initial age for all years of the simulation. this is provided for consistency with a previous version which did this implicityly in for estiamting the basal area factors :param bool force_use_densities: ignore other parameters and just use them densities object for calculating basal

area increment

pygypsy.data_prep module

Data Preparation

Calculates and joins parameters required for pygypsy to a plot table

pygypsy.data_prep.populate_species_dict(partial_species_list, sorted_species_abbrev_perc_tuples_list, dominant_species=None, row=None, dominant_species_current_age=None, dominant_species_current_height=None)[source]

Fill partial fplot

Given fplot with proportion filled out, add age, top height, basal area, density

Parameters:
  • partial_species_list –
  • sorted_species_abbrev_perc_tuples_list –
  • dominant_species –
  • dominant_species_current_age –
  • dominant_species_current_height –
pygypsy.data_prep.prep_standtable(data, **kwargs)[source]

Define site_index of all other species given the dominant species

The site index is only defined for the dominant species in a plot. This function uses the dominant species and its site index to estimate the site indices for other species. It estimates other values and returns a data frame of all of the values for all plots input.

estimates site_index Dom from inventory Age and HD this site_index is used to estimate the site index of the other species for example: - FD is dom species take HD and Age - assume FD is Sw generate site_index for Sw - get the SW site_index - calculate the SIs for other species from the conversion formulas

Parameters:
  • data – input data frame
  • kwargs – additional arguments to _prep_row()

pygypsy.density module

Density estimators

pygypsy.density.estimate_density_aw(SDF_Aw0, bhage_Aw, SI_bh_Aw, ret_detail=False)[source]

Main purpose of this function is to project densities forward and backward in time for the species

Parameters:
  • SI_bh_Aw (float) – site index of species Aw
  • bhage_Aw (float) – breast height age of species Aw
  • SDF_Aw0 (float) – Stand Density Factor of species Aw
  • ret_detail (bool) – whether additional values should be returned - used

by other functions to iteratively solve this function for SDF

pygypsy.density.estimate_density_pl(SDF_Aw0, SDF_Sw0, SDF_Sb0, SDF_Pl0, tage_Pl, SI_bh_Pl, ret_detail=False)[source]

Main purpose of this function is to project densities forward and backward in time for the species

Parameters:
  • SI_bh_Pl (float) – site index of species Pl
  • tage_Pl (float) – total age of species Pl
  • SDF_Pl0 (float) – Stand Density Factor of species Pl
  • SDF_Aw0 (float) – Stand Density Factor of species Aw
  • SDF_Sb0 (float) – Stand Density Factor of species Sb
  • SDF_Sw0 (float) – Stand Density Factor of species Sw
  • ret_detail (bool) – whether additional values should be returned - used

by other functions to iteratively solve this function for SDF

pygypsy.density.estimate_density_sb(SDF_Sb0, tage_Sb, SI_bh_Sb, ret_detail=False)[source]

Main purpose of this function is to project densities forward and backward in time for the species

Parameters:
  • SI_bh_Sb (float) – site index of species Sb
  • tage_Sb (float) – total age of species Sb
  • SDF_Sb0 (float) – Stand Density Factor of species Sb
  • SDF_Aw0 (float) – Stand Density Factor of species Aw
  • ret_detail (bool) – whether additional values should be returned - used

by other functions to iteratively solve this function for SDF

pygypsy.density.estimate_density_sw(SDF_Sw0, SDF_Aw0, tage_Sw, SI_bh_Sw, ret_detail=False)[source]

Main purpose of this function is to project densities forward and backward in time for the species

Parameters:
  • SI_bh_Sw (float) – site index of species Sw
  • tage_Sw (float) – total age of species Sw
  • SDF_Sw0 (float) – Stand Density Factor of species Sw
  • SDF_Aw0 (float) – Stand Density Factor of species Aw
  • ret_detail (bool) – whether additional values should be returned - used

by other functions to iteratively solve this function for SDF

pygypsy.forward_simulation module

Simulation

pygypsy.forward_simulation.simulate_densities_speciescomp_topheight(n_years=250, start_at_data_year=False, **kwargs)[source]

Estimate, species composition, top height for all species along time

Time is counted independently for each species.

Parameters:
  • duration (in) –
  • startTage (float) – It uses the oldest species as a reference to become the stand age
  • startTageAw, startTageSw, startTageSb, and startTagePl (float) – age for respective species
  • SDF_Pl0 (float) – Stand Density Factor of species Pl
  • SDF_Aw0 (float) – Stand Density Factor of species Aw
  • SDF_Sb0 (float) – Stand Density Factor of species Sb
  • SDF_Sw0 (float) – Stand Density Factor of species Sw
  • SI_bh_Sw (float) – site index of species Sw
  • SI_bh_Aw (float) – site index of species Aw
  • SI_bh_Sb (float) – site index of species Sb
  • SI_bh_Pl (float) – site index of species Pl
  • y2bh_Aw (float) – time elapseed in years from zero to breast height age of sp Aw
  • y2bh_Sw (float) – time elapseed in years from zero to breast height age of sp Sw
  • y2bh_Sb (float) – time elapseed in years from zero to breast height age of sp Sb
  • y2bh_Pl (float) – time elapseed in years from zero to breast height age of sp Pl
pygypsy.forward_simulation.simulate_forwards_df(plot_df, **kwargs)[source]

Simulate the evolution of plot characteristics through time

This begins with the simulation of densities, species, and top height.

With the time series of those items in hand, the simulation from time zero (primary succession) to the time of observation can be skipped. If it is not skipped, an optimization routine is used to find factors for each species. The factors are multiplied with a parameter of the basal area increment to ensure that the simulation time timer zero to the time of observation passes through a basal area of 0 and the observed basal area. Between time zero and the time of observation, fixed values may optionally be used for density, species compositon. This optimization is expensive.

Once the simulation reaches the year of observation, the simulated densities, species composition, and top heights are used in the increment functions, instead of using fixed values.

Parameters:
  • plot_df – pandas.DataFrame with plot data
  • kwargs – keyword arguments to func:_simulate_row
Returns:

multi-index data frame with plot id and year as index and values

of the simulated plot characteristics

Warning

the backwards parameter must be set to True in order to utilize the correction factors, which ensure the data passes through 0 and the observation. without the backwards simulation, this is already ensured. However, for Aspen, the factor found is also used for the forward simulation

pygypsy.io module

IO

pygypsy.io.df_to_s3_bucket(df, bucket_conn, key, **kwargs)[source]

Write dataframe to s3 bucket

Parameters:
  • df – data frame
  • bucket_conn – boto3 bucket object
  • key – object key
  • kwargs – additional keyword arguments to pandas.to_csv

pygypsy.log module

Package Loggers

pygypsy.log.setup_logging()[source]

Initialize logging for pygypsy package

pygypsy.path module

Path utility

pygypsy.plot module

Plotting Convenience Functions

pygypsy.plot.save_plot(simulation_dataframe, path)[source]

Save plots of pygypsy simulation output

Creates a panel and includes all plots generated as pygypsy outputs (simulation_dataframe) and saves the panel on a folder determined byt path

pygypsy.site_index module

Functions for calculating site indices

pygypsy.site_index.get_site_indices_from_dominant_species(dominant_species=None, dominant_species_site_index=None)[source]

Calculate site indices for non-dominant species

Keyword Arguments: dominant_species – (default None) dominant_species_site_index – (default None)

pygypsy.stand_density_factor module

Stand density factor estimators

pygypsy.stand_density_factor.estimate_sdf_aw(spc, site_index, bhage, density)[source]

Main purpose of this function is to estimate SDF for the species

Parameters:
  • spc (str) – species_abbreviation
  • site_index (float) – site index of species Aw
  • bhage (float) – breast height age of speceis Aw
  • density (float) – density of species Aw
pygypsy.stand_density_factor.estimate_sdf_pl(spc, site_index, tage, sdfaw, sdfsw, sdfsb, density)[source]

Main purpose of this function is to estimate SDF for the species

Parameters:
  • spc (str) – species_abbreviation
  • site_index (float) – site index of species Pl
  • tage (float) – total age of species Pl
  • sdfaw (float) – Stand Density Factor of species Aw
  • sdfsw (float) – Stand Density Factor of species Sw
  • sdfpl (float) – Stand Density Factor of species Pl

these parameters SDF above indicate that the density of Pl depends on the density of all otehr species :param float density: density of species Pl

pygypsy.stand_density_factor.estimate_sdf_sb(spc, site_index, tage, density)[source]

Main purpose of this function is to estimate SDF for the species

Parameters:
  • spc (str) – species_abbreviation
  • site_index (float) – site index of species Sb
  • tage (float) – total age of species Sb
  • density (float) – density of species Sb
pygypsy.stand_density_factor.estimate_sdf_sw(spc, site_index, tage, sdfaw, density)[source]

Main purpose of this function is to estimate SDF for the species

Parameters:
  • spc (str) – species_abbreviation
  • site_index (float) – site index of species Sw
  • tage (float) – total age of species Sw
  • sdfaw (float) – Stand Density Factor of species Aw, this parameter indicates that

the density of Sw depends on the density of Aw :param float density: density of species Sw

pygypsy.utils module

Helper Functions

pygypsy.utils.estimate_species_composition(n_aw, n_sb, n_sw, n_pl)[source]

Calculates species composition based on their densities

Parameters:N_Aw, N_Sb, N_Sw, and N_Pl (float) – densities of the respective species

pygypsy.volume module

Volume calculations

pygypsy.volume.gross_total_volume(species, *args)[source]

Gross total volume

Parameters:
  • species (str) – species abbreviation
  • *args –

    additional arguments to species specific gross total volume functions
pygypsy.volume.merchantable_volume(species, *args, **kwargs)[source]

Merchantable volume

Parameters:
  • species (str) – species abbreviation
  • *args –

    additional arguments to species specific gross total volume functions

Module contents

pygypsy

Based on Hueng et all (2009)

Huang, S., Meng, S. X., & Yang, Y. (2009). A growth and yield projection system (GYPSY) for natural and post-harvest stands in Alberta. Forestry Division, Alberta Sustainable Resource Development, 25.

Important Acronyms:

aw = white aspen sb = black spruce sw = white spruce pl = logdepole pine bhage = Breast Height Age tage = Total age si_<xx> = estimated site index for species <xx> y2bh = years until breast height age can be measured