pygcam.landProtection

This module supports implementation of the protect sub-command of GCAM tool (gt). It is provided in library form so that it can be used from within setup programs (or other programs) without having to execute the GCAM tool (gt) script.

See the documentation for landProtection.xml, the input file used by this subcommand.

API

class pygcam.landProtection.LandProtection(node)

Stores the application’s representation of the parsed XML file describing land protection scenarios.

Parameters:node – an lxml.etree.Element representing the top-level <landProtection> node
protectLand(infile, outfile, scenarioName, backup=True, unprotectFirst=False)

Generate a copy of infile with land protected according to scenarioName, writing the output to outfile.

Parameters:
  • infile – input file (should be one of the GCAM aglu-xml land files)
  • outfile – the file to create which represents the desired land protection
  • scenarioName – a scenario in the landProtection.xml file
  • backup – if True, create a backup outfile, with a ‘~’ appended to the name, before writing a new file.
  • unprotectFirst – (bool) if True, make all land “unprotected” before protecting.
Returns:

none
protectLandTree(tree, scenarioName)

Apply the protection scenario scenarioName to the parsed XML file tree. This interface is provided so WriteFuncs (which are passed an open XMLInputFile) can apply protection scenarios.

Parameters:
  • tree – (lxml ElementTree) a tree for a parsed XML input file.
  • scenarioName – (str) the name of the scenario to apply
Returns:

none
pygcam.landProtection.createProtected(tree, fraction, landClasses=None, otherArable=False, regions=None, unprotectFirst=False)

Modify an lxml tree representing a GCAM input file to protect a fraction of landClasses in regions.

Parameters:
  • tree – a tree representing a parsed GCAM land_input XML file
  • fraction – the fraction of land in the given land classes to protect
  • landClasses – a string or a list of strings, or None. If None, all standard unmanaged land classes are modified.
  • otherArable – (bool) if True, land class ‘OtherArableLand’ is included in default land classes.
  • regions – a string or a list of strings, or None. If None, all regions are modified.
  • unprotectFirst – (bool) if True, make all land “unprotected” before protecting.
Returns:

None
pygcam.landProtection.protectLand(infile, outfile, fraction, landClasses=None, otherArable=False, regions=None, unprotectFirst=False)

Create a copy of infile that protects a fraction of landClasses in regions.

Parameters:
  • infile – the path of a GCAM land_input XML file
  • outfile – the path of the XML file to create by modifying data from infile
  • fraction – the fraction of land in the given land classes to protect
  • landClasses – a string or a list of strings, or None. If None, all “standard” unmanaged land classes are modified.
  • otherArable – (bool) if True, land class ‘OtherArableLand’ is included in default land classes.
  • regions – a string or a list of strings, or None. If None, all regions are modified.
  • unprotectFirst – (bool) if True, make all land “unprotected” before protecting.
Returns:

None
pygcam.landProtection.protectLandTree(tree, scenarioName)

Apply the protection scenario scenarioName to the parsed XML file tree. This interface is provided so WriteFuncs (which are passed an open XMLInputFile) can apply protection scenarios.

Parameters:
  • tree – (lxml ElementTree) a tree for a parsed XML input file.
  • scenarioName – (str) the name of the scenario to apply
Returns:

none
pygcam.landProtection.runProtectionScenario(scenarioName, outputDir=None, workspace=None, scenarioFile=None, xmlFiles=None, inPlace=False, unprotectFirst=False)

Run the protection named by scenarioName, found in scenarioFile if given, or the value of config variable GCAM.LandProtectionXmlFile otherwise. The source files are take from workspace, if given, otherwise from the value of GCAM.RefWorkspace. Results are written to the given outputDir. In the even that the input and output files are the same, inPlace must be set to True to indicate that overwriting is intended. By default the two files xmlFiles, land2.xml and land3.xml in the aglu-xml directory, are processed, though other files can be specified in the unlikely case that you have alternatives.

Parameters:
  • scenarioName – (str) the name of a protection scenario defined in the scenarioFile
  • outputDir – (str) the directory under which to write the modified land files. Ignored if inPlace=True.
  • workspace – (str) the location of the workspace holding the input files (ignored if xmlFiles are specified explicitly)
  • scenarioFile – (str) the path to a protection.xml file defining scenarioName
  • xmlFiles – (list of str) the paths of the XML input files to modify
  • inPlace – (bool) if True, input and output files may be the same (output overwrites input).
  • unprotectFirst – (bool) if True, make all land “unprotected” before protecting.
Returns:

none
pygcam.landProtection.unProtectLand(tree, landClasses=None, otherArable=False, regions=None)

Restore the file to 0% land protection by adding the protected land back into its unprotected counterpart and deleting the protected elements.

Parameters:
  • tree – a tree representing a parsed GCAM land_input XML file
  • landClasses – a string or a list of strings, or None. If None, all standard unmanaged land classes are modified.
  • otherArable – (bool) if True, land class ‘OtherArableLand’ is included in default land classes.
  • regions – a string or a list of strings, or None. If None, all regions are modified.
Returns:

None