Skip to content

Land Cover Classification

Jump to bottom
donebert edited this page Jun 23, 2022 · 28 revisions

Many ATtILA for ArcGIS Pro tools require a Land Cover Classification (LCC) file as one of their input parameters. The LCC file dictates how a tool processes the input Land cover grid. It:

  • Defines the text description of land cover classes based on the raster integer value.
  • Determines the inclusion or exclusion of specific land cover classes in metric calculations (e.g. limiting calculations to only terrestrial land cover types via the exclusion of water and ice/snow classes).
  • Allows for the grouping of classes (e.g. deciduous, coniferous, and mixed forest classes may be grouped into a single "forest" class).
  • Allows for the assignment of coefficients associated with specific land cover classes to calculate coefficient-based metrics (e.g. impervious percent, nitrogen loading, and phosphorous loading).

LCC files utilize XML formatting to define these properties for an associated Land cover grid. For the user's convenience, ATtILA for ArcGIS Pro includes LCC files for some commonly-used Land cover datasets including the National Land Cover Database (NLCD), the Coast Change Analysis Program (C-CAP), and the US EPA EnviroAtlas Meter-Scale Urban Land Cover (MULC). Descriptions of the LCC files that accompany ATtILA for ArcGIS Pro are in the Supplied Land Cover Classification Schemas section of this document.

LCC files may be created or edited to allow users to customize the properties of the land cover classes to meet their objectives.

It is recommended that users create or edit LCC schema XML documents using the External LCC Editor that accompanies ATtILA for ArcGIS to reduce the possibility of introducing errors. See Create or Modify Land Cover Classification for more information on this tool. No previous experience editing XML files is necessary to edit the XML using the LCC Editor, which provides an easy-to-use interface.

LCC XML documents may also be created or edited using any standard text editor following the syntax guidelines provided in ATtILA's LCC XML Document section.

LCC XML Document Storage

The Supplied Land Cover Classification Schemas that accompany ATtILA for ArcGIS are stored in the ToolboxSource > LandCoverClassifications folder in the ATtILA for ArcGIS toolbox destination folder (see Installing ATtILA). LCC XML documents stored here automatically populate the "Land cover classification scheme" dropdown in each ATtILA tool that requires a land cover classification file (Core and Edge Metrics, Land Cover on Slopes Proportions, Land Cover Proportions, Riparian Land Cover Proportions, and Sample Point Land Cover Proportions).

Customized LCC XML documents can exist anywhere on a local or network computer. Each tool that requires an LCC XML document includes a parameter for navigating to the local or network path at which the XML file is stored. However, users may find it more convenient to access their customized LCC XML documents from the "Land cover classification scheme" dropdown in the ATtILA tools, particularly for frequently-used customized LCC XML documents. To facilitate this, store the customized XML files in the ToolboxSource > LandCoverClassifications folder as indicated above.

NOTE: It is recommended that the LCC file contain entries for all values in the input Land cover grid. However, if the LCC file does not define properties for a Land cover grid value, ATtILA for ArcGIS will alert the user by providing a warning message indicating that a value occurring in the Land cover grid was not defined in the LCC file.

ATtILA's LCC XML Document

ATtILA for ArcGIS Pro Land Cover Classification (LCC) schema documents require a precise XML structure that consists of the following:

Detailed descriptions, applications, and possible restrictions for each element are provided their respective sections in this document. The Supplied Land Cover Classification Schemas that accompany ATtILA for ArcGIS may be useful to review while reading through the following sections. What may initially appear to be complex, hard to decipher documents will become easier to interpret with the background information provided below.

Basic structure of ATtILA's Land Cover Classification schema XML document: all required elements.

<?xml version='1.0' encoding='utf-8'?>
<lccSchema xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="lcc" xsi:noNamespaceSchemaLocation="XSD_FILE_PATH">
	<metadata>
		<name></name>
		<description></description>
	</metadata>
	<coefficients>
		<coefficient Id="" Name="" fieldName="" method="" />
	</coefficients>
	<values>
		<value Id="" Name="" excluded="">
			<coefficient Id="" value="" />
		</value>
	</values>
	<classes>
		<class Id="" Name="" filter="">
			<value Id="" />
		</class>
	</classes>
</lccSchema>

It is recommended that users create or edit LCC schema XML documents using the External LCC Editor that accompanies ATtILA for ArcGIS to reduce the possibility of introducing errors. However, LCC XML documents may also be created or edited using any standard text editor and the syntax guidelines provided in each section.

Regardless of how a user chooses to create their LCC XML documents, it is strongly recommended that they first become acquainted with the details on LCC XML formatting. This will give the user a better understanding of how ATtILA for ArcGIS interacts with the land cover grid and will provide a background for understanding how ATtILA for ArcGIS may be customized for user-specific needs.

XML Fundamentals

An XML document is composed of text content marked up with tags describing the data. These tags look similar to HTML mark-up tags, but unlike HTML, the tags are customized to define what an item is (i.e., a book, a person, a telephone number, etc.) and particular attributes of each defined item (i.e. the book's title, a person's first and last name, whether the telephone number is for a home, business, or mobile device, etc.). In order for an application to correctly parse an XML document into its various pieces, the XML document must be "well-formed"; in other words, it must follow certain rules.

When using the External LCC Editor in ATtILA for ArcGIS to modify or create an LCC XML document, the resulting output document will be well-formed with regard to the ATtILA for ArcGIS application. When editing the LCC XML document with a text editor, these general XML rules must be observed:

  • Each start-tag (<tag>) must have a matching end-tag. The end-tag can be either a non-empty element, (</tag>), or an empty element (/>).
  • Attribute values must be quoted.
  • Attribute names must be unique, and XML is case-sensitive: "name" is different from "Name" which is different from "NAME".
  • Comments and processing commands cannot appear inside tags.

When editing an LCC XML document with a text editor, it is important to check the document for formatting errors and, more importantly, for any violations to the rules and restrictions ATtILA for ArcGIS places on document elements and attributes. The XML Validation section of this document provides instructions for performing these checks.

XML Declaration

Basic structure of ATtILA's Land Cover Classification schema XML document: XML declaration.

<?xml version='1.0' encoding='utf-8'?>

The first line of the LCC XML document is an XML declaration statement. It is not required, but if it is included, it must be the first line of the document. No other character or blank space can precede the declaration statement. The declaration statement allows an XML parser to obtain a basic understanding about how the text document is encoded.

Root Element: lccSchema

Basic structure of ATtILA's Land Cover Classification schema XML document: Root element (lccSchema).

<lccSchema xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="lcc" xsi:noNamespaceSchemaLocation="XSD_FILE_PATH">
    .  
    .
    .
</lccSchema>

The <lccSchema> tag is the root element of the LCC XML document. All other elements in the LCC XML document are contained within this element. XML documents are limited to one root element.

The XML root element can also contain information specific to the location and name of an XML Schema Document (XSD). The XSD document is used for validating the form and contents of the XML file. Information about the XSD document is optional.

The XSD information, if included, appears in the following form:

<lccSchema xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="lcc" xsi:noNamespaceSchemaLocation="XSD_FILE_PATH">

where XSD_FILE_PATH is the relative or absolute path of the XML schema file. When the XML file is located in the same folder as the designated XSD file, the XSD_FILE_PATH is simply the name of the XSD file.

The XSD file prepared for validating ATtILA's XML documents is named LCCSchema.xsd. It is located in the ToolboxSource > LandCoverClassifications folder in the ATtILA for ArcGIS toolbox destination folder (see Installing ATtILA).

You can include the following line as your root element if you place your custom XML document in the same folder as the XSD file:

<lccSchema xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="lcc" xsi:noNamespaceSchemaLocation="LCCSchema.xsd">

Metadata Element

Basic structure of ATtILA's Land Cover Classification schema XML document: Metadata element.

<metadata>
	<name></name>
	<description></description>
</metadata>

The Metadata element contains the name of the coding schema along with a brief description. ATtILA for ArcGIS requires the Metadata element to be present when it parses the the XML document, and it cannot be empty. The Metadata element must contain the following two elements:

  • name - text, land cover coding schema name
  • description - text, description of land cover coding schema

Example Metadata element:

<metadata>
	<name>NLCD</name>
	<description>National Land Cover Database</description>
</metadata>

The information contained in the Metadata element is for informational purposes only. It is displayed in the External LCC Editor's Metadata window, and only there. The entries for the name and description attributes can be as long or as short as the user desires.

XML Note

  • XML is case-sensitive and care should be used when editing the LCC XML documents using a text editor. Wherever possible, element and attribute names for the document have been defined using lowercase characters. The only current exceptions are the attributes "Id" and "Name" in the Coefficients, Values, and Classes elements. If editing an LCC XML document outside of the External LCC Editor, these attributes should be capitalized wherever they appear.

  • You may notice that in the Metadata element, the <name> element is lowercase. The distinction here is that "name" in the Metadata element pertains to an element, and that the capitalization rule only applies to an element's attributes.

Coefficients Element

Basic structure of ATtILA's Land Cover Classification schema XML document: Coefficients element.

<coefficients>
	<coefficient Id="" Name="" fieldName="" method="" />
</coefficients>

The Coefficients element is used to identify and to parameterize the coefficient-based metrics available in the Land Cover Coefficient Calculator tool. This element is required by ATtILA for ArcGIS to parse the LCC XML document, but it can be empty (i.e., it does not have to contain any <coefficient> elements).

NOTE: If no <coefficient> element is in the XML document when the user attempts to use the Land Cover Coefficient Calculator* tool, the tool dialog will not populate the "Report metrics for these coefficients" input box when a "Land cover classification scheme" is selected. Despite the missing information, the user is still able to click the OK button to begin the calculation run, but the run will result in an error.

If any <coefficient> element is provided, it needs to contain the following attributes:

  • Id - text, unique identifier
  • Name - text, description of coefficient metric
  • fieldName - text, name of field to be created for output
  • method - text, either "P" or "A"

Example Coefficients element with three <coefficient> elements:

<coefficients>
	<coefficient Id="IMPERVIOUS" Name="Percent Cover Total Impervious Area" fieldName="PCTIA" method="P" />
	<coefficient Id="NITROGEN" Name="Estimated Nitrogen Loading Based on Land Cover" fieldName="N_Load" method="A" />
	<coefficient Id="PHOSPHORUS" Name="Estimated Phosphorus Loading Based on Land Cover" fieldName="P_Load" method="A" />
</coefficients>

Each coefficient represented by a <coefficient> element in the LCC XML document appears in the "Report metrics for these coefficients" parameter in the Land Cover Coefficient Calculator tool dialog and is individually selectable (see below). The element's attributes are listed next to the check box as follows: Id - [fieldName] Name

Image

Id Attribute
Id is a text string of any length that supplies the short name for a coefficient. In this version of ATtILA, the text string is restricted to 'NITROGEN', 'PHOSPHORUS', or 'IMPERVIOUS'. In a future release, the user will be able to use any string for the Id attribute. See the method attribute discussion below for more details.

Name Attribute
Name is a text string of any length used to supply a more detailed description of the coefficient and/or provide additional details regarding the metrics that result from tool calculations using the coefficient. It can also be an empty string (e.g., Name="").

fieldName Attribute
fieldName is a text string used to customize the name of the coefficient in the output table field. The length of the text string is dependent on the output table type selected in the Land Cover Coefficient Calculator tool as follows:

  • dBase table - field names are restricted to 10 characters in length.
  • geodatabase table - field names are restricted to 64 characters in length.

ATtILA will truncate field names that are longer than those allowed, and check to see if the truncated field name is already in the output table. If the truncated field name already exists, the text string is truncated further to allow a numerical value to be appended to the field name to create a unique field name. When this occurs, a warning message is added to the tool's View Details box and the Geoprocessing > History window informing the user of the changes to the fieldName's text string in the output table.

In addition to size limitations, the fieldName attribute string must conform to the field naming conventions dictated by the different database systems (dBASE, INFO, or geodatabase). In general, try to restrict field names to just alphanumeric characters and underscores. Use of spaces and special characters should be avoided, as well as beginning a field name with a number or an underscore. Also, avoid using field names that contain words that are considered reserved keywords, such as date, day, month, order, table, text, user, when, where, year, and zone. For more guidelines on the naming of fields, search on "Fundamentals of adding and deleting fields" in the ArcGIS help documentation.

method Attribute
CAUTION: In this version of ATtILA, the method attribute is dummy attribute, and exists only as a placeholder.

In future releases, the method attribute will be used to pass an appropriate calculation routine for the coefficent to the Land Cover Coefficient Calculator tool. When implemented, the method element will be restricted to two choices:

  • "A" - the tool will use a "Per Unit Area" calculation routine to calculate metrics associated with the coefficient.
  • "P" - the tool will use a "Percent Area" calculation routine to calculate metrics associated with the coefficient.

More information on the different calculation routines can be found on the Land Cover Coefficient Calculator page.

XML Note

  • XML is case-sensitive and care should be used when editing the LCC XML documents using a text editor. Wherever possible, element and attribute names for the document have been defined using lowercase characters. The only current exceptions are the attributes "Id" and "Name" in the Coefficients, Values, and Classes elements. If editing an LCC XML document outside of the External LCC Editor, these attributes should be capitalized wherever they appear.

  • You may notice that in the Metadata element, the <name> element is lowercase. The distinction here is that "name" in the Metadata element pertains to an element, and that the capitalization rule only applies to an element's attributes.

Values Element

Basic structure of ATtILA's Land Cover Classification schema XML document: Values element

<values>
	<value Id="" Name="" excluded="">
		<coefficient Id="" value="" />
	</value>
</values>

The Values element defines the set of values that can exist in a land cover raster. This element is required by ATtILA for ArcGIS to parse the XML document, but it can be empty (i.e., it does not have to contain any <value> elements). Value elements are only necessary in two cases:

  1. if the user wants to exclude the area occupied by a given grid value when determining a reporting unit's effective area (e.g., basing metric calculations on the land area in a reporting unit vs. the total area of the reporting unit), or
  2. if the user is planning to calculate any metrics with the Land Cover Coefficient Calculator. In this case <value> elements should be added where coefficient weights are known (e.g., the nitrogen loading coefficient for a particular agriculture type).

NOTE: Although values are not necessary in the XML document, if one is using the LCC Editor to construct an LCC XML document, you will be required to have value elements defined in order to assign values to a class element (see Classes Element*).*

If any <value> element is provided, it must have the Id attribute. The attributes, Name and excluded, are allowed, but are not necessary. Properties for the <value> element attributes are:

  • Id - integer
  • Name - text (optional, can be the empty string, "")
  • excluded - boolean (optional, "true" or "false" or "1" or "0")

Example Values element with two <value> elements:

<values> 
    <value Id="11" Name="Open Water" excluded="true" />
	<value Id="41" Name="Deciduous Forest" />
</values>

Id Attribute
Id is an integer value representing a grid code that may be found in a land cover raster. Values included in the LCC XML document can span the range of expected values of a particular land cover dataset (e.g., NLCD, C-CAP, MULC), but all of the values provided in the document do not have to exist in the actual land cover layer. This is often the case when a national-level land cover coding schema is selected by the user, but the input land cover raster has been clipped to a regional study area.

A potentially more important issue is when all the values located in a land cover raster are not accounted for in the LCC XML document. ATtILA for ArcGIS will examine all of the values provided in the LCC XML document from both the Values section of the document and those provided in the Classes Element section and compare them to those found in the land cover raster. Any values in the grid not found in the LCC XML document will be reported to the user with a warning message in the tool's View Details box and the Geoprocessing > History window. The user can then determine if the reported values were accidentally omitted from the LCC XML document or incorrectly recorded. A report of missing values may also indicate that the wrong LCC Schema was selected for the input raster layer, or that the wrong raster layer was input for the selected LCC Schema.

Name Attribute (optional)
Name is a text string of any length used to supply a more detailed description of the grid code and/or provide other useful information regarding the value. The Name attribute may be an empty string (e.g., Name="").

excluded Attribute (optional)
The attribute, excluded, is used to identify grid codes whose area is to be excluded from the reporting unit's effective area calculation. Effective area can be thought of as the area of interest within a reporting unit that the user wishes to use for percentage based metric calculations. For example, the user may be interested in basing their metric calculations on just the land area in a reporting unit versus the overall total area of the reporting unit. To make the effective area equal to that of the land area, the user would set the excluded attribute of any water related grid value to "true".

The default setting for the excluded attribute is excluded="false" (i.e., if no excluded attribute is provided in the <value> element, the area associated with that grid value is not excluded from the reporting unit's effective area calculation). When all excluded attributes are tagged as 'false', the effective area is equal to the total overall area of the reporting unit.

*CAUTION: any value tagged as excluded = "true", should not be used in any <class> element definition within the LCC XML document. The <class> element is discussed in the Classes Element* section.


VALUE ELEMENTS WITH COEFFICIENT ELEMENTS

A Value element can also contain one or more Coefficient elements. These Coefficient elements are optional unless the user is planning on generating metrics using the Land Cover Coefficient Calculator tool. See the caution note below for more specifics on when <coefficient> elements must be supplied. If any <coefficient> element is provided, it needs to contain the following attributes:

  • Id - text (Either 'NITROGEN', 'PHOSPHORUS', or 'IMPERVIOUS').
  • value - decimal

Example Values element with one <value> element with two <coefficient> elements:

<coefficients>
	<coefficient Id="NITROGEN" Name="Estimated Nitrogen Loading Based on Land Cover" apField="A" fieldName="N_Load" />
	<coefficient Id="PHOSPHORUS" Name="Estimated Phosphorus Loading Based on Land Cover" apField="" fieldName="P_Load" />
</coefficients>

<values>
	<value Id="41" Name="Deciduous Forest">
		<coefficient Id="NITROGEN" value="2.447" />
		<coefficient Id="PHOSPHORUS" value="0.089" />
	</value>
</values>

Coefficient Element: Id Attribute
Id is a text string used to reference a <coefficient> element within the LCC XML document's Coefficients Element section. This text string needs to match the Id attribute for that <coefficient> element exactly. At present, the text string for this attribute is restricted to equal either 'NITROGEN', 'PHOSPHORUS', or 'IMPERVIOUS'. In future releases of ATtILA, we plan to allow the user to use any string for the this element's Id attribute as long as it matches an Id attribute found in a corresponding <coefficient> element. See the discussion on the attribute, method, in Coefficients Element for more details on this.

Coefficient Element: value Attribute
The attribute value is a decimal number representing the coefficient weighting factor assigned to a land cover/land use type. Values for NITROGEN and PHOSPHOROUS should be given in kg per hectare per year. Values for IMPERVIOUS should represent percentages.

CAUTION: For any coefficient-based metric the user selects to calculate when running the Land Cover Coefficient Calculator tool, that coefficient <element> must be present in all of the <value> elements provided in the <values> element. Not all values in the input land cover raster need to be accounted for in the LCC XML document when using the Land Cover Coefficient Calculator tool, but if a value is included, its <value> element must contain the corresponding <coefficient> element for the desired metric.

XML Note>

  • XML is case-sensitive and care should be used when editing the LCC XML documents using a text editor. Wherever possible, element and attribute names for the document have been defined using lowercase characters. The only current exceptions are the attributes "Id" and "Name" in the Coefficients, Values, and Classes elements. If editing an LCC XML document outside of the External LCC Editor, these attributes should be capitalized wherever they appear.

  • You may notice that in the Metadata element, the <name> element is lowercase. The distinction here is that "name" in the Metadata element pertains to an element, and that the capitalization rule only applies to an element's attributes.

Classes Element

Basic structure of ATtILA's Land Cover Classification schema XML document: Classes element.

<classes>
	<class Id="" Name="" filter="">
		<value Id="" />
	</class>
</classes>

The <classes> element contains values from a land cover raster grouped into one or more <class> elements. The <classes> element is required by ATtILA for ArcGIS to parse the XML document, and it must contain at least one <class> element. Any provided <class> element needs to contain an Id attribute. The attributes, Name, filter, and xxxField (where xxxx equals a tool name abbreviation), are allowed, but are not necessary. Properties for the <class> element attributes are:

  • Id - text, unique identifier

  • Name - text (optional, can be the empty string, "")

  • filter - text, a string of one or more tool name abbreviations (caem, flcp, flcv, lcosp, lcp, np, plcv, pm, rlcp, or splcp) separated by a ";" (optional, can be the empty string, "")

  • xxxxField - text, where xxxx equals a tool name abbreviation (flcp, lcosp, lcp, rlcp, or splcp). A separate xxxxField attribute can exist for each tool (optional, can be the empty string, "")

A <class> element can contain either <value> elements or additional <class> elements but not both types. A <class> element contained within another <class> element is known as a child class. The containing <class> element is the parent class. A <value> element within a <class> element has only one attribute:

  • Id - integer, corresponds to a land cover/land use grid value

Example Classes element with one <class> element:

<classes>
	<class Id="nat" Name="All natural land use" filter="" lcpField="NINDEX">
		<value Id="41" />
		<value Id="42" />
		<value Id="43" />
		<value Id="51" />
		<value Id="52" />
	</class>
</classes>

Example Classes element with one parent <class> element and two child classes:

<classes>
	<class Id="nat" Name="All natural land use" lcpField="NINDEX">
		<class Id="for" Name="Forest">
			<value Id="41" />
			<value Id="42" />
			<value Id="43" />
		</class>
		<class Id="shrb" Name="Shrubland">
			<value Id="51" />
			<value Id="52" />
		</class>
	</class>
</classes>

NOTE: When a <class> element (parent class) has additional <class> elements nested within it (child classes), the <value> elements from all child classes are combined to define the parent class. For example, if a class, "nat", contains two classes, "for" and "shrb", and "for" is comprised of values 41, 42, and 43 and "shrb" is defined as values 51 and 52, "nat" would be defined as having values 41, 42, 43, 51, and 52.

NOTE: Empty <class> elements are ignored by ATtILA for ArcGIS.

NOTE: if a value is marked as excluded = "true" in the Values Element section, but is included in a class definition, ATtILA for ArcGIS will ignore the area of that excluded value when summing up the area of the selected class for metric calculations. If all values assigned to the class are tagged as excluded, the output metric is calculated as 0%.

Each <class> element in the LCC XML document will appear as a selectable metric in the "Report metrics for these classes" or the "Generate output for these classes" input parameter area for tools that utilize the LCC XML document (i.e., caem, flcp, flcv, lcosp, lcp, np, plcv, pm, rlcp, and splcp). An example for lcp is shown below using the supplied land cover classification schema, NLCD LAND.

Image

In the above example, the <class> element's attributes are listed next to its check box in the following order and format:

  • Id - [xxxxField or auto-generated field name] Name

Id Attribute
Id is a text string used to identify the defined set of raster grid values as a group (i.e., class) for analysis. In addition, the class Id attribute is used as a base to auto-generate output metric field names when no xxxxField class attribute is provided (see below) or if the xxxxField attribute is an empty string. Each ATtILA for ArcGIS tool has a predefined prefix and/or suffix which it will use in conjunction with the Id attribute string to auto-generate field names. See the help section for each individual tool (caem, flcp, flcv, lcosp, lcp, np, plcv, pm, rlcp, and splcp) to learn more.

xxxxField Attribute (optional)
The attribute, xxxxField, where xxxx equals a tool name abbreviation, is a text string used as the default output field name. Only the tools flcp, lcosp, lcp, rlcp, and splcp can make use of the xxxxField attribute. If no xxxxField attribute is provided or if the xxxxField attribute contains an empty string, ATtILA for ArcGIS will auto-generate an output field name using the class Id attribute as a base (see above). A separate xxxxField attribute can exist in the <class> element for each applicable tool (e.g., <class Id="nat" Name="All natural land use" filter="" lcpField="NINDEX" rlcpField="RNatural">).

CAUTION: The Id attribute, if used for output field naming, or the xxxxField attribute, if provided, must be unique among the different <class> elements or identical field names can be generated between classes. If duplicate field names are present, only one is added to the output table. During metric runs, all previous values calculated for that field will be overwritten by the last metric processed with the duplicate field name.

CAUTION: Field name size is limited by the Output table type: dBASE table field names can be 10 characters in length, and File Geodatabase table field names can be 64 characters in length.

  • For xxxxField attribute strings: ATtILA for ArcGIS will truncate strings that are longer than those allowed, and check to see if the truncated field name is already in the output table. If the truncated field name already exists, the text string will be truncated further to allow a numerical value to be appended to the field name to create a unique entity. A warning message will then be added to the tool's View Details box and the Geoprocessing > History window informing the user of what the provided xxxxField attribute text string was changed to for the output table.
  • For auto-generated field names: If the auto-generated field name is longer than what is allowed, ATtILA for ArcGIS will truncate the field name base (i.e., the class Id attribute string), keeping the metric's predefined prefix and/or suffix intact, to shorten the field name. If the truncated field name already exists in the output table, the base string will be truncated further to allow a numerical value to be appended to it to create a unique entity. A warning message will then be added to the tool's View Details box and the Geoprocessing > History window informing the user of what the auto-generated field name was changed to before adding it to the output table.

CAUTION: In addition to size limitations, the Id attribute, if used for output field naming, or the xxxxField attribute, if provided, must conform to the field naming conventions dictated by the different database systems (dBASE, INFO, or geodatabase). In general, try to restrict field names to just alphanumeric characters and underscores. Use of spaces and special characters should be avoided, as well as beginning a field name with a number or an underscore. Also, avoid using field names that contain words that are considered reserved keywords, such as date, day, month, order, table, text, user, when, where, year, and zone. For more guidelines on the naming of fields, search on "Fundamentals of adding and deleting fields" in the ArcGIS help documentation.

CAUTION: If an invalid field name is provided in the xxxxField attribute, such as a string of spaces, the metric run will fail during execution, and an "Invalid field name" error message will appear in the tool's View Details box and the Geoprocessing > History window.

Name Attribute (optional)
Name, is a text string of any length used to supply a more detailed description of the class and/or provide other useful information regarding it. The Name attribute may be an empty string (e.g., Name=""). The Name attribute is not used in metric calculations or output field naming routines.

filter Attribute (optional)
The filter attribute is a string of one or more tool name abbreviations (caem, flcp, flcv, lcosp, lcp, np, plcv, pm, rlcp, or splcp) separated by a semi-colon. It is used to exclude a class from a tool's list of selectable classes in the "Report metrics for these classes" or the "Generate output for these classes" input parameter area. This can be done to reduce clutter within a tool's GUI (e.g., dropping all classes except those related to agriculture for the Land Cover on Slopes Proportions tool) or to prevent classes incongruous for the analysis from being selected (e.g., <class Id="wetl" Name="All wetland land cover" filter="lcosp"> will eliminate the wetl class from the Land Cover on Slopes Proportions tool).

Value element: Id Attribute
The <value> element attribute, Id, is an integer value representing a grid code that may be found in a land cover raster. Groupings of <value> elements within a <class> element is dictated solely by the research needs of the user.

XML Note

  • XML is case-sensitive and care should be used when editing the LCC XML documents using a text editor. Wherever possible, element and attribute names for the document have been defined using lowercase characters. The only current exceptions are the attributes "Id" and "Name" in the Coefficients, Values, and Classes elements. If editing an LCC XML document outside of the External LCC Editor, these attributes should be capitalized wherever they appear.

  • You may notice that in the Metadata element, the <name> element is lowercase. The distinction here is that "name" in the Metadata element pertains to an element, and that the capitalization rule only applies to an element's attributes.

Comments (optional)

XML documents can contain commented characters for notes and brief descriptions of sections. Comments are delimited by <!-- and end with the first occurrence of -->.

The Supplied Land Cover Classification schemas that come with ATtILA for ArcGIS come with a standardized set of comments (see below). They provide information to the user regarding the contents of the following elements: <coefficients>, <values>, and <classes>. These standardized comments are also inserted when LCC XML documents are created with the External LCC Editor. Although comments are supplied by the program, they are unnecessary for the functioning of the XML document, and can be deleted. Any LCC XML document created by the user outside of the External LCC Editor can omit comments.

<\!--
	* The coefficients node contains coefficients to be assigned to values.

	* REQUIRED ATTRIBUTES
	* Id - text, unique identifier
	* Name - text, word or phrase describing coefficient
	* fieldName - text, name of field to be created for output
	*	- must conform to the field naming conventions dictated by the output database system
	* apMethod - text, "P" or "A", designates "P"ercentage or per unit "A"rea calculation routine
--\>

<\!-- 
	* The values node defines the full set of values that can exist in a land cover raster.
	* REQUIRED ATTRIBUTES
	* Id - integer, raster code
	* 
	* OPTIONAL ATTRIBUTES
	* Name - text, word or phrase describing value
	* excluded - boolean, "true" or "false" or "1" or "0"
	*	- used to exclude values from effective area calculations
	*	- excluded=false is the default
	
	* A value element can optionally contain one or more coefficient elements
	
	* REQUIRED COEFFICIENT ATTRIBUTES
	* Id - text, must match an Id attribute from a coefficients node element
	* value - decimal, weighting/calculation factor
--\>

<\!--
	* The classes node contains values from a land cover raster grouped into one or more classes.
	
	* REQUIRED ATTRIBUTES
	* Id - text, unique identifier, also used for automated generation of output field name
	*	- must conform to the field naming conventions dictated by the output database system
	
	* OPTIONAL ATTRIBUTES
	* Name - text, word or phrase describing class
	* filter - text, a string of one or more tool name abbreviations separated by a ";"
	*	- possible abbreviations are: caem, flcp, flcv, lcosp, lcp, np, plcv, pm, rlcp, and splcp
	*	- used to exclude the class from the selectable classes in the tool's GUI
	* xxxxField - text, overrides ATtILA-generated field name for output
	*	- where xxxx equals a tool name abbreviation
	*	- possible abbreviations are: flcp, lcosp, lcp, rlcp, and splcp
	*	- a separate xxxxField attribute can exist for each tool
	*	- must conform to the field naming conventions dictated by the output database system
	
	* A class can contain either values or classes but not both types.
	* Value elements contain only an Id attribute which refers to a value in a raster.
	* Values tagged as excluded="true" in the values node should not be included in any class. 
--\>

XML Validation

Table of contents

Clone this wiki locally