IAN - a raster image analysis tool Introduction IAN generates reports from the statistical analysis of raster images. It is programmed in the open source scripting language Ruby enabling technically savvy users and the developers to easily extend the program. The existing framework is designed to easily support additional metrics, reports, image file formats, options, and units. The flexible architecture of IAN streamlines the process of new releases. IAN runs on all 32-bit Windows platforms. It comes with two user interfaces - a user friendly windowing user interface (IAN) and a command line user interface (IANC) for console and programmatic access. If you have any questions about IAN you can contact us at ian-mail@mailplus.wisc.edu. History IAN was developed at the Forest Landscape Ecology Lab, Department of Forest Ecology and Management, University of Wisconsin-Madison. IAN grew from the same concept that gave birth to APACK and FRAGSTATS in the landscape ecology arena. But IAN can be used in any discipline that requires image analysis. As IAN grows its metric set can come from a variety of fields. IAN was first released in August of 2004. Benefits of IAN over APACK (and FRAGSTATS) - User friendly GUI - Extensive online help - Easy to use Install program - Many images can be processed at one time - Reads Windows BMP files as input allowing images from nearly any application to be analyzed - Excel-compatible output format - Multiple text report formats - Support for many more unit types (foot, acre, furlong, angstrom, etc.) - Support for many image formats (1 bit, 4 bit, 8 bit, 16 bit, 24 bit) - The command line version supports long file names and long unit names. In other words spaces are okay in the command line version - Slowest APACK metrics removed - Extensible by user Downloading IAN In order to download IAN, you need to register first at our registration page, after which the download process will begin automatically. Installing IAN Prerequisites IAN is written in Ruby. Therefore you need a Ruby interpreter installed before you can run IAN. Getting Ruby The standard Ruby distribution can be found at RubyForge's website: http://rubyinstaller.rubyforge.org/wiki/wiki.pl. Download version 1.8.1 or later. Do not download any version that ends in "_rc<num>" as this denotes a Release Candidate release and not an official stable release. Installing Ruby Run the EXE you’ve downloaded from RubyForge. This will install the interpreter, all necessary libraries, and will put the interpreter on your path. IMPORTANT: If the interpreter is not on your path IAN will not work correctly. After installation of IAN if you have difficulty getting IAN to run verify that the Ruby interpreter is on your path. To do so open a Command Prompt window and type "ruby -v". If Ruby is on your path you should get a version string back. If it is not on your path you must put it there through the Control Panel :: System :: Advanced :: Environmental Variables. If Ruby was installed in c:\ruby you would specify c:\ruby\bin as an additional search path. Unzipping IAN Take the ZIP file you’ve downloaded from this site and unzip it to a directory (i.e. c:\InstIan). To unzip the ZIP file use a program such as WinZip or PkZip/Unzip. If you are using the latest version of Windows you can use the ZIP support built directly into Explorer. Running IAN's install program From Windows’ Start Menu choose Run, browse to the directory you created and select install.rb. Choose OK to begin installation. Follow the prompts to complete the installation process. Adding IAN's directory to the path (optional) It is recommended that you add IAN to your path. This can be done by selecting Control Panel :: System from within Windows (or My Computer :: Properties). Choose the Advanced tab and select the Enviromental Variables button. Use the bottom window of the dialog to edit the Path environmental variable. Add a semicolon immediately followed by the full path to where you installed IAN. For example, IAN may have been unzipped to c:\IanInst and then through the install program it may have been installed in c:\Ian. Let's says the existing path is c:\windows. Edit the new path to look like c:\windows;c:\Ian. Clean up You may now remove the directory where you unzipped IAN to (i.e. C:\InstIan). You are now ready to use IAN. Running IAN: The windowed UI The windowed version of IAN is named IAN.BAT and lives in the directory you installed IAN in. By invoking this batch file the windowed user interface will be launched. IAN launches a command prompt window in order to interpret its code to launch the UI. If this command window is bothersome it can be bypassed by creating a Windows shortcut whose command line is <ianpath>\winui.rbw (e.g. c:\Ian\winui.rbw). Once you’ve started IAN read the online help to learn how to use it. Running IAN: The command line UI The command line version of IAN is named IANC.BAT and lives in the directory you installed IAN in. By invoking this batch file the command line user interface will be launched. Open a Command Prompt Window and type IANC –h to get access to the online help. IAN Functionality Options (command line UI only - windowed version has equivalent functionality) -H,-? Use to get online help. If used alone ("IANC -h") a general overview of IANC’s command line syntax is given. Otherwise item specific help is given on the items that follow –H on the command line. For example, to get help on the ASC file format type “IANC –h iasc”. -B Specify the background color of the input image(s) on the command line. Correct use of –B includes a color as an argument (e.g. –B(100)). The color can be specified in decimal (e.g. –B(5)), binary (leading 0b e.g. –B(0b1111)), octal (leading 0 e.g. –B(014)), and hexadecimal (leading 0x e.g. –B(0xff0000)). -N Specify the number of neighbors each cell has. Correct use of –N includes a number (either 4 or 8) as an argument (e.g.–N(4)). This affects how polygons borders and cell adjacencies are calculated. -UA Specify the areal unit of the input image(s) on the command line. Correct use of –UA includes an optional measure (and tilde) followed by an areal unit name (e.g. –UA(100.0~sq. m)). The unit type must be area. The name can be singular, plural, or abbreviated and can contain spaces. -UD Specify the distance unit of the input image(s) on the command line. Correct use of –UD includes an optional measure (and tilde) followed by a distance unit name (e.g. –UD(30.0~m)). The unit type must be distance. The name can be singular, plural, or abbreviated and can contain spaces. -A,-AALL Select all analyses. When used in conjunction with –H this will report help on all analyses installed on the system. Otherwise all analyses installed on the system will be run on the image(s) listed on the command line. -IALL Select all image types. When used in conjunction with –H this will report help on all image types supported by the system. -OALL Select all options. When used in conjunction with –H this will report help on all options installed in the system. -RALL Select all reports. When used in conjunction with –H this will report help on all reports supported by the system. Analyses For a comprehensive summary of analyses please read below Image File Formats ASC - IAN's (and APACK's) ASCII file format This file format is documented below BMP - Windows BMP file format This file format is documented in the Microsoft Windows Knowledge Base GIS - ERDAS 7.4 compatible GIS file format This file format is documented in the ERDAS Field Guide LAN - ERDAS 7.4 compatible LAN file format This file format is documented in the ERDAS Field Guide Reports CSV - Comma Separated Values (Excel compatible) TXT - Text format (metrics grouped by metric) TX2 - Text format (metrics grouped by class) Extending IAN Please read how to extend IAN below IAN's and APACK's ASCII image file format IAN and APACK define and support a case insensitive ASCII image file format. An well defined ASCII image file is comprised of sections of user specified data. In general the ASCII image file format definition supports free layout of sections. Sections can appear in any order and not all sections are required. Sections can be separated by additional whitespace (or blank lines) if desired. Any deviations from these conventions are noted below. A minimal ASCII image file includes three sections: the rows section, the columns section, and the cells section. These sections are each described below. ASCII image files can be embellished with additional information such as a legend, a title, measurement units, and comments. Comments start with the two character sequence �//�. All text following the two character sequence �//� to the end of line is ignored. Columns section The number of columns in the image file is specified in the columns section of the ASCII image. This section is a required element of any ASCII image file. The columns section starts with the string �[columns]� on its own line. The number of columns is then specified on the following line. The specification of the columns section in the ASCII image file must precede the cells section. Rows section The number of rows in the image file is specified in the rows section of the ASCII image. This section is a required element of any ASCII image file. The rows section starts with the string �[rows]� on its own line. The number of rows is then specified on the following line. The specification of the rows section in the ASCII image file must precede the cells section. Cells section The actual cell data in the image file is specified in the cells section of the ASCII image. This section is a required element of any ASCII image file. It must not precede the rows section or the columns section. The cells section starts with the string �[cells]� on its own line. Then starting on the next line each cell value is specified separated by spaces and/or carriage returns. There should be exactly as many cell values listed as there are rows and columns specified. APACK reads cell values one complete row at a time from top to bottom. So the first cell value entry is mapped to row 1 and column 1 and pertains to the upper left corner of an image. The second cell value entry is mapped to row 1 and column 2. Title section The title of the image file is specified in the title section of the ASCII image. Including this section in the definition of an ASCII image file is optional. The title section starts with the string �[title]� on its own line. Then starting on the next line the title string is specified. The case of the title string is maintained. Legend section The legend of the image file is specified in the legend section of the ASCII image. Including this section in the definition of an ASCII image file is optional. The legend section starts with the string �[legend]� on its own line. Then the following lines contain a cell value followed by a legend string. Legend items can specified in any order desired and there is no need to specify all of them. Simply specify those that are of interest. The cell value specified pertains to the cell value associated with the legend string. The cell values must be <= 16 million. The case of the legend strings are maintained. Cell spacing section The cell spacing of the image file is specified in the cell spacing section of the ASCII image. Including this section in the definition of an ASCII image file is optional. The cell spacing section starts with the string �[cell spacing]� on its own line. Then starting on the next line a number followed by a unit name is specified. The number specified represents the number of units between cells and must be greater than zero. The unit name specified represents the unit and must be a distance unit. In APACK the unit must be one of �m�, �km�, �ft�, �yd�, or �mi�. IAN has a much larger set of distance units. Simply specify the name or abbreviation of your distance unit. If it is not found in IAN�s unit database it is not difficult to add to IAN. An example test image follows: // Example ASCII text image file // [title] Example text image for IAN and APACK [rows] 4 [columns] 4 [cells] 1 1 2 2 // row 1 1 5 5 2 // row 2 4 5 5 3 4 4 3 3 // last row [legend] 1 water 2 marsh 3 scrub 4 conifer 5 deciduous 0 background [cell spacing] 28.5 m // // End example ASCII text image file Extending IAN Programming Ruby If you would like to extend IAN first you will need to learn how to program in Ruby. Ruby is a very useful scripting language that you can use for many projects other than IAN. A good web introduction to Ruby can be found at http://www.rubycentral.com/book/. Its based upon the most popular print introduction to Ruby: “Programming Ruby – The Pragmatic Programmmer’s Guide”. To make an extension to IAN you need only learn the basics of the language. The basic templates of the extensions are outlined below and class descriptions are compiled in a library description. How to create an extension Adding a new analysis Analyses live in the ANALYSES subdirectory under IAN’s install directory. Any analysis you make must be placed there. Look at the analyses present in IAN for ideas on how to do things. Your analysis class must be named Analysis and must take the following format: class Analysis def initialize(engine,options,image,distUnit,areaUnit,args) # Only record initialization information here. Do actual initialization at the beginning of run method. This ensures that help # will work correctly. # engine is the Engine from the class library that is calling this Analysis. You should remember its reference so you can # interact with the user interface. # options is an OptionList containing all command line options and their values as OptionSummaries # image is an ImageInstance associated with the image to be analyzed # distUnit is the distance Unit the output should be reported in # areaUnit is the area Unit the output should be reported in # args is an Array of Strings representing the arguments to the Analysis specified on the command line. For instance the # Analysis may be invoked on the command line like this: AAR(1,2,3). end def help(verbose) # verbose is a flag (true or false) specifying whether verbose help or brief help is desired. Brief help is at most one line. # return an Array of Strings describing the Analysis end def run # return an Array of one or more output summaries (library class OutputSummary) # use the information from initialize to run your Analysis end def name # a String identifying the Analysis end def outType # a flag specifying the types of the metrics reported by this analysis. It can be any combination of AnalysisType::IMAGE, # AnalysisType::CLASS, and AnalysisType::INTERCLASS end end Your Analysis can have additional methods if desired. It will become instantly available to both the command line version and the windowed version of IAN. Adding a new report ReportWriters live in the REPORTS subdirectory under IAN’s install directory. Any report you make must be placed there. Look at the reports present in IAN for ideas on how to do things. Your report class must be named ReportWriter and must take the following format: class ReportWriter def outName # a String whose value is the file name of the report being written end def run(engine,options,image,analysesOutput,args,verbose) # engine is the Engine from the class library that is calling this ReportWriter. You should remember its reference so you can # interact with the user interface. # options is an OptionList containing all command line options and their values as OptionSummaries # image is an ImageInstance associated with the image to be analyzed # analysesOutput is an Array of OutputSummaries. It’s the output from all of the analyses that have been run. # args is an Array of Strings representing the arguments to the ReportWriter specified on the command line. For instance # the ReportWriter may be invoked on the command line like this: RTXT(c:\fred.out). # verbose is a flag (true or false) specifying whether verbose output or brief output is desired. end def help(verbose) # verbose is a flag (true or false) specifying whether verbose help or brief help is desired. Brief help is at most one line. # return an Array of Strings describing the ReportWriter end end Adding a new option Options live in the OPTIONS subdirectory under IAN’s install directory. Any option you make must be placed there. Look at the options present in IAN for ideas on how to do things. Your option class must be named Option and must take the following format: class Option def help(verbose) # verbose is a flag (true or false) specifying whether verbose help or brief help is desired. Brief help is at most one line. # return an Array of Strings describing the Option end def name # a String used to identify the Option internally. For example, “Background”. end end Your Option can have additional methods if desired. Your Option will automatically be available to the command line version of IAN. You can write additional analyses or modify existing analyses to use the value of your Option. Adding a new image file format ImageConverters live in the IMAGETYPES subdirectory under IAN’s install directory. Any image converter you make must be placed there. Look at the image converters present in IAN for ideas on how to do things. Your converter class must be named ImageConverter and must take the following format: class ImageConverter def name # a String identifying the ImageConverter end def help(verbose) # verbose is a flag (true or false) specifying whether verbose help or brief help is desired. Brief help is at most one line. # return an Array of Strings describing the ImageConverter end def readImage(engine,imageArgs,imageInstance) # engine is the Engine from the class library that is calling this ImageConverter. You should remember its reference so you # can interact with the user interface. # imageArgs is an Array of Strings. If one is present it is the filename of the image being read. If two are present the first # argument is the path and the second argument is the filename of the image being read. # imageInstance is the ImageInstance associated with the image to be read. # The ImageConverter will need to call the ImageInstance’s makeNewImage() method before reading into any new image. # The ImageConverter needs to set the imageInstance’s filename when reading the file. Use imageInstance.fileName= end def writeImage(engine,imageArgs,imageInstance) # currently IAN does not use this functionality but requires a stub definition of it for future expansion end end Your ImageConverter can have additional methods if desired. Your ImageConverter will automatically be available to both the command line version and the windowed version of IAN. Name your ImageConverter based upon the extension of files of that image type. For instance an ImageConverter designed to read PNG files should be defined in the file PNG.RB. Adding a new unit type Unit definitions are stored in units.dat, a file present in the directory where IAN is installed. That file describes how to add units to IAN. IAN’s Class Library Analysis Documented above. Array See Ruby’s definition of Array for information on available methods, etc. BinaryReader new(file) Creates a new BinaryReader on file. File must already be open and in binmode. See Ruby’s File help for more information. readString(optionalLength) Returns a string. If the optional length is given the string will be exactly that many characters wide. Otherwise the string read is determined by the next NULL character (0x0) found. readByte Returns the next byte in the file as an Integer (range 0-255) readInt16 Returns the next two bytes as a little endian Integer (range -32768-32767) readUInt16 Returns the next two bytes as a little endian Integer (range 0-65535) readInt32 Returns the next four bytes as a little endian Integer (range -2147483648-2147483647) readUInt32 Returns the next four bytes as a little endian Integer (range 0-4294967295) readFloat32 Returns the next four bytes as a Float from 32 bit IEEE format readFloat64 Returns the next eight bytes as a Float from 64 bit IEEE format BinaryWriter new(file) Creates a new BinaryWriter on file. File must already be open and in binmode. See Ruby’s File help for more information. writeByte(int) Write the passed in Integer (range 0-255) as a byte to the associated file writeInt16(int) Write the passed in Integer (range -32768-32767) as a little endian 2 byte signed integer to the associated file writeUInt16(int) Write the passed in Integer (range 0-65535) as a little endian 2 byte unsigned integer to the associated file writeInt32(int) Write the passed in Integer (range -2147483648-2147483647) as a little endian 4 byte signed integer to the associated file writeUInt32(int) Write the passed in Integer (range 0-4294967295) as a little endian 4 byte unsigned integer to the associated file writeFloat32(float) Write the passed in Float as an IEEE compliant 4 byte float to the associated file writeFloat64(float) Write the passed in Float as an IEEE compliant 8 byte float to the associated file writeChars(string) Write the characters in string to the associated file. Do not terminate with a NULL char (0x0). writeCString(string) Write the characters in string to the associated file. Terminate with a NULL char (0x0). Engine The Engine has three methods that are of interest to those extending IAN. They are statement(text), warning(text), and error(text). Each takes a text String as input and updates the UI accordingly. Error(text) terminates current processing. Float This class is used to report AnalysisType::IMAGE metric output. See Ruby’s definition of Float for information on available methods, etc. Hash This class is used to report AnalysisType::CLASS metric output. See Ruby’s definition of Hash for information on available methods, etc. ImageConverter Documented above. ImageFile An ImageFile represents the actual pixel data of an ImageInstance. It has many methods for accessing the data in an image. An ImageFile pixel is encoded in a 32 bit integer. The layout of bits in the integer differ based upon the number of bits per pixel the image has. Bit layouts Msb 00000000 Lsb (4 bits per digit) 1 bit: 00000000 or 00000001 4 bit: 00000000 through 0000000f 8 bit: 00000000 through 000000ff 16 bit: 00000000 through 0x0000ffff 24 bit: 00rrggbb specify(rows,cols) Initialize the ImageFile to have a rows x cols pixel image. Initially all zeroes. rows Report the number of rows in the image. cols Report the number of columns in the image. getCell(x,y) Get the pixel associated with coordinate (x,y) where x = row and y = column. When accessing pixels its important to note that IAN stores images with the origin at the lower left corner. setCell(x,y,value) Set the pixel associated with coordinate (x,y) where x = row and y = column to value. Care must be taken to encode the pixel correctly. See Bit Layouts above. When accessing pixels its important to note that IAN stores images with the origin at the lower left corner. classesPresent Returns a count of the number of classes present in the image legend Returns a reference to a Hash that holds the mapping of pixel values to legend names. palette Returns a reference to a Hash that holds the mapping of pixel values to 00rrggbb formatted pixels. Not present for all ImageFiles due to differing input file formats. title Get the optional title (as a String) that is associated with the image title=string Set the optional title associated with the image from the input String each (code block that takes one parameter: |pixel|) Apply the passed in code block to each pixel in the image each5(code block that takes five parameters: |center, north, south, east, west|) Apply the passed in code block to each four neighbor combination in the image. Note that some pixels do not have the full complement of neighbors (for instance, the upper left corner pixel does not have a northern or western neighbor). In such cases the neighbor value will be nil. each9(code block that takes nine parameters: |ctr, nw, n, ne, w, e, sw,s,se|) Apply the passed in code block to each eight neighbor combination in the image. Note that some pixels do not have the full complement of neighbors (for instance, the upper left corner pixel does not have a northern, western, or northwestern neighbor). In such cases the neighbor value will be nil. polyCount(eightNeighbors) Returns the count of all polygons in the image. eightNeighbors is a Boolean (true or false) specifying whether to consider 4 neighbors per pixel or eight. polyAreas(eightNeighbors) Returns an Array containing the cell count area of each polygon in the image. Entry zero of the Array does not contain meaningful information. eightNeighbors is a Boolean (true or false) specifying whether to consider 4 neighbors per pixel or eight. polyPerims(eightNeighbors) Returns an Array containing the cell count perimeter of each polygon in the image. Entry zero of the Array does not contain meaningful information. eightNeighbors is a Boolean (true or false) specifying whether to consider 4 neighbors per pixel or eight. polyClasses(eightNeighbors) Returns an Array containing the pixel value of each polygon in the image. Entry zero of the Array does not contain meaningful information. eightNeighbors is a Boolean (true or false) specifying whether to consider 4 neighbors per pixel or eight. area Returns the total area of the image in pixel counts. This is simply rows*cols. Background is not accounted for. perimeter Returns the total perimeter of the image. Does not simply sum the perimeters of each class as this would double count interclass perimeter. Rather it only counts each differing adjacency once. areas Returns an Array containing the pixel counts of each class present. The Array is indexed by pixel value. perimeters Returns an Array containing the pixel count perimeter of each class present. The Array is indexed by pixel value. pIJ(eightNeigbors,background) Returns a SparseMatrix containing adjacency probabilities for the image. The pIJ probabilities are calculated to represent the probability that a random pixel equals class I times the probability that class J is adjacent to it. eightNeighbors is a Boolean (true or false) specifying whether to consider 4 neighbors per pixel or eight. Background is the pixel value of the background color. If no background is present in the image, -1 should be specified. ImageInstance imageConv Returns the ImageConverter used to load this image file Returns the ImageFile associated with this instance. This is the primary way to access the pixel data and associated methods. distUnit The Unit this image defines for distances. It may be nil. areaUnit The Unit this image defines for areas. It may be nil. bitsPerPix Returns the number of bits per pixel for the associated ImageFile. Should be 1, 4, 8, 16, or 24. filename Returns a String with the filename of the ImageFile associated with this ImageInstance makeNewImage(rows,cols,bitsPerPix,engine) This method should be called by any ImageConverter’s readImage() method when it creates an image. Rows and cols specify the dimensions of the map. bitsPerPix must be one of 1, 4, 8, 16, or 24 and represents the bits per pixel of the new image. engine is the Engine that interacts with the user interface. Integer This class used to report AnalysisType::IMAGE metric output. See Ruby’s definition of Integer for information on available methods, etc. Option Documented above. OptionList add(optionSummary) Add an OptionSummary to the list of Options find(optionName) If optionName is found in the list this method returns the associated OptionSummary, otherwise it returns nil. OptionSummary new(abbrev,name,args) Create an OptionSummary. Abbrev is the short name of the Option (usually derived from its filename). For example, “N” for neighbors option (n.rb). name is the long name of the Option (i.e. “Neighborhood”) that will be used to search for it in OptionLists. dig_to_i(digitString) Returns the integer specified by digitString. digitString can be binary (0b001), octal (0377), decimal (10), or hexadecimal (0xff). value Returns the current value of the Option (as specified by the user) OutputSummary This is the class that must be created by Analyses. Each analysis returns an Array of these. new(name,abbrev,type,data,unit,family,precision) Name is the textual description of the metric associated with this output (for instance, “Average Area”). Abbrev is a 10 or fewer character String representing an abbreviated name for this output (for instance, “AveArea”). Spaces are not allowed in the abbreviation. Type specifies the kind of output this summary contains: AnalysisType::IMAGE (a measure that applies to the image as a whole, a Float or an Integer), AnalysisType::CLASS (a measure that applies to each class in the image, a Hash), or AnalysisType::INTERCLASS (a measure that applies to each combination of classes in the image, a SparseMatrix). Data is the actual measure (Float, Integer, Hash, SparseMatrix). Unit is either NoUnit for analyses that do not force units (but default to Image units) or a unit found in units.dat (like Units.find(“percent”)). Family specifies whether this is a “scalar”, “distance”, “area” or “compound” metric. Precision lets any ReportWriter know how many digits are significant for output. name Returns a String containing the name of the metric. outType Returns one of AnalysisType::IMAGE, AnalysisType::CLASS, or AnalysisType::INTERCLASS. output Returns the actual measure (Float, Integer, Hash, SparseMatrix). unit Return the overriding Unit of this metric. Usually NoUnit. family Returns one of “scalar”, “distance”, “area”, “compound” precision Returns an Integer specifying how many digits past the decimal are significant for output. ReportWriter Documented above. SparseMatrix This class is used to report AnalysisType::INTERCLASS metric output. [](row,col) Returns the matrix entry for (row,col). Returns nil if entry is not found. Row and col do not need to be numeric but can be any object. For instance, sparseM[“feet”,”inches”] returns “6 foot 2” []=(row,col,value) Sets the matrix entry for (row,col) to value. Returns nil if entry is not found. Row and col do not need to be numeric but can be any object. For instance, sparseM[“feet”,”inches”] = “6 foot 2” each(a code block taking one parameter: | entry |) Applies the passed in code block to each entry in the SparseMatrix each_coord(a code block taking two parameters: | row col |) Applies the passed in code block to each (row,col) combination in the SparseMatrix String See Ruby’s definition of String for information on available methods, etc. Unit A class that represents real world units for the Analyses. Created in units.dat. name Name of this unit. Example: “millimeter” pluralName Plural name of this unit. Example: “millimeters” abbrev Abbreviation of this unit. Example: “mm” baseUnit Name of the unit that acts as a base unit for this unit. Example: “meters” factor The number of base units making up one of these units. Example: 0.001 family One of “scalar”, “distance”, “area”. Sharing your extension If you have an extension you would like to share contact ian-mail@mailplus.wisc.edu. Your extension may be added to the latest IAN distribution. Current extensions Lacunarity analysis: simply click this link to download LCU.rb and place it in the analyses directory under your current IAN installation. Analyses supported by IAN (as of October 7th, 2004) Index Area (A) Aggregation Index (AI) Adjacency Matrix (AM) Angular Second Moment (ASM) Core Area (CA) Contagion (CO) Dominance (DO) Edge Density (ED) Edge Distribution Evenness (EDE) Electivity (EL) Fractal Dimension – Box Counting method (FDB) Fractal Dimension – Perimeter/Area method (FDP) Inverse Difference Moment (IDM) Largest Polygon Index (LPI) Perimeter (P) Perimeter/Area ratios (PA) Perimeter/Area ratios – corrected (PAC) Polygon Area Summary Statistics (PAS) Polygon Perimeter Summary Statistics (PPS) Relative Area (RA) Relative Contagion (RCO) Relative Dominance (RDO) Shape Index Summary Statistics (SHP) Shared Perimeter (SP) Shannon-Weaver Diversity (SWD) Shannon-Weaver Evenness (SWE) Discussion Area (A) A reports the area of each class in the image Aggregation Index (AI) AI reports the aggregation indices upon an image. It is reported for the image as a whole as well as for each class present in the image. An AI analysis reports values between zero and one. AI equals 1.0 when a class is completely aggregated into a single square patch. It reports numbers closer to 0.0 when each patch is narrow in one direction and long in another. Definition: AI = total adjacent edges of class i with itself divided by the maximum possible adjacent edges of class i with itself. Reference: He H. S., B. E. DeZonia and D. J. Mladenoff. 2000. An aggregation index (AI) to quantify spatial patterns on landscapes. Landscape Ecology 15: 591-601 Adjacency Matrix (AM) AM reports the adjacency matrix probabilities between classes. Output values range between 0.00% and 100.00% and represent the proportional breakdown of neighbor cells. An AM value of 40% for class I to class J implies that it is 40% probable that a given cell on an image will be of class I and have class J adjacent to it. Reference: Li H., and J.F. Reynolds. 1993. A new contagion index to quantify spatial patterns of landscape. Landscape Ecology 3:155-162. Angular Second Moment (ASM) ASM reports the angular second moment of the image. It is a measure of image texture. ASM ranges from 0.0 for an image with many classes and little clumping to 1.0 for an image with a single class (maximum clumping). Note: This measure is derived from an adjacency matrix. In a paper in 1996 Riitters discusses how the method used to create the adjacency matrix can have a large impact upon resulting metrics. This can explain where IAN may differ from another package on this measure. Definition: given an adjacency matrix between the classes present ASM = the sum of the squared adjacencies for all combinations of the classes present. Core Area (CA) CA reports the core area measures of the image. It is reported for each class present in the image. For a single pixel core area is defined as 1 cell if all of its neighbors are of the same class as the pixel. An 8 neighbor rule is used. The total cell count for each class is then scaled to the correct units. Contagion (CO) CO reports the contagion of the image. Contagion is a measure of the degree to which classes are clumped into polygons. It is estimated by determining the image’s departure from maximal diversity. Contagion returns a value greater than or equal to zero. Large values of contagion arise from images that are predominantly made up of a few classes. Small values of contagion arise from images that are made up of many different classes in approximately equal proportions. Note: This measure is derived from an adjacency matrix. Different methods of computing adjacency exist. If IAN's measure departs from that of another package it may be due to differing methods of calculating adjacency. Definition: given an adjacency matrix T between classes present contagion = maximum possible diversity - measured diversity. Maximum diversity is 2 * ln(classes present) and measured diversity is the sum of T(i,j) * ln(T(i,j)) for all combinations of classes i and j. Reference: For more information see Li H., and J.F. Reynolds. 1993. A new contagion index to quantify spatial patterns of landscape. Landscape Ecology 3:155-162." Dominance (DO) DO reports the dominance measure of an image. Dominance is a measure of the degree to which an image departs from maximal diversity as defined by Shannon. DO returns a value greater than or equal to zero. Large values of DO arise from images that are predominantly made up of a few classes. Small values of DO arise from images that are made up of many different classes in approximately equal proportions. Definition: given a probability distribution p of the classes present, dominance = maximum possible diversity - measured diversity. Maximum diversity is defined as ln(classes present) and measured diversity is defined as -1 times the sum of p(i)*ln(p(i)) for all classes present. Reference: For more information see Turner M.G. 1990. Spatial and temporal analysis of landscape patterns. Landscape Ecology 1:21-30 Edge Density (ED) ED measures the edge density (edge length per unit area) of the image. It is reported for the image as a whole as well as for each class present in the image. ED is calculated as the total edge length divided by total image area for a given image or class. Edge Distribution Evenness (EDE) EDE reports the edge distribution evenness of the image. It is a measure of how equally distributed are the edge types of an image. EDE can range from zero for an image with no edge other than border to 1.0 for an image whose edge types (connections between differing classes) are all equally present within the image. Note: This measure uses an adjacency matrix. [Riitters 96] discusses how the method used to create the adjacency matrix can have a large impact upon resulting metrics. Definition: (given t, an adjacency matrix between classes present) First the main diagonal of the adjacency matrix is set to zero and the matrix is rescaled to sum to 1.0. Then: EDE = measured diversity / maximum diversity Measured diversity = -1 * the sum of all combinations of classes in the equation t(i,j) * ln(t(i,j). Maximum diversity is defined as 2 * ln (classes present). Reference: For more information see [Riitters 96] and [Wickham 96] [Riitters 96] - Riitters, O’Neill, et al. 1996. A note on contagion indices for landscape analysis. Landscape Ecology 11:197-202. [Wickham 96] - Wickham J.D., K.H. Riitters, R.V. O’Neill, K.B. Jones, and T.G. Wade. 1996. Landscape ‘Contagion’ in Raster and Vector Environments. International Journal of Geographical Information Systems 7:891-89 Electivity (EL) EL reports the electivity between classes present in the image. The electivity index calculated is equivalent to log Q as specified in the [Jacobs 74] paper (detailed below). Electivity measures the strength of association between the classes. For the purposes of EL association is measured from the number of times two classes border on each other relative to the maximum coupling possible. EL results range from minus infinity for two classes that never neighbor each other to positive infinity for two classes that always neighbor each other. Definition: EL = (Rij * (1-Pij)) / (Pij * (1-Rij)) where Rij = x11 / (x11 + x21) and Pij = x12 / (x12 + x22) and: x11 = couplings in which I and J participate x12 = couplings in which I participates and J does not x21 = couplings in which J participates and I does not x22 = couplings in which neither I nor J participates Note: only 4 neighbors are considered for couplings Reference: For more information regarding this specific electivity index see [Mladenoff 93], [Pastor 90], and [Jacobs 74]. For more information regarding electivity indices in general see [Lechowicz 82] [Jacobs 74] - Jacobs J. 1974. Quantitative Measurement of Food Selection. Oecologia 14:413-417 [Lechowicz 82] - Lechowicz M.J. 1982. The Sampling Characteristics of Electivity Indices. Oecologia 52:22-30 [Mladenoff 93] - Mladenoff D.J., M.A. White, J. Pastor, and T.R. Crow. 1993. Comparing spatial pattern in unaltered old-growth and disturbed forest landscapes. Ecological Applications 2:294-306 [Pastor 90] - Pastor J., and M. Broschart. 1990. The spatial pattern of a northern conifer-hardwood landscape. Landscape Ecology 1:55-68. Fractal Dimension – Box Counting method (FDB) FDB estimates the fractal dimension of the image using the box counting method. It is reported for each class present and for the image as a whole. FDB ranges from 1.0 for images made up of polygons whose outlines are very regular (or straight) to 2.0 for images made of polygons whose outlines are very irregular. Limitations: For those images whose sample set is too small to accurately estimate fractal dimension IAN reports 0. Definition: The calculation of FDB is the log-log regression of box size versus number of boxes required to cover the image. Reference: For more information regarding the implementation of this fractal dimension method and regarding the use of fractal dimension estimates in landscape ecology see [Loehle 90], [Milne 91], and [Sugihara 90]. There are many techniques and much debate as to how to accurately measure fractal dimension. For more information regarding this topic refer to [Russ 94]. [Loehle 90] - Loehle C. 1990. Home range: A fractal approach. Landscape Ecology 1:39-52 [Milne 91] - Milne B.T. 1991. The utility of fractal geometry in landscape design. Landscape and Urban Planning 21:81-90 [Russ 94] - Russ, John C. 1994. Fractal Surfaces. Plenum Press. New York, New York, USA [Sugihara 90] - Sugihara G., and R.M. May. 1990. Applications of Fractals in Ecology. TREE 3:79-86. Fractal Dimension – Perimeter/Area method (FDP) FDP estimates the fractal dimension of the image using the perimeter/area method as described in [Sugihari 90]. It is reported for the image as a whole as well as for each class present in the image. FDP ranges from 1.0 for images made up of polygons whose outlines are very regular (or straight) to 2.0 for images made of patches whose outlines are very irregular. Definition: The calculation of FDP is twice the log-log regression of polygon perimeters versus polygon areas. Note that FRAGSTATS calculates this measure by regressing polygon areas versus polygon perimeters. Either method is defensible and neither is correct. This is because the linear regression model assumptions are typically violated when measuring fractal objects. Reference: For more information regarding the implementation of this fractal dimension method and regarding the use of fractal dimension estimates in landscape ecology refer to [Sugihari 90]. There is much debate as to how to accurately measure fractal dimension. For more information regarding this topic refer to [Russ 94]. [Russ 94] - Russ, John C. 1994. Fractal Surfaces. Plenum Press. New York, New York, USA [Sugihara 90] - Sugihara G., and R.M. May. 1990. Applications of Fractals in Ecology. TREE 3:79-86. Inverse Difference Moment (IDM) IDM reports the inverse difference moment of an image. It is a measure of image texture. IDM ranges from 0.0 for an image that is highly textured to 1.0 for an image that is untextured (such as an image with a single class). Note: This measure uses an adjacency matrix. [Riitters 96] discusses how the method used to create the adjacency matrix can have a large impact upon resulting metrics. Definition: given t, an adjacency matrix between the classes present: IDM = sum of all combinations of classes of: (t(i,j)*t(i,j)) / (1 + (i-j)(i-j)) Limitations: Since IDM relies on the magnitude of differences between cell values it is only appropriate to compute it from interval data (as opposed to categorical data). Reference: For more information see [Musick 91] [Musick 91] - Musick, and Grover 1991. Image Textural Measures as Indices of Landscape Pattern, chapter in Quantitative Methods in Landscape Ecology, Turner and Gardner (1991). Springer-Verlag. New York, New York, USA. [Riitters 96] - Riitters, O’Neill, et al. 1996. A note on contagion indices for landscape analysis. Landscape Ecology 11:197-202. Largest Polygon Index (LPI) LPI measures the percentage of area taken up by the largest polygon. It is reported for the image as a whole as well as for each class present in the image. LPI is calculated as the largest polygon size divided by the total area of the image. It is multiplied by 100 to represent a percentage. Perimeter (P) P reports the perimeter of each class and of the image as a whole. Perimeter/Area ratios (PA) PA reports the average perimeter to area ratio for all polygons present in the image. It is reported for the image as a whole as well as for each class present in the image. PA is calculated by averaging the perimeter to area ratio for all polygons present. This provides a result that generally differs from dividing the total perimeter of the polygons by their total area. Reference: For more information see Baker W.L., and Y. Cai. 1992. The r.le programs for multiscale analysis of landscape structure using the GRASS geographical information system. Landscape Ecology 7:291-302 Perimeter/Area ratios – corrected (PAC) PAC reports the average corrected perimeter to area ratio for all polygons present in the image. It is reported for the image as a whole as well as for each class present in the image. A corrected perimeter to area ratio is calculated by dividing the perimeter of a polygon by the square root of the product of 4 pi and the area of the polygon. The average corrected perimeter to area ratio is calculated by averaging the corrected perimeter to area ratio for all polygons present. This provides a result that generally differs from dividing the total perimeter by the square root of 4 pi times the total area. PAC results are always greater than or equal to 1. PAC equals 1.0 for polygons that are perfect circles, 1.1 for polygons that are perfect squares, and can be arbitrarily large for polygons that are extremely long and skinny. Reference: For more information see Baker W.L., and Y. Cai. 1992. The r.le programs for multiscale analysis of landscape structure using the GRASS geographical information system. Landscape Ecology 7:291-302 Polygon Area Summary Statistics (PAS) This analysis reports the following measures upon an image and its classes: Total polygons Mean polygon area Standard Deviation of polygon area Median polygon area Interquartile range of polygon area Area of smallest polygon Area of largest polygon Polygon Perimeter Summary Statistics (PPS) This analysis reports the following measures upon an image and its classes: Total polygons Mean polygon perimeter Standard Deviation of polygon perimeter Median polygon perimeter Interquartile range of polygon perimeter Perimeter of smallest polygon Perimeter of largest polygon Relative Area (RA) RA reports the relative proportion of each class within the image. Relative Contagion (RCO) RCO reports the relative contagion of the image. It is based upon Riitter's version of contagion (corrections made to Li's version). Contagion is a measure of the degree to which classes are clumped into polygons. RCO reports relative contagion values. Therefore the possible values range from 0.0 for images with minimal contagion to 1.0 for images with maximum contagion. Note: This measure uses an adjacency matrix. [Riitters 96] discusses how the method used to create the adjacency matrix can have a large impact upon resulting metrics. Definition: (given t, an adjacency matrix between classes present) RCO = 1.0 - (measured diversity / maximum diversity) Measured diversity = -1 * the sum of all combinations of classes in the equation t(i,j) * ln(t(i,j). Maximum diversity is defined as 2 * ln (classes present). Reference: For more information see [Riitters 96] [Riitters 96] - Riitters, O’Neill, et al. 1996. A note on contagion indices for landscape analysis. Landscape Ecology 11:197-202. Relative Dominance (RDO) RDO reports the relative dominance measure of an image. Dominance is a measure of the degree to which an image departs from maximal diversity as defined by [Shannon 62]. RDO returns a value between 0.0 and 1.0 inclusive. Large values of RDO arise from images that are predominantly made up of a few classes. Small values of RDO arise from images that are made up of many different classes in approximately equal proportions. Definition: (given p, a probability distribution of the classes present) RDO = 1.0 - (measured diversity / maximum diversity) where measured diversity = -1 * sum over all classes of p(i)*ln(p(i)) and maximum diveristy = ln(classes present). Reference: For more information about dominance see [Turner 90] [Shannon 62] - Shannon and Weaver. 1962. The mathematical theory of communication. University of Illinois Press. Urbana, Illinois, USA. [Turner 90] - Turner M.G. 1990. Spatial and temporal analysis of landscape patterns. Landscape Ecology 1:21-30. Shape Index Summary Statistics (SHP) This metric calulates a statistical summary of the Shape Index upon the image. The summary includes mean, standard deviation, median, first quartile, third quartile, min, and max of the shape index of the polygons within the image.", The Shape Index for a polygon is defined as (perimeter / minimum perimeter) where minimum possible perimeter is calculated in the following manner: Find the edge length of the largest square smaller than the area of the polygon (n = floor(sqrt(area))). Let m be the difference between the area of the polygon and the area of sqr(n). Then the minimum perimeter equals 4n if m == 0 4n+2 if sqr(n) < area <= n(n+1) 4n+4 if area > n(n+1) The Shape Index is always >= 1 and is unitless. Values close to 1 imply that the shape of the polygon is compact. Large values imply an irregular shape. The Shape Index is scale independent. Polygons of the same shape but differing sizes will have the same shape index. Shared Perimeter (SP) SP reports the shared perimeter between classes. It reports perimeter for every 2 color combination of the classes present in the image. Shannon-Weaver Diversity (SWD) SWD reports the diversity of the image as described by [Shannon 62]. SWD results are always greater than or equal to zero. A low diversity measure implies an image is dominated by a single class. A high diversity measure implies an image that contains many classes in approximately equal proportions. Definition: (given p, a probability distribution of the classes present) SWD = -1 * sum over all classes of p(i)*ln(p(i)) Reference: For more information see [Turner 90] [Shannon 62] - Shannon and Weaver. 1962. The mathematical theory of communication. University of Illinois Press. Urbana, Illinois, USA. [Turner 90] - Turner M.G. 1990. Spatial and temporal analysis of landscape patterns. Landscape Ecology 1:21-30. Shannon-Weaver Evenness (SWE) SWE reports the relative diversity of the image where diversity is defined as described by [Shannon 62]. Relative diversity is computed as the measured diversity of the image divided by the maximum possible diversity for the image. SWE values range between 0 and 1 inclusive. Definition: (given p, a probability distribution of the classes present), SWE = measured diversity / maximum diversity where measured diversity = -1 * sum over all classes of p(i)*ln(p(i)) and maximum diversity = ln(classes present). [Shannon 62] - Shannon and Weaver. 1962. The mathematical theory of communication. University of Illinois Press. Urbana, Illinois, USA.