Metadata-Version: 1.0
Name: python-consume
Version: 0.1.0
Summary: Python port of Consume, a software program developed by the USFS that calculates consumption and emissions from wildland fires
Home-page: http://pypi.python.org/pypi/python-consume
Author: Tyler A. Erickson
Author-email: tylerickson@gmail.com
License: BSD
Description: ==============
        Python-Consume
        ==============
        Python-Consume is a Python package that is a port of Consume 3.0, a software 
        program developed by the USFS that calculates consumption and emissions from 
        wildland fires.
        
        Consume 3.0 was developed and designed originally in Java by US Forest 
        Service Fire and Environmental Research Applications (FERA) team.
        
        This is a recoded version (2010) developed by Michigan Tech Research
        Institute (MTRI) in consultation with FERA.  This version was developed
        for use in MTRI's Wildfire Emissions Information System (WFEIS) 
        (wfeis.mtri.org), but was also designed to include more user-friendly
        shell-based analysis options.
        
        During the recoding process, several errors were identified in the original
        Consume 3.0 source code, but were fixed (via consultation with original
        developers Roger Ottmar and Susan Prichard) for this version. For this reason,
        results from this version will not always align with results from the official
        Consume 3.0 GUI version of the software. Notable errors include:
        
            (1) incorrect calculation of 'duff' reduction (p. 182 in the Consume 3.0
            (2) a bug that interchanges 'squirrel midden' density and radius when FCCS
                values are loaded
            (3) a typo that incorrectly calculates pm2.5 emissions from 'canopy'
                consumption (thus influencing total pm2.5 emissions values as well)
        
        * For users familiar with the original Consume 3.0 GUI software, see the 
          notes section below for functionality and operational differences between
          this version and the original.
        
        References:
        
        * CONSUME: http://www.fs.fed.us/pnw/fera/research/smoke/consume/index.shtml
        * FCCS: http://www.fs.fed.us/pnw/fera/fccs/
        * FERA: http://www.fs.fed.us/pnw/fera/F
        * MTRI: http://www.mtri.org
        
        Requirements:
        
        * Python 2.4 or above (free from http://www.python.org)
        * numpy package (free from http://np.scipy.org/)
        
        For questions/comments, contact:
        
        * Michael G. Billmire mgbillmi@mtu.edu
        * Tyler A. Erickson taericks@mtu.edu
        
        ------------
        Dependencies
        ------------
        * Python 2.4 or above 
        * python-numpy (free from http://np.scipy.org/)
        
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        Notes for users familiar with the original Consume 3.0 GUI software
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        * This version relies entirely on FCCS fuelbed data and does NOT use SAF/SRM
          cover type data except in the background for selecting the correct emissions
          factor groups to use from a link table provided by FERA.
        * **Heat release** output is coupled with consumption outputs.
        * Instead of selecting a specific ecoregion from Bailey's set, this version only
          requires the user to specify whether the fuelbed is located in *western*, 
          *boreal*, or *southern* regions. See the original Consume 3.0 User's Manual
          to view which Bailey's ecoregions fit into these broader categories. 
        
        ------------
        Installation
        ------------
        Python-Consume can be installed from the Python Package Index, using either 
        easy_install or pip:
        
          $ sudo easy_install python-consume
        
        or
        
          $ sudo pip install python-consume
        
        The installation can be tested by running the following:
        
          $ nosetests -s --with-coverage
        
        -------------------------------------------
        Usage
        -------------------------------------------
        
        (See next section for a complete, uninterrupted example...)
        
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        Getting Started with the Fuel Consumption Object
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        Open a Python shell program (e.g. IDLE, ipython, etc.).
        Import the module:
        
        >>> from consume import consume
        
        Declare a Consume FuelConsumption object:
        
        >>> fc_obj = consume.FuelConsumption()
        
        ..
        
          Note: if the .xml fuel loading database is located somewhere other than
          the default location, user can specify this using the 'fccs_file' argument,
          e.g.:
          fc_obj = consume.FuelConsumption(fccs_file="C:/Documents/FCCSLoadings.xml")
        
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        SETTING INPUT PARAMETERS
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        There are a number of alternative options for setting input values:
        
        1.  Start a program that will prompt the user for inputs:
            >>> fc_obj.prompt_for_inputs()
        
        2.  Load inputs from a pre-formatted csv file (see example file:
            "consume_inputs_example.csv" for correct formatting):
            
            >>> fc_obj.load_scenario("myscenario.csv")
            
            OR to load, calculate outputs, and store outputs at once, use the
            batch_process method:
            
            >>> fc_obj.batch_process("myscenario.csv", "myoutputs.csv")
        
        3.  Individually set/change input values manually:
            
            >>> fc_obj.burn_type = <'natural' or 'activity'>
            >>> fc_obj.fuelbed_fccs_ids = [FCCSID#1,FCCSID#2,...]
            >>> fc_obj.fuelbed_area_acres = [AREA#1,AREA#2,...]
            >>> fc_obj.fuelbed_ecoregion = [ECOREGION#1, ECOREGION#2,...]
            >>> fc_obj.fuel_moisture_1000hr_pct = [1000hrFM#1, 1000hrFM#2,...]
            >>> fc_obj.fuel_moisture_duff_pct = [DuffFM#1, DuffFM#2, ...]
            >>> fc_obj.canopy_consumption_pct = [PctCan#1, PctCan#2,...]
            >>> fc_obj.shrub_blackened_pct = [PercentShrub#1, PercentShrub#2,...]
        
            inputs specific to 'activity' burns:
            
            >>> fc_obj.fuel_moisture_10hr_pct = [10HourFM#1, 10HourFM#2, ...]
            >>> fc_obj.slope = [Slope#1, Slope#2, ...]
            >>> fc_obj.windspeed = [Windspeed#1, Windspeed#2, ...]
            >>> fc_obj.fm_type = <'MEAS-Th', 'ADJ-Th', or 'NFDRS-Th'>
            >>> fc_obj.days_since_rain = [Days#1, Days#2, ...]
            >>> fc_obj.lengthOfIgnition = [Length#1, Length#2, ...]
        
        
            *Note: When setting input values, the user can also select a SINGLE 
            value (instead of a list) for any environment variable that will 
            apply to the entire scenario.
            These environment variables include the following:
            ecoregion, fuel_moisture_1000hr_pct,  fuel_moisture_duff_pct, 
            canopy_consumption_pct, shrub_blackened_pct, slope, windpseed, 
            fm_type, days_since_rain, lengthOfIgnition*
        
        Description of the input parameters:
        
        burn_type
            Use this variable to select 'natural' burn equations or 
            'activity' (i.e. prescribed) burn equations. Note that
            'activity' burns require 6 additional input parameters:
            10hr fuel moisture, slope, windpseed, fuel moisture type,
            days since significant rainfall, and length of ignition.
            
        fuelbed_fccs_ids
            a list of Fuel Characteristic Classification System (FCCS)
            (http://www.fs.fed.us/pnw/fera/fccs/index.shtml) fuelbed ID
            numbers (1-291).  Use the .FCCS.browse() method to load a list
            of all FCCS ID#'s and their associated site names. Use 
            .FCCS.info(id#) to get a site description of the
            specified FCCD ID number. To get a complete listing of fuel
            loadings for an FCCS fuelbed, use: 
            .FCCS.info(id#, detail=True)
        
        fuelbed_area_acres
            a list (or single number to be used for all fuelbeds) of
            numbers in acres that represents area for the corresponding
            FCCS fuelbed ID listed in the 'fuelbeds_fccs_ids' variable.
        
        fuelbed_ecoregion
            a list (or single region to be used for all fuelbeds) of
            ecoregions ('western', 'southern', or 'boreal') that
            represent the ecoregion for the corresponding FCCS fuelbed ID
            listed in the 'fuelbeds_fccs_ids' variable. Regions within the
            US that correspond to each broad regional description can be
            found in the official Consume 3.0 User's Guide, p. 60. Further
            info on Bailey's ecoregions can be found here:
            www.eoearth.org/article/Ecoregions_of_the_United_States_(Bailey)
            Default is 'western'
        
        fuel_moisture_1000hr_pct
            1000-hr fuel moisture in the form of a number or list of
            numbers ranging from 0-100 representing a percentage.
            Default is 50%
        
        fuel_moisture_10hr_pct
            <specific to 'activity' burns>
            10-hr fuel moisture in the form of a number or list of
            numbers ranging from 0-100 representing a percentage.
            Default is 50%
        
        fuel_moisture_duff_pct
            Duff fuel moisture. A number or list of numbers ranging from
            0-100 representing a percentage.
            Default is 50%.
        
        canopy_consumption_pct
            Percent canopy consumed. A number or list of numbers ranging
            from 0-100 representing a percentage. Set to '-1' to
            use an FCCS-fuelbed dependent precalculated canopy consumption
            percentage based on crown fire initiation potential, crown to
            crown transmissivity, and crown fire spreading potential.
            (note: auto-calc is not available for FCCS ID's 401-456)
            Default is -1
        
        shrub_blackened_pct
            Percent of shrub that has been blackened. A number or list
            of numbers ranging from 0-100 representing a percentage.
            Default is 50%
        
        slope
            <specific to 'activity' burns>
            Percent slope of a fuelbed unit. Used in predicting 100-hr
            (1-3" diameter) fuel consumption in 'activity' fuelbeds.
            Valid values: a number or list of numbers ranging from 0-100
            representing a percentage.
            Default is 5%
        
        windspeed
            <specific to 'activity' burns>
            Mid-flame wind speed (mph) during the burn. Maximum is 35 mph.
            Used in predicting 100-hr (1-3" diameter) fuel consumption in 
            'activity' fuelbeds.
            Default is 5 mph
        
        fm_type
            <specific to 'activity' burns>
            Source of 1000-hr fuel moisture data.
                
                * "Meas-Th" (default) : measured directly
                * "NFDRS-Th" : calculated from NFDRS
                * "ADJ-Th" : adjusted for PNW conifer types
            
            Note: 1000-hr fuel moisture is NOT calculated by Consume, 
            i.e. user must derive 1000-hr fuel moisture & simply select
            the method used.
        
        days_since_rain
            <specific to 'activity' burns>
            Number of days since significant rainfall. According to the
            Consume 3.0 User's Guide, "Significant rainfall is one-quarter
            inch in a 48-hour period." Used to predict duff consumption
            in 'activity' fuelbeds.
        
        lengthOfIgnition
            <specific to 'activity' burns>
            The amount of time (minutes) it will take to ignite the area
            to be burned. Used to determine if a fire will be of high 
            intensity, which affects diameter reduction of large woody
            fuels in 'activity' fuelbeds.
        
        The user can also optionally set alternate output units. Use the
        list_valid_units() method to view output unit options.
        Default fuel consumption units are tons/acre ('tons_ac').
        
        >>> consume.list_valid_units()
        
        Output::
        
            ['lbs',
             'lbs_ac',
             'tons',
             'tons_ac',
             'kg',
             'kg_m^2',
             'kg_ha',
             'kg_km^2'
             'tonnes',
             'tonnes_ha',
             'tonnes_km^2']
        
        
        >>> fc_obj.output_units = 'lbs'
        
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        CUSTOMIZING FUEL LOADINGS
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        Fuel loadings are automatically imported from the FCCS database based on the
        FCCS fuelbed ID#s selected by the user. If desired, the user can also 
        customize FCCS fuel loadings by setting the '.customized_fuel_loadings' variable
        to a list of 3 value lists in this format:
        [fuelbed index number {interger}, fuel stratum {string}, loading value {number}]
        
        e.g.:
        
        >>> fc_obj.customized_fuel_loadings = [[1, 'overstory', 4.5],[2, 'shrub_prim', 5]]
        
        The above command will change the canopy 'overstory' loading in the first ('1')
        fuelbed to 4.5 (tons/acre) and will change the 'shrub_prim' (primary shrub
        loading) in the second ('2') fuelbed to 5 tons/acre. To view all valid stratum
        names and units, use the fc_obj.FCCS.list_fuel_loading_names() method.
        
        
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        OUTPUTS
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        Consumption outputs can be accessed by calling the .results(), .report(), or
        .batch_process() methods. Calling any of these methods will trigger the 
        calculation of all fuel consumption equation and will return the results in 
        a variety of different formats:
        
        
        >>> fc_obj.results()
        
        ... generates & prints a python DICTIONARY of consumption
        results by fuel category (major and minor categories)
        See complete example below to see how individual
        data categories can be accessed from this dictionary.
        
        >>> fc_obj.report(csv="")
        
        ...prints a TABULAR REPORT of consumption results for
        the major fuel categories (similar to the "Fuel
        Consumption by Combustion Stage" report produced by the
        official Consume 3.0 GUI program).  To export a version 
        of this report as a CSV FILE, use the 'csv' argument to 
        specify a file name, e.g.:
        >>> fc_obj.report(csv = "consumption_report.csv")
        
        >>> fc_obj.batch_process(csvin="", csvout="")
        
        ...similar to the .report() method, although requires an
        input csv file and will export results to the specified
        CSV output.
        
        
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        OTHER USEFUL METHODS
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        >>> consume.list_valid_units()        
        
        ...displays a list of valid output unit options
        
        >>> consume.list_valid_consumption_strata()
        
        ...displays a list of valid consumption strata group names
        
        >>> fc_obj.list_variable_names()
        
        ...displays a list of the variable names used for each input parameter
        
        >>> fc_obj.FCCS.browse()
        
        ...loads a list of all FCCS fuelbed ID numbers and their site names
        
        >>> fc_obj.FCCS.info(#)
        
        ...provides site description of the FCCS fuelbed with the specified ID number. 
        Set detail=True to print out detailed fuel loading information
        
        >>> fc_obj.FCCS.get_canopy_pct(#)
        
        ...displays estimated canopy consumption percent as calculated by MTRI for the 
        specified FCCS ID number. This is the  value that will be used if 
        canopy_consumption_pct is set to -1.
        
        >>> fc_obj.load_example()
        
        ...loads an example scenario with 2 Fuelbeds
        
        >>> fc_obj.reset_inputs_and_outputs()
        
        ...clears input and output parameters
        
        >>> fc_obj.display_inputs()
        
        ...displays a list of the input parameters.
        Useful for checking that scenario parameters were set correctly
        
        
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        Working with the EMISSIONS Object
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        For emissions data, declare a Consume Emissions object by nesting in the
        FuelConsumption object we were working on above as the only required argument.
        
        >>> e_obj = consume.Emissions(fc_obj)
        
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        SETTING INPUT PARAMETERS
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        Input parameters for emissions calculations are much easier to set than those
        for FuelConsumption, as they are ALL ultimately automatically derived from the
        parameters set within the nested FuelConsumption object.
        The input parameters required for the emissions calculations are as follows:
        
        *  FUEL CONSUMPTION (tons/ac) & the scenario of corresponding FCCS ID#s,
           AREAS, and ECOREGIONS, all of which is derived from the FuelConsumption
           object specified in the Emissions object declaration we just did
        
        *  EMISSIONS FACTOR GROUP ('efg'), which specifies the appropriate set of
           emissions factors (lbs/tons consumed for each of 7 emissions species) 
           to use for the scenario. This is automatically selected based on the 
           FCCS fuelbeds in the consumption scenario, but the user can override
           the auto-select process if desired as described below.
        
        As with the FuelConsumption object, the user can also optionally set alternate 
        output units for the Emissions object. Use the consume.list_valid_units() method
        to view output unit options.
        Default output units for emissions are lbs/ac.
        
        >>> e_obj.output_units = 'kg_ha'
        
        To change the FuelConsumption units, simply modify the units of the FC object
        that is nested within the Emissions object:
        
        >>> e_obj.FCobj.output_units = 'kg_ha'
        
        
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        OUTPUTS
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        As with the FuelConsumption object, Emissions outputs can be accessed by 
        calling the .results() or .report() methods. Calling either methods will trigger
        the calculation of emissions and output results in a variety of different
        formats:
        
        >>> e_obj.results()
        
        ...generates a python DICTIONARY similar to the one created
        by the FuelConsumption object, but with Emissions
        results added (consumption data is also included).
        See complete example below to see how specific
        data categories can be accessed in this dictionary.
        
        >>> e_obj.report()
        
        ...prints a TABULAR REPORT of emissions results for all
        pollutants and combustion stages (similar to the
        "Emissions by Combustion Stage" report produced in 
        the official Consume 3.0 GUI program).  To export
        a version of this report as a CSV FILE, use the
        'csv' argument to specify a file name, e.g.:
        >>> e_obj.report(csv = "emissions_report.csv")
        
        
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        OTHER USEFUL METHODS
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        >>> e_obj.display_inputs()
        
        ...displays a list of the input parameters.
        Useful for checking that scenario
        parameters were set correctly
        
        >>> e_obj.efDB.browse()
        
        ...displays a list of all emissions factor
        groups and their associated fuel types
        and references
        
        >>> e_obj.efDB.info(#)
        
        ...display detailed information about the
        specified emissions factor group ID#
        (use the .browse() method above to view
        ID#s). Includes the actual emissions
        factor values.
        
        For further help on specific methods or properties,
        type "help([CONSUME METHOD])" within a python shell, e.g.:
        
        >>> help(fc_obj.FCCS.info)
        
        Output::
        
          Help on method info in module consume_obj:
          
          info(self, fccs_id, detail=False) method of consume_obj.FCCSDB instance
              Display an FCCS fuelbed description.
              
              Prints fuel loading information on the fuelbed with the specified
              FCCS ID. Requires one argument: an integer refering to a specific FCCS
              ID. For a list of valid FCCS IDs, use the .browse() method."
        
        
        -------------------------------------------
        Complete Uninterrupted Example
        -------------------------------------------
        
        The following example sets up a 'natural' burn scenario in which 100 acres FCCS 
        fuelbed ID #1 ("Black cottonwood - Douglas fir - Quaking aspen riparian forest")
        and 200 acres of FCCS fuelbed ID #47 ("Redwood - Tanoak forest") are consumed.
        1000-hr and duff fuel moisture is set at 50% for fuelbed ID #1 and 40% for
        fuelbed ID #47. Canopy consumption and shrub percent black is set at 25% for
        both fuelbeds.
        
        >>> from consume import consume
        >>> fc_obj = consume.FuelConsumption()
        >>> fc_obj.fuelbed_fccs_ids = [1, 47]
        >>> fc_obj.fuelbed_area_acres = [100, 200]
        >>> fc_obj.fuelbed_ecoregion = 'western'
        >>> fc_obj.fuel_moisture_1000hr_pct = [50, 40]
        >>> fc_obj.fuel_moisture_duff_pct = [50, 40]
        >>> fc_obj.canopy_consumption_pct = 25
        >>> fc_obj.shrub_blackened_pct = 25
        >>> fc_obj.output_units = 'kg_ha'
        >>> fc_obj.display_inputs()
        
        Output::
        
          Current scenario parameters:
          
          Parameter                   Value(s)
          \--------------------------------------------------------------
          Burn type                   natural
          FCCS fuelbeds (ID#)         [1, 47]
          Fuelbed area (acres)        [100, 200]
          Fuelbed ecoregion           western
          Fuel moisture (1000-hr, %)  [50, 40]
          Fuel moisture (duff, %)     [50, 40]
          Canopy consumption (%)      25
          Shrub blackened (%)         25
          Output units                kg_ha
        
        
        >>> fc_obj.report()
        
        Output::
        
            FUEL CONSUMPTION
            Consumption units: kg/ha
            Heat release units: btu/ha
            Total area: 300 acres
        
            FCCS ID: 1
            Area:    100
            Ecoregion: western
            CATEGORY        Flaming     Smoldering  Residual    TOTAL
            canopy          1.25e+04    9.58e+02    1.51e+02    1.36e+04
            shrub           1.26e+03    6.97e+01    0.00e+00    1.33e+03
            nonwoody        3.95e+02    2.08e+01    0.00e+00    4.16e+02
            llm             2.32e+03    2.20e+02    0.00e+00    2.54e+03
            ground fuels    8.97e+02    1.51e+04    3.72e+04    5.32e+04
            woody fuels     9.71e+03    5.61e+03    8.81e+03    2.41e+04
            TOTAL:          2.70e+04    2.20e+04    4.61e+04    9.52e+04
        
            Heat release:   1.19e+08    9.70e+07    2.03e+08    4.20e+08
        
        
            FCCS ID: 47
            Area:    200
            Ecoregion: western
            CATEGORY        Flaming     Smoldering  Residual    TOTAL
            canopy          7.93e+03    2.48e+03    2.05e+03    1.25e+04
            shrub           3.87e+03    2.69e+02    0.00e+00    4.13e+03
            nonwoody        9.88e+02    5.20e+01    0.00e+00    1.04e+03
            llm             4.93e+03    5.41e+02    0.00e+00    5.47e+03
            ground fuels    3.59e+03    4.08e+04    6.98e+04    1.14e+05
            woody fuels     2.56e+04    2.06e+04    2.49e+04    7.11e+04
            TOTAL:          4.69e+04    6.47e+04    9.67e+04    2.08e+05
        
            Heat release:    2.07e+08    2.85e+08    4.27e+08    9.18e+08
        
        
            ALL FUELBEDS:
        
            Consumption:    4.03e+04    5.04e+04    7.99e+04    1.71e+05
            Heat release:   3.26e+08    3.82e+08    6.30e+08    1.34e+09
        
        
        
        >>> fc_obj.results()['consumption']['ground fuels']
        
        Output::
        
            {'basal accumulations': {'flaming': array([-0.,  0.]),
                                     'residual': array([-0.,  0.]),
                                     'smoldering': array([-0.,  0.]),
                                     'total': array([-0.,  0.])},
             'duff, lower': {'flaming': array([ 0.,  0.]),
                             'residual': array([ 35377.20573062,  62608.52081126]),
                             'smoldering': array([  8844.30143266,  15652.13020281]),
                             'total': array([ 44221.50716328,  78260.65101407])},
             'duff, upper': {'flaming': array([  896.68092549,  3586.72370195]),
                             'residual': array([ 1793.36185097,  7173.4474039 ]),
                             'smoldering': array([  6276.76647841,  25107.06591365]),
                             'total': array([  8966.80925487,  35867.23701949])},
             'squirrel middens': {'flaming': array([ 0.,  0.]),
                                  'residual': array([ 0.,  0.]),
                                  'smoldering': array([ 0.,  0.]),
                                  'total': array([ 0.,  0.])}}
        
        
        >>> e_obj = consume.Emissions(fc_obj)
        >>> e_obj.display_inputs()
        
        Output::
        
            CONSUMPTION
        
            Current scenario parameters:
        
            Parameter                    Value(s)
            \--------------------------------------------------------------
            Burn type                    ['natural']
            FCCS fuelbeds (ID#)          [1, 47]
            Fuelbed area (acres)         [ 100.  200.]
            Fuelbed ecoregion            ['western']
            Fuel moisture (1000-hr, %)   [ 50.  40.]
            Fuel moisture (duff, %)      [ 50.  40.]
            Canopy consumption (%)       [ 25.]
            Shrub blackened (%)          [ 25.]
            Output units                 ['kg_ha']
        
            EMISSIONS
        
            Current scenario parameters:
        
            Parameter            Value(s)
            \--------------------------------------------------------------
        
        >>> e_obj.report()
        
        Output::
        
            EMISSIONS
            Units: lbs_ac
        
            FCCS ID: 1
            Area:    100 ac. (40.5 ha)
            Emissions factor group: 2
            SPECIES Flaming     Smoldering  Residual    TOTAL
            pm      2.77e+02    3.73e+02    7.82e+02    1.43e+03
            pm10    1.69e+02    2.54e+02    5.33e+02    9.56e+02
            pm2.5   1.47e+02    2.30e+02    4.82e+02    8.58e+02
            co      1.11e+03    3.59e+03    7.53e+03    1.22e+04
            co2     4.09e+04    2.80e+04    5.87e+04    1.28e+05
            ch4     5.31e+01    1.92e+02    4.03e+02    6.49e+02
            nmhc    6.27e+01    1.37e+02    2.88e+02    4.88e+02
        
            FCCS ID: 47
            Area:    200 ac. (80.9 ha)
            Emissions factor group: 4
            SPECIES Flaming     Smoldering  Residual    TOTAL
            pm      4.60e+02    9.69e+02    1.45e+03    2.88e+03
            pm10    2.45e+02    7.30e+02    1.09e+03    2.07e+03
            pm2.5   2.01e+02    6.81e+02    1.02e+03    1.90e+03
            co      1.11e+03    7.87e+03    1.18e+04    2.08e+04
            co2     7.24e+04    8.72e+04    1.30e+05    2.90e+05
            ch4     6.28e+01    5.08e+02    7.60e+02    1.33e+03
            nmhc    6.70e+01    3.81e+02    5.70e+02    1.02e+03
        
            ALL FUELBEDS:
            Units: lbs_ac
            Total area: 300 ac. (121.4 ha)
            pm      3.99e+02    7.70e+02    1.23e+03    2.40e+03
            pm10    9.45e+01    3.02e+01    2.14e+01    1.46e+02
            pm2.5   2.96e+01    3.08e+00    0.00e+00    3.27e+01
            co      7.81e+00    6.37e-01    0.00e+00    8.45e+00
            co2     4.02e+01    6.65e+00    0.00e+00    4.68e+01
            ch4     2.65e+01    4.93e+02    9.07e+02    1.43e+03
            nmhc    2.01e+02    2.37e+02    2.99e+02    7.36e+02
        
        
        >>> e_obj.results()['emissions']['co2']
        
        Output::
        
            {'flaming': array([ 40877.14600611,  72354.16061005]),
             'residual': array([  58664.90328723,  130457.66209735]),
             'smoldering': array([ 27980.07467362,  87193.41115534]),
             'total': array([ 127522.12396695,  290005.23386274])}
        
        
        
        -------------------------------------------
        Navigating the .results() dictionaries
        -------------------------------------------
        
        The table below depicts all categories included in the .results() dictionaries
        that are produced from the FuelConsumption and Emissions objects. Note that the
        FuelConsumption .results() dictionary does NOT include emissions data while the
        Emissions .results() dictionary includes BOTH consumption and emissions data.
        
        The FINAL index in the dictionary will be always be an integer that indicates
        the fuelbed unit in the scenario. In the example above, a [0] would access 
        data for the first fuelbed (FCCS ID #1) and a [1] would access data for the 
        second fuelbed (FCCS ID #47). Use Python's built-in 'sum()' function to
        calculate total consumption/emissions across ALL fuelbeds.
        
        
        ~~~~~~~~~~~~~
        Examples
        ~~~~~~~~~~~~~
        
        To access TOTAL consumption for the given scenario for each fuelbed unit:
        
        >>> fc_obj.results()['consumption']['summary']['total']['total']
        
        To access TOTAL consumption for only the first fuelbed unit in the scenario:
        
        >>> fc_obj.results()['consumption']['summary']['total']['total'][0]
        
        To access TOTAL consumption for the given scenario across ALL fuelbeds*:
        
        >>> sum(fc_obj.results()['consumption']['summary']['total']['total'])
        
        To access consumption data for all canopy strata:
        
        >>> fc_obj.results()['consumption']['canopy']
        
        To access TOTAL canopy consumption:
        
        >>> fc_obj.results()['consumption']['summary']['canopy']['total']
        
        To access 'co2' emissions from all combustion stages:
        
        >>> e_obj.results()['emissions']['co2']
        
        To access total 'co2' emissions for the given scenario across ALL fuelbeds*:
        
        >>> sum(e_obj.results()['emissions']['co2']['total'])
        
        To view units that the emissions data are in:
        
        >>> e_obj.results()['parameters']['units_emissions']
        
            *Note: if outputs units are per-area units (i.e. tons/acre or kg/ha), these 
            sum' functions will not provide an accurate representation of the overall
            consumption rate for the scenario.*
        
        Output::
        
            Index 1           Index 2              Index 3                     Index 4       Index 5    
            -----------------------------------------------------------------------------------------------------------------------------
        
            'parameters'   'fuel moisture: 1000hr'
                           'fuel moisture duff'
                           'fuel moisture pct canopy consumed'
                           'fuel moisture pct shrub blackened'
                           'fuelbed area'
                           'fuelbed ecoregion'
                           'fuelbed fccs id'
                           'units consumption'
                           'units emissions'
            -----------------------------------------------------------------------------------------------------------------------------
                                 
            'emissions'    'ch4'                'flaming','smoldering','residual', or 'total'
                           'co'                 'flaming','smoldering','residual', or 'total'
                           'co2'                'flaming','smoldering','residual', or 'total'
                           'nmhc'               'flaming','smoldering','residual', or 'total'
                           'pm'                 'flaming','smoldering','residual', or 'total'
                           'pm10'               'flaming','smoldering','residual', or 'total'
                           'pm25'               'flaming','smoldering','residual', or 'total'
                           
                           'stratum'            'ch4'                       'canopy'             'flaming','smoldering','residual', or 'total
                                                                            'ground fuels'       ''
                                                                            'litter-lichen-moss' ''
                                                                            'nonwoody'           ''
                                                                            'shrub'              ''
                                                                            'woody fuels'        ''
                                                'co'                        'canopy'             ''
                                                                            'ground fuels'       ''
                                                                            'litter-lichen-moss' ''
                                                                            'nonwoody'           ''
                                                                            'shrub'              ''
                                                                            'woody fuels'        ''
                                                'co2'   .....etc.....
                                                        
        
            -----------------------------------------------------------------------------------------------------------------------------
                                 
            'heat release' 'flaming'
                           'smoldering'
                           'residual'
                           'total'
        
            -----------------------------------------------------------------------------------------------------------------------------
        
            'consumption'  'summary'            'total'                     'flaming','smoldering','residual', or 'total'
                                                'canopy'                    'flaming','smoldering','residual', or 'total'
                                                'ground fuels'              'flaming','smoldering','residual', or 'total'
                                                'litter-lichen-moss'        'flaming','smoldering','residual', or 'total'
                                                'nonwoody'                  'flaming','smoldering','residual', or 'total'
                                                'shrub'                     'flaming','smoldering','residual', or 'total'
                                                'woody fuels'               'flaming','smoldering','residual', or 'total
        
                           'canopy'             'overstory'                 'flaming','smoldering','residual', or 'total'
                                                'midstory'                  'flaming','smoldering','residual', or 'total'
                                                'understory'                'flaming','smoldering','residual', or 'total'
                                                'ladder fuels'              'flaming','smoldering','residual', or 'total'
                                                'snags class 1 foliage'     'flaming','smoldering','residual', or 'total'
                                                'snags class 1 non foliage' 'flaming','smoldering','residual', or 'total'
                                                'snags class 1 wood'        'flaming','smoldering','residual', or 'total'
                                                'snags class 2'             'flaming','smoldering','residual', or 'total'
                                                'snags class 3'             'flaming','smoldering','residual', or 'total'
                
                           'ground fuels'       'duff upper'                'flaming','smoldering','residual', or 'total'
                                                'duff lower'                'flaming','smoldering','residual', or 'total'
                                                'basal accumulations'       'flaming','smoldering','residual', or 'total'
                                                'squirrel middens'          'flaming','smoldering','residual', or 'total'
        
                           'litter-lichen-moss' 'litter'                    'flaming','smoldering','residual', or 'total'
                                                'lichen'                    'flaming','smoldering','residual', or 'total'
                                                'moss'                      'flaming','smoldering','residual', or 'total'
                           'nonwoody'           'primary dead'              'flaming','smoldering','residual', or 'total'
                                                'primary live'              'flaming','smoldering','residual', or 'total'
                                                'secondary dead'            'flaming','smoldering','residual', or 'total'
                                                'secondary live'            'flaming','smoldering','residual', or 'total'
        
                           'shrub'              'primary dead'              'flaming','smoldering','residual', or 'total'
                                                'primary live'              'flaming','smoldering','residual', or 'total'
                                                'secondary dead'            'flaming','smoldering','residual', or 'total'
                                                'secondary live'            'flaming','smoldering','residual', or 'total'
                           'woody fuels'        '1-hr fuels'                'flaming','smoldering','residual', or 'total'
                                                '10-hr fuels'               'flaming','smoldering','residual', or 'total'
                                                '100-hr fuels'              'flaming','smoldering','residual', or 'total'
                                                '1000-hr fuels sound'       'flaming','smoldering','residual', or 'total'
                                                '1000-hr fuels rotten'      'flaming','smoldering','residual', or 'total'
                                                '10000-hr fuels sound'      'flaming','smoldering','residual', or 'total'
                                                '10000-hr fuels rotten'     'flaming','smoldering','residual', or 'total'
                                                '10k+-hr fuels sound'       'flaming','smoldering','residual', or 'total'
                                                '10k+-hr fuels rotten'      'flaming','smoldering','residual', or 'total'
                                                'stumps sound'              'flaming','smoldering','residual', or 'total'
                                                'stumps rotten'             'flaming','smoldering','residual', or 'total'
                                                'stumps lightered'          'flaming','smoldering','residual', or 'total'
            -----------------------------------------------------------------------------------------------------------------------------
        
        
Keywords: kml
Platform: UNKNOWN
Classifier: Programming Language :: Python
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
