Crop Production Package

Model Entry Point

invest_natcap.crop_production.crop_production.execute(args)

Entry point into the Crop Production Model

Parameters:
  • args['workspace_dir'] (str) – location into which all intermediate and output files should be placed.
  • args['results_suffix'] (str) – a string to append to output filenames
  • args['crop_lookup_table_uri'] (str) – filepath to a CSV table used to convert the crop code provided in the Crop Map to the crop name that can be used for searching through inputs and formatting outputs.
  • args['lulc_map_uri'] (str) – a GDAL-supported raster representing a crop management scenario.
  • args['fertilizer_maps_dir'] (str) – filepath to folder that should contain a set of GDAL-supported rasters representing the amount of Nitrogen (N), Phosphorous (P2O5), and Potash (K2O) applied to each area of land (kg/ha).
  • args['spatial_dataset_dir'] (str) – the provided folder should contain a set of folders and data specified in the ‘Running the Model’ section of the model’s User Guide.
  • args['create_crop_production_maps'] (boolean) – If True, a set of crop production maps is saved within the folder of each yield function.
  • args['do_yield_observed'] (boolean) – if True, calculates yield based on observed yields within region and creates associated outputs.
  • args['do_yield_percentile'] (boolean) – if True, calculates yield based on climate-specific distribution of observed yields and creates associated outputs
  • args['do_yield_regression'] (boolean) – if True, calculates yield based on yield regression model with climate-specific parameters and creates associated outputs
  • args['modeled_irrigation_map_uri'] (str) – filepath to a GDAL-supported raster representing whether irrigation occurs or not. A zero value indicates that no irrigation occurs. A one value indicates that irrigation occurs. If any other values are provided, irrigation is assumed to occur within that cell area.
  • args['do_nutrition'] (boolean) – if true, calculates nutrition from crop production and creates associated outputs.
  • args['nutrition_table_uri'] (str) – filepath to a CSV table containing information about the nutrient contents of each crop.
  • args['do_economic_returns'] (boolean) – if true, calculates economic returns from crop production and creates associated outputs.
  • args['economics_table_uri'] (str) – filepath to a CSV table containing information related to market price of a given crop and the expenses involved with producing that crop.

Example Args:

args = {
    'workspace_dir': 'path/to/workspace_dir/',
    'results_suffix': 'scenario_name',
    'crop_lookup_table_uri': 'path/to/crop_lookup_table_uri',
    'lulc_map_uri': 'path/to/lulc_map_uri',
    'do_fertilizer_maps': True,
    'fertilizer_maps_dir': 'path/to/fertilizer_maps_dir/',
    'spatial_dataset_dir': 'path/to/spatial_dataset_dir/',
    'create_crop_production_maps': True,
    'do_yield_observed': True,
    'do_yield_percentile': True,
    'do_yield_regression': True,
    'modeled_irrigation_map_uri': 'path/to/modeled_irrigation_map_uri/',
    'do_nutrition': True,
    'nutrition_table_uri': 'path/to/nutrition_table_uri',
    'do_economic_returns': True,
    'economics_table_uri': 'path/to/economics_table_uri',
}

Example Returns:

results_dict = {
    'observed_vars_dict': {
        # ...
        'crop_production_dict': {...},
        'economics_table_dict': {...},
        'crop_total_nutrition_dict': {...}
    },
    'percentile_vars_dict': {
        # ...
        'crop_production_dict': {...},
        'economics_table_dict': {...},
        'crop_total_nutrition_dict': {...}
    },
    'regression_vars_dict': {
        # ...
        'crop_production_dict': {...},
        'economics_table_dict': {...},
        'crop_total_nutrition_dict': {...}
    }
}

Crop Production IO Module

The Crop Production IO module contains functions for handling inputs and outputs

exception invest_natcap.crop_production.crop_production_io.MissingParameter(msg)

Bases: exceptions.StandardError

An exception class that may be raised when a necessary parameter is not provided by the user.

invest_natcap.crop_production.crop_production_io.assert_crops_in_list(vars_dict, key)
invest_natcap.crop_production.crop_production_io.convert_dict_to_unicode(data)
Converts strings and strings nested in dictionaries and lists
to unicode.
invest_natcap.crop_production.crop_production_io.create_crops_in_aoi_list(vars_dict)

Example Returns:

vars_dict = {
    # ...
    'crops_in_aoi_list': ['corn', 'rice', 'soy']
}
invest_natcap.crop_production.crop_production_io.create_results_table(vars_dict, percentile=None, first=True)
Creates a table of results for each yield function. This includes
production information as well as economic and nutrition information if the necessary inputs are provided.

Example Args:

vars_dict = {
    'crop_production_dict': {
        'corn': 12.3,
        'soy': 13.4,
        ...
    },
    'economics_table_dict': {
        'corn': {
            'total_cost': <float>,
            'total_revenue': <float>,
            'total_returns': <float>,
            ...
        }
    },
    'crop_total_nutrition_dict': {
        'corn': {...},
        ...
    },
}
invest_natcap.crop_production.crop_production_io.fetch_climate_bin_maps(vars_dict)

Fetches a dictionary of URIs to climate bin maps with crop names as keys

Example Returns:

vars_dict = {
    # ... previous vars ...

    'climate_bin_maps_dir': 'path/to/climate_bin_maps_dir/',
    'climate_bin_maps_dict': {
        'crop': 'path/to/crop_climate_bin_map',
        ...
    },
}
invest_natcap.crop_production.crop_production_io.fetch_fertilizer_maps(vars_dict)
Fetches a dictionary of URIs to fertilizer maps with fertilizer names as
keys.

Example Returns:

vars_dict = {
    # ... previous vars ...

    'fertilizer_maps_dict': {
        'nitrogen': 'path/to/nitrogen_fertilizer_map',
        'phosphorous': 'path/to/phosphorous_fertilizer_map',
        'potash': 'path/to/potash_fertilizer_map'
    },
}
invest_natcap.crop_production.crop_production_io.fetch_observed_yield_maps(vars_dict)

Fetches a dictionary of URIs to observed yield maps with crop names as keys

Parameters:observed_yield_maps_dir (str) – descr
Returns:observed_yields_maps_dict – descr
Return type:dict

Example Returns:

vars_dict = {
    # ... previous vars ...

    'observed_yield_maps_dir': 'path/to/observed_yield_maps_dir/',
    'observed_yields_maps_dict': {
        'crop': 'path/to/crop_yield_map',
        ...
    },
}
invest_natcap.crop_production.crop_production_io.fetch_spatial_dataset(vars_dict)

Fetches necessary variables from provided spatial dataset folder

Example Returns:

vars_dict = {
    # ... previous vars ...

    'observed_yield_maps_dir': 'path/to/observed_yield_maps_dir/',
    'observed_yields_maps_dict': {
        'crop': 'path/to/crop_yield_map',
        ...
    },
    'climate_bin_maps_dir': 'path/to/climate_bin_maps_dir/',
    'climate_bin_maps_dict': {
        'crop': 'path/to/crop_climate_bin_map',
        ...
    },
    'percentile_table_uri': 'path/to/percentile_table_uri',
    'percentile_yield_dict': {
        'crop': {
            <climate_bin>: {
                'yield_25th': <float>,
                'yield_50th': <float>,
                'yield_75th': <float>,
                'yield_95th': <float>,
                ...
            },
        }
        ...
    },
    'modeled_yield_tables_uri': 'path/to/modeled_yield_tables_uri',
    'modeled_yield_dict': {
        'crop': {
            'climate_bin': {
                'yield_ceiling': '<float>',
                'yield_ceiling_rf': '<float>',
                'b_nut': '<float>',
                'b_K2O': '<float>',
                'c_N': '<float>',
                'c_P2O5': '<float>',
                'c_K2O': '<float>',
            },
        },
        ...
    },
}
invest_natcap.crop_production.crop_production_io.get_inputs(args)

Fetches inputs from the user, verifies for correctness and completeness, and returns a list of variables dictionaries

Parameters:args (dictionary) – arguments from the user
Returns:vars_dict – dictionary of variables to be used in the model
Return type:dictionary

Example Returns:

vars_dict = {
    # ... original args ...

    # Workspace
    'intermediate_dir': 'path/to/intermediate_dir',
    'output_dir': 'path/to/output_dir',

    # Crop Lookup Table
    'crop_lookup_dict': {
        'code': 'crop_name',
        ...
    },
    'crops_in_aoi_list': ['crop1', 'crop2', 'crop3'],

    'fertilizer_maps_dict': {
        'nitrogen': 'path/to/nitrogen_fertilizer_map',
        'phosphorous': 'path/to/phosphorous_fertilizer_map',
        'potash': 'path/to/potash_fertilizer_map'
    },

    # From spatial_dataset_dir
    'observed_yield_maps_dir': 'path/to/observed_yield_maps_dir/',
    'observed_yields_maps_dict': {
        'crop': 'path/to/crop_yield_map',
        ...
    },
    'climate_bin_maps_dir': 'path/to/climate_bin_maps_dir/',
    'climate_bin_maps_dict': {
        'crop': 'path/to/crop_climate_bin_map',
        ...
    },
    'percentile_table_uri': 'path/to/percentile_table_uri',
    'percentile_yield_dict': {
        'crop': {
            <climate_bin>: {
                'yield_25th': <float>,
                'yield_50th': <float>,
                'yield_75th': <float>,
                'yield_95th': <float>,
                ...
            },
        }
        ...
    },
    'modeled_yield_tables_dir': 'path/to/modeled_yield_tables_dir',
    'modeled_yield_dict': {
        'crop': {
            <climate_bin>: {
                'yield_ceiling': '<float>',
                'yield_ceiling_rf': '<float>',
                'b_nut': '<float>',
                'b_K2O': '<float>',
                'c_N': '<float>',
                'c_P2O5': '<float>',
                'c_K2O': '<float>',
            },
        },
        ...
    },

    # For Nutrition
    'nutrition_table_dict': {
        'crop': {
            'fraction_refuse': <float>,
            'protein': <float>,
            'lipid': <float>,
            'energy': <float>,
            'ca': <float>,
            'fe': <float>,
            'mg': <float>,
            'ph': <float>,
            ...
        },
        ...
    },

    # For Economic Returns
    'economics_table_dict': {
        'crop': {
            'price': <float>,
            'cost_nitrogen': <float>,
            'cost_phosphorous': <float>,
            'cost_potash': <float>,
            'cost_labor': <float>,
            'cost_mach': <float>,
            'cost_seed': <float>,
            'cost_irrigation': <float>
        }
    },
}
invest_natcap.crop_production.crop_production_io.read_crop_lookup_table(vars_dict)

Reads in the Crop Lookup Table and returns a dictionary

Example Returns:

vars_dict = {
    # ... previous vars ...

    'crop_lookup_table_uri': '/path/to/crop_lookup_table_uri'
    'crop_lookup_dict': {
        'code': 'crop_name',
        ...
    }
}
invest_natcap.crop_production.crop_production_io.read_economics_table(vars_dict)

Reads in the Economics Table and returns a dictionary of values

Example Returns:

vars_dict = {
    # ... previous vars ...

    'economics_table_dict': {
        'crop': {
            'price': <float>,
            'cost_nitrogen': <float>,
            'cost_phosphorous': <float>,
            'cost_potash': <float>,
            'cost_labor': <float>,
            'cost_mach': <float>,
            'cost_seed': <float>,
            'cost_irrigation': <float>
        }
    },
}
invest_natcap.crop_production.crop_production_io.read_nutrition_table(vars_dict)

Reads in the Nutrition Table and returns a dictionary of values

Example Returns:

vars_dict = {
    # ... previous vars ...

    'nutrition_table_dict': {
        'crop': {
            'fraction_refuse': <float>,
            'protein': <float>,
            'lipid': <float>,
            'energy': <float>,
            'ca': <float>,
            'fe': <float>,
            'mg': <float>,
            'ph': <float>,
            ...
        },
        ...
    },
}
invest_natcap.crop_production.crop_production_io.read_percentile_yield_tables(vars_dict)

Reads in the Percentile Yield Table and returns a dictionary

Example Returns:

vars_dict = {
    # ... previous vars ...

    'percentile_yield_tables_dir': 'path/to/percentile_yield_tables_dir/',
    'percentile_yield_dict': {
        'crop': {
            <climate_bin>: {
                'yield_25th': <float>,
                'yield_50th': <float>,
                'yield_75th': <float>,
                'yield_95th': <float>,
                ...
            },
        }
        ...
    },
}
invest_natcap.crop_production.crop_production_io.read_regression_model_yield_tables(vars_dict)

Reads the regression model yield tables and returns a dictionary of values

Example Returns:

vars_dict = {
    # ... previous vars ...

    'modeled_yield_tables_dir': 'path/to/modeled_yield_tables_dir/',
    'modeled_yield_dict': {
        'crop': {
            <climate_bin>: {
                'yield_ceiling': '<float>',
                'yield_ceiling_rf': '<float>',
                'b_nut': '<float>',
                'b_K2O': '<float>',
                'c_N': '<float>',
                'c_P2O5': '<float>',
                'c_K2O': '<float>',
            },
        },
        ...
    },
}

Crop Production Model Module

The Crop Production Model module contains functions for running the model

invest_natcap.crop_production.crop_production_model.calc_observed_yield(vars_dict)

Calculates yield using observed yield function

Parameters:vars_dict (dict) – descr

Example Args:

vars_dict = {
    # ...

    'lulc_map_uri': '/path/to/lulc_map_uri',
    'crop_lookup_dict': {
        'code': 'crop_name',
        ...
    },
    'observed_yields_maps_dict': {
        'crop': '/path/to/crop_climate_bin_map',
        ...
    },
    'economics_table_dict': {
        'crop': {
            'price': <float>,
            ...
        }
        ...
    },
}
invest_natcap.crop_production.crop_production_model.calc_percentile_yield(vars_dict)

Calculates yield using the percentile yield function

Example Args:

vars_dict = {
    'percentile_yield_dict': {
        ''
    },
    '': ''
}
invest_natcap.crop_production.crop_production_model.calc_regression_yield(vars_dict)

Calculates yield using the regression model yield function

Example Args:

vars_dict = {
    ...

    'fertilizer_maps_dict': {...},
    'modeled_irrigation_map_uri': '',
    'modeled_yield_dict': {...}
}

Module contents