# wiki

name: TracTicketsCustomFields
author: trac
ipnr: 127.0.0.1
text:
  = Custom Ticket Fields =
  Trac supports adding custom, user-defined fields to the ticket module. Using custom fields, you can add typed, site-specific properties to tickets.

  == Configuration ==
  Configuring custom ticket fields is done in the [wiki:TracIni trac.ini] file. All field definitions should be under a section named `[ticket-custom]`.

  The syntax of each field definition is:
  {{{
   FIELD_NAME = TYPE
   (FIELD_NAME.OPTION = VALUE)
   ...
  }}}
  The example below should help to explain the syntax.

  === Available Field Types and Options ===
   * '''text''': A simple (one line) text field.
     * label: Descriptive label.
     * value: Default value.
     * order: Sort order placement. (Determines relative placement in forms.)
   * '''checkbox''': A boolean value check box.
     * label: Descriptive label.
     * value: Default value (0 or 1).
     * order: Sort order placement.
   * '''select''': Drop-down select box. Uses a list of values.
     * options: List of values, separated by '''|''' (vertical pipe).
     * value: Default value (Item #, starting at 0).
     * order: Sort order placement.
   * '''radio''': Radio buttons. Essentially the same as '''select'''.
     * label: Descriptive label.
     * options: List of values, separated by '''|''' (vertical pipe).
     * value: Default value (Item #, starting at 0).
     * order: Sort order placement.
   * '''textarea''': Multi-line text area.
     * label: Descriptive label.
     * value: Default text.
     * cols: Width in columns.
     * rows: Height in lines.
     * order: Sort order placement.

  === Sample Config ===
  {{{
  [ticket-custom]

  test_one = text
  test_one.label = Just a text box

  test_two = text
  test_two.label = Another text-box
  test_two.value = Just a default value

  test_three = checkbox
  test_three.label = Some checkbox
  test_three.value = 1

  test_four = select
  test_four.label = My selectbox
  test_four.options = one|two|third option|four
  test_four.value = 2

  test_five = radio
  test_five.label = Radio buttons are fun
  test_five.options = uno|dos|tres|cuatro|cinco
  test_five.value = 1

  test_six = textarea
  test_six.label = This is a large textarea
  test_six.value = Default text
  test_six.cols = 60
  test_six.rows = 30
  }}}

  ''Note: To make an entering an option for a `select` type field optional, specify a leading `|` in the `fieldname.options` option.''

  === Reports Involving Custom Fields ===

  The SQL required for TracReports to include custom ticket fields is relatively hard to get right. You need a `JOIN` with the `ticket_custom` field for every custom field that should be involved.

  The following example includes a custom ticket field named `progress` in the report:
  {{{
  #!sql
  SELECT p.value AS __color__,
     id AS ticket, summary, component, version, milestone, severity,
     (CASE status WHEN 'assigned' THEN owner||' *' ELSE owner END) AS owner,
     time AS created,
     changetime AS _changetime, description AS _description,
     reporter AS _reporter,
    (CASE WHEN c.value = '0' THEN 'None' ELSE c.value END) AS progress
    FROM ticket t
       LEFT OUTER JOIN ticket_custom c ON (t.id = c.ticket AND c.name = 'progress')
       JOIN enum p ON p.name = t.priority AND p.type='priority'
    WHERE status IN ('new', 'assigned', 'reopened')
    ORDER BY p.value, milestone, severity, time
  }}}

  Note in particular the `LEFT OUTER JOIN` statement here.

  ----
  See also: TracTickets, TracIni


name: WikiDeletePage
author: trac
ipnr: 127.0.0.1
text:
  = Deleting a Wiki Page =

  Existing wiki pages can be completely deleted using the ''Delete Page'' or the ''Delete this Version'' buttons at the bottom of the wiki page. These buttons are only visible for users with `WIKI_DELETE` permissions.

  '''Note:''' This is an irreversible operation.

  In general, it is recommended to create redirection pages instead of completely deleting an old page, as to not frustrate the visitor with broken links when coming to the site from a search engine. A redirection page is a short page that  contains a link such as  “See !SomeOtherPage”. However, deleting specific versions or even complete pages can make sense to remove spam or other abuse.

  ----
  See also: TracWiki, TracPermissions


name: TracBackup
author: trac
ipnr: 127.0.0.1
text:
  = Trac Backup =
  [[TracGuideToc]]

  Since Trac uses a database backend, some extra care is required to safely create a backup of a [wiki:TracEnvironment project environment]. Luckily, [wiki:TracAdmin trac-admin] has a command to make backups easier: `hotcopy`.

    ''Note: Trac uses the `hotcopy` nomenclature to match that of [http://subversion.tigris.org/ Subversion], to make it easier to remember when managing both Trac and Subversion servers.''

  == Creating a Backup ==

  To create a backup of a live TracEnvironment, simply run:
  {{{
    $ trac-admin /path/to/projenv hotcopy /path/to/backupdir
  }}}

  [wiki:TracAdmin trac-admin] will lock the database while copying.''

  The resulting backup directory is safe to handle using standard file-based backup tools like `tar` or `dump`/`restore`.

  === Restoring a Backup ===

  Backups are simply a copied snapshot of the entire [wiki:TracEnvironment project environment] directory, including the SQLite database. 

  To restore an environment from a backup, simply stop the process running Trac (i.e. the Web server or [wiki:TracStandalone tracd]), restore the directory structure from the backup and restart the service.

    ''Note: Automatic backup of environments that don't use SQLite as database backend is not supported at this time. As a workaround, we recommend that you stop the server, copy the environment directory, and make a backup of the database using whatever mechanism is provided by the database system.''

  ----
  See also: TracAdmin, TracEnvironment, TracGuide


name: TracTickets
author: trac
ipnr: 127.0.0.1
text:
  = The Trac Ticket System =
  [[TracGuideToc]]

  The Trac issue database provides simple but effective tracking of issues and bugs within a project.

  As the central project management element of Trac, tickets are used for '''project tasks''', '''feature requests''', '''bug reports''' and '''software support issues'''. 

  As with the TracWiki, this subsystem has been designed with the goal of making user contribution and participation as simple as possible. It should be as easy as possible to report bugs, ask questions and suggest improvements.

  An issue is assigned to a person who must resolve it or reassign the ticket to someone else.
  All tickets can be edited, annotated, assigned, prioritized and discussed at any time.

  '''Note:''' To make full use of the ticket system, use it as an ''in bucket'' for ideas and tasks for your project, rather than just bug/fault reporting. 

  == Ticket Fields ==

  A  ticket contains the following information attributes:
   
   * '''Reporter''' - The author of the ticket.
   * '''Type''' - The nature of the ticket (for example, defect or enhancement request)

   * '''Component''' - The project module or subsystem this ticket concerns.
   * '''Version''' - Version of the project that this ticket pertains to.
   * '''Keywords''' - Keywords that a ticket is marked with.  Useful for searching and report generation.

   * '''Priority''' - The importance of this issue, ranging from ''trivial'' to ''blocker''.
   * '''Milestone''' - When this issue should be resolved at the latest.
   * '''Assigned to/Owner''' - Principal person responsible for handling the issue.
   * '''Cc''' - A list of other associated people. ''Note that this does not imply responsiblity or any other policy.''
   
   * '''Resolution''' - Reason for why a ticket was closed. One of {{{fixed}}}, {{{invalid}}}, {{{wontfix}}}, {{{duplicate}}}, {{{worksforme}}}.
   * '''Status''' - What is the current status? One of {{{new}}}, {{{assigned}}}, {{{closed}}}, {{{reopened}}}.
   * '''Summary''' - A brief description summarizing the problem or issue.
   * '''Description''' - The body of the ticket. A good description should be specific, descriptive and to the point.

  '''Note:''' Versions of Trac prior to 0.9 did not have the ''type'' field, but instead provided a ''severity'' field and different default values for the ''priority'' field. This change was done to simplify the ticket model by removing the somewhat blurry distinction between ''priority'' and ''severity''. However, the old model is still available if you prefer it: just add/modify the default values of the ''priority'' and ''severity'', and optionally hide the ''type'' field by removing all the possible values through [wiki:TracAdmin trac-admin].


  == Changing and Commenting Tickets ==

  Once a ticket has been entered into Trac, you can at any time change the
  information by '''annotating''' the bug. This means changes and comments to
  the ticket are logged as a part of the ticket itself.

  When viewing a ticket, the history of changes will appear below the main ticket area.

  ''In the Trac project, we use ticket comments to discuss issues and tasks. This makes
  understanding the motivation behind a design- or implementation choice easier,
  when returning to it later.''

  '''Note:''' An important feature is being able to use TracLinks and
  WikiFormatting in ticket descriptions and comments. Use TracLinks to refer to
  other issues, changesets or files to make your ticket more specific and easier
  to understand.

  '''Note:''' See TracNotification for how to configure email notifications of ticket changes.

  === State Diagram ===
  http://projects.edgewall.com/trac/attachment/wiki/TracTickets/Trac%20Ticket%20State%20Chart%2020040607DF.png?format=raw


  == Default Values for Drop-Down Fields ==

  The option selected by default for the various drop-down fields can be set in [wiki:TracIni trac.ini], in the `[ticket]` section:

   * `default_type`: Default ticket type
   * `default_component`: Name of the component selected by default
   * `default_version`: Name of the default version
   * `default_milestone`: Name of the default milestone
   * `default_priority`: Default priority value
   * `default_severity`: Default severity value

  If any of these options are omitted, the default value will either be the first in the list, or an empty value, depending on whether the field in question is required to be set.


  == Hiding Fields and Adding Custom Fields ==

  Many of the default ticket fields can be hidden from the ticket web interface simply by removing all the possible values through [wiki:TracAdmin trac-admin]. This of course only applies to drop-down fields, such as ''type'', ''priority'', ''severity'', ''component'', ''version'' and ''milestone''.

  Trac also lets you add your own custom ticket fields. See TracTicketsCustomFields for more information.


  == Assign-to as Drop-Down List ==

  If the list of possible ticket owners is finite, you can change the ''assign-to'' ticket field from a text input to a drop-down list. This is done by setting the `restrict_owner` option of the `[ticket]` section in [wiki:TracIni trac.ini] to “true”. In that case, Trac will use the list of all users who have logged in and set their email address to populate the drop-down field.

  ''Note that this feature is '''still experimental as of version 0.9'''. There is no way to only display a subset of all known users as possible ticket owners. Nor is there a convenient way to remove emeritus users short of directly modifying the database.''


  == Preset Values for New Tickets ==

  To create a link to the new-ticket form filled with preset values, you need to call the `/newticket?` URL with variable=value separated by &. 

  Possible variables are :

   * '''reporter''' - Name or email of the reporter
   * '''summary''' - Summary line for the ticket
   * '''description''' - Long description of the ticket
   * '''component''' - The component droplist
   * '''version''' - The version droplist
   * '''severity''' - The severity droplist
   * '''keywords''' - The keywords 
   * '''priority''' - The priority droplist
   * '''milestone''' - The milestone droplist
   * '''owner''' - The person responsible for the ticket
   * '''cc''' - The list of emails for notifying about the ticket change

  '''Example:''' ''/trac/newticket?summary=Compile%20Error&version=1.0&component=gui''


  See also:  TracGuide, TracWiki, TracTicketsCustomFields, TracNotification


name: TracInstall
author: trac
ipnr: 127.0.0.1
text:
  = Trac Installation Guide = 
  [[TracGuideToc]]

  Trac is a lightweight project management tool that is implemented as a web-based application. Trac is written in the Python programming language and can use [http://sqlite.org/ SQLite] or [http://www.postgresql.org/ PostgreSQL] as  database. For HTML rendering, Trac uses the [http://www.clearsilver.net/ Clearsilver] templating system.

  What follows are generic instructions for installing and setting up Trac and its requirements. While you can find instructions for installing Trac on specific systems at [http://projects.edgewall.com/trac/wiki/TracInstallPlatforms TracInstallPlatforms] on the main Trac site, please be sure to first read through these general instructions to get a good understanding of the tasks involved.

  == Requirements ==

  To install Trac, the following software packages must be installed:

   * [http://www.python.org/ Python], version >= 2.3.
     * Python 2.4 is not supported on Windows since there are no Subversion bindings available for it.
     * For RPM-based systems you might also need the `python-devel` and `python-xml` packages.
   * [http://subversion.tigris.org/ Subversion], version >= 1.0. (>= 1.1 recommended) and corresponding [http://svnbook.red-bean.com/svnbook-1.1/ch08s02.html#svn-ch-8-sect-2.3 Python bindings]
     * Trac uses the [http://www.swig.org/ SWIG] bindings included in the Subversion distribution, '''not''' [http://pysvn.tigris.org/ PySVN] (which is sometimes confused with the standard SWIG bindings).
     * If Subversion was already installed without the SWIG bindings, you'll need to re-`configure` Subversion and `make swig-py`, `make install-swig-py`.
   * [http://www.clearsilver.net/ ClearSilver], version >= 0.9.3
     * With python-bindings (`./configure --with-python=/usr/bin/python`)

  === For SQLite ===

   * [http://www.sqlite.org/ SQLite], version 2.8.x or 3.x
   * [http://pysqlite.org/ PySQLite]
     * version 1.0.x (for SQLite 2.8.x)
     * version 1.1.x or 2.x (for SQLite 3.x)

  === For PostgreSQL ===

   * [http://www.postgresql.org/ PostgreSQL]
   * [http://initd.org/projects/psycopg1 psycopg1], [http://initd.org/projects/psycopg2 psycopg2], or [http://pypgsql.sourceforge.net/ pyPgSQL]

  === Optional Requirements ===

   * A CGI-capable web server (see TracCgi), or
   * a [http://www.fastcgi.com/ FastCGI]-capable web server (see TracFastCgi), or
   * [http://httpd.apache.org/ Apache] with [http://www.modpython.org/ mod_python 3.1.3+] (see TracModPython)
   * [http://peak.telecommunity.com/DevCenter/setuptools setuptools], version >= 0.5a13 for using plugins (see TracPlugins)
   * [http://docutils.sourceforge.net/ docutils], version >= 0.3.3 for WikiRestructuredText.
   * [http://silvercity.sourceforge.net/ SilverCity] and/or [http://www.gnu.org/software/enscript/enscript.html Enscript] for [wiki:TracSyntaxColoring syntax highlighting].

  '''Attention''': The various available versions of these dependencies are not necessarily interchangable, so please pay attention to the version numbers above. If you are having trouble getting Trac to work please double-check all the dependencies before asking for help on the [http://projects.edgewall.com/trac/wiki/MailingList MailingList] or [http://projects.edgewall.com/trac/wiki/IrcChannel IrcChannel].

  Please refer to the documentation of these packages to find out how they are best installed. In addition, most of the [http://projects.edgewall.com/trac/wiki/TracInstallPlatforms platform-specific instructions] also describe the installation of the dependencies.

  == Installing Trac ==

  Like most Python programs, the Trac Python package is installed by running the following command at the top of the source directory:
  {{{
  $ python ./setup.py install
  }}}

  ''Note: you'll need root permissions or equivalent for this step.''

  This will byte-compile the python source code and install it in the `site-packages` directory
  of your Python installation. The directories `cgi-bin`, `templates`, `htdocs`, `wiki-default` and `wiki-macros` are all copied to `$prefix/share/trac/.`

  The script will also install the [wiki:TracAdmin trac-admin] command-line tool, used to create and maintain [wiki:TracEnvironment project environments], as well as the [wiki:TracStandalone tracd] standalone server.

  === Advanced Users ===

  To install Trac to a custom location, or find out about other advanced installation options, run:
  {{{
  $ python ./setup.py --help
  }}}

  Specifically, you might be interested in:
  {{{
  $ python ./setup.py install --prefix=/path/you/want
  }}}


  == Creating a Project Environment ==

  A [wiki:TracEnvironment Trac environment] is the backend storage where Trac stores information like wiki pages, tickets, reports, settings, etc. An environment is basically a directory that contains a human-readable configuration file and various other files and directories.

  A new environment is created using [wiki:TracAdmin trac-admin]:
  {{{
  $ trac-admin /path/to/trac_project_env initenv
  }}}

  [wiki:TracAdmin trac-admin] will prompt you for the information it needs to create the environment, such as the name of the project, the path to an existing subversion repository, the [wiki:TracEnvironment#DatabaseConnectionStrings database connection string], and so on. If you're not sure what to specify for one of these options, just leave it blank to use the default value. The database connection string in particular will always work as long as you have SQLite installed. The only option where the default value is likely to not work is the path to the Subversion repository, so make sure that one's correct.

  Also note that the values you specify here can be changed later by directly editing the [wiki:TracIni] configuration file.

  ''Note: The user account under which the web server runs will require write permissions to the environment
  directory and all the files inside.''


  == Running the Standalone Server ==

  After having created a Trac environment, you can easily try the web interface by running the standalone server [wiki:TracStandalone tracd]:
  {{{
  $ tracd --port 8000 /path/to/projectenv
  }}}

  Then, fire up a browser and visit `http://localhost:8000/`. You should get a simple listing of all environments that tracd knows about. Follow the link to the environment you just created, and you should see Trac in action.


  == Running Trac on a Web Server ==

  Trac provides three options for connecting to a “real” web server: [wiki:TracCgi CGI], [wiki:TracFastCgi FastCGI] and [wiki:TracModPython mod_python]. For decent performance, it is recommended that you use either FastCGI or mod_python.

  == Configuring Authentication ==

  The process of adding, removing, and configuring user accounts for authentication depends on the specific way you run Trac.  To learn about how to accomplish these tasks, please visit one of the following pages:

   * TracStandalone if you use the standalone server, `tracd`.
   * TracCgi if you use the CGI or FastCGI methods.
   * TracModPython if you use the mod_python method.

  == Using Trac ==

  Once you have your Trac site up and running, you should be able to browse your subversion repository, create tickets, view the timeline, etc.

  Keep in mind that anonymous (not logged in) users can by default access most but not all of the features. You will need to configure authentication and grant additional [wiki:TracPermissions permissions] to authenticated users to see the full set of features.

  ''Enjoy!''

  [http://projects.edgewall.com/trac/wiki/TracTeam The Trac Team]

  ----
  See also:  TracGuide, TracCgi, TracFastCgi, TracModPython, TracUpgrade, TracPermissions


name: TracTimeline
author: trac
ipnr: 127.0.0.1
text:
  = The Trac Timeline =
  [[TracGuideToc]]

  The timeline provides a historic view of the project in a single report.

  It lists all Trac events that have occured in chronological order, a
  brief description of each event and if applicable, the person responsible for
  the change.

  The timeline lists these kinds of events:
   * '''Wiki page events''' -- Creation and changes
   * '''Ticket events''' -- Creation and resolution/closing (and optionally other changes)
   * '''Source code changes ''' -- Repository check-ins
   * '''Milestone ''' -- Milestone completed

  Each event entry provides a hyperlink to the specific event in question, as well as
  a brief excerpt of the actual comment or text, if available.

  == RSS Support ==

  The Timeline module supports subscription using RSS 2.0 syndication. To subscribe to project events, click orange '''XML''' icon at the bottom of the page. See TracRss for more information on RSS support in Trac.

  ----
  See also: TracGuide, TracWiki, WikiFormatting, TracRss, TracNotification


name: TracRss
author: trac
ipnr: 127.0.0.1
text:
  = Using RSS with Trac =
  [[TracGuideToc]]

  Several of the Trac modules support content syndication using the RSS (Really Simple Syndication) XML format.
  Using the RSS subscription feature in Trac, you can easily monitor progress of the project, a set of issues or even changes to a single file .

  Trac supports RSS feeds in:

   * TracTimeline --  Use the RSS feed to '''subscribe to project events'''.[[br]]Monitor overall project progress in your favorite RSS reader.
   * TracReports and TracQuery -- Allows syndication of report and ticket query results.[[br]]Be notified about important and relevant issue tickets.
   * TracBrowser -- Syndication of file changes.[[br]]Stay up to date with changes to a specific file or directory.

  == How to access RSS data ==
  Anywhere in Trac where RSS is available, you should find a small orange '''XML''' icon, typically placed at the bottom of the page. Clicking the icon will access the RSS feed for that specific resource.

  '''Note:''' Different modules provide different data in their RSS feeds. Usually, the syndicated information corresponds to the current view. For example, if you click the RSS link on a report page, the feed will be based on that report. It might be explained by thinking of the RSS feeds as an ''alternate view of the data currently displayed''.

  == Links ==
   * http://blogs.law.harvard.edu/tech/rss -- RSS 2.0 Specification
   * http://www.mozilla.org/products/firefox/ -- Mozilla Firefox supports [http://www.mozilla.org/products/firefox/live-bookmarks.html live bookmarks] using RSS
   * http://sage.mozdev.org -- Sage RSS and Atom feed aggregator for Mozilla Firefox
   * http://www.rssreader.com/ -- Free and powerful RSS Reader for Windows
   * http://liferea.sourceforge.net/ -- Open source GTK2 RSS Reader for Linux
   * http://akregator.sourceforge.net/ -- Open source KDE RSS Reader (will be part of KDE-PIM 3.4)
   * http://www.sharpreader.net/ -- A free RSS Reader written in .NET for Windows
  ----
  See also: TracGuide, TracTimeline, TracReports, TracBrowser


name: WikiPageNames
author: trac
ipnr: 127.0.0.1
text:
  = Wiki Page Names =

  Wiki page names are written using CamelCase. Within a wiki text, any word in CamelCase automatically becomes a hyperlink to the wiki page with that same name.

  Page names must follow these rules:

   1. The name must consist of '''alphabetic characters only'''. No digits, spaces, punctuation, or underscores are allowed.
   1. A name must have at least two capital letters.
   1. The first character must be capitalized.
   1. Every capital letter must be followed by one or more lower-case letters. 
   1. The use of slash ( / ) is permitted to create a hierarchy inside the wiki.  (See !SubWiki and !ParentWiki macros in the [http://projects.edgewall.com/trac/wiki/MacroBazaar MacroBazaar] which provide a way to list all sub-entries and a link up the hierarchy respectively.)

  If you want to create a wiki page that doesn't follow CamelCase rules you could use the following syntax:
  {{{
  [wiki:Wiki_page]
  }}}

  This will be rendered as:
   [wiki:Wiki_page]

  ----
  See also: WikiNewPage, WikiFormatting, TracWiki


name: TracImport
author: trac
ipnr: 127.0.0.1
text:
  = Importing ticket data =

  == Bugzilla ==

  Ticket data can be imported from Bugzilla using the [http://projects.edgewall.com/trac/browser/trunk/contrib/bugzilla2trac.py bugzilla2trac.py] script, available in the contrib/ directory of the Trac distribution.

  {{{
  $ bugzilla2trac.py
  bugzilla2trac - Imports a bug database from Bugzilla into Trac.

  Usage: bugzilla2trac.py [options]

  Available Options:
    --db <MySQL dbname>              - Bugzilla's database
    --tracenv /path/to/trac/env      - full path to Trac db environment
    -h | --host <MySQL hostname>     - Bugzilla's DNS host name
    -u | --user <MySQL username>     - effective Bugzilla's database user
    -p | --passwd <MySQL password>   - Bugzilla's user password
    -c | --clean                     - remove current Trac tickets before importing
    --help | help                    - this help info

  Additional configuration options can be defined directly in the script.
  }}}

  Currently, the following data is imported from Bugzilla:

    * bugs
    * bug activity (field changes)
    * bug attachments
    * user names and passwords (put into a htpasswd file)

  The script provides a number of features to ease the conversion, such as:

    * PRODUCT_KEYWORDS:  Trac doesn't have the concept of products, so the script provides the ability to attach a ticket keyword instead.

    * IGNORE_COMMENTS:  Don't import Bugzilla comments that match a certain regexp.

    * STATUS_KEYWORDS:  Attach ticket keywords for the Bugzilla statuses not available in Trac.  By default, the 'VERIFIED' and 'RELEASED' Bugzilla statuses are translated into Trac keywords.

  For more details on the available options, see the configuration section at the top of the script.

  == Sourceforge ==

  Ticket data can be imported from Sourceforge using the [http://projects.edgewall.com/trac/browser/trunk/contrib/sourceforge2trac.py sourceforge2trac.py] script, available in the contrib/ directory of the Trac distribution.

  == Mantis ==

  Mantis bugs can be imported using the attached script.

  Currently, the following data is imported from Mantis:
    * bugs
    * bug comments
    * bug activity (field changes)

  Attachments are NOT imported.  If you use the script, please read the NOTES section (at the top of the file) and make sure you adjust the config parameters for your environment.

  mantis2trac.py has the same parameters as the bugzilla2trac.py script:
  {{{
  mantis2trac - Imports a bug database from Mantis into Trac.

  Usage: mantis2trac.py [options] 

  Available Options:
    --db <MySQL dbname>              - Mantis database
    --tracenv /path/to/trac/env      - Full path to Trac db environment
    -h | --host <MySQL hostname>     - Mantis DNS host name
    -u | --user <MySQL username>     - Effective Mantis database user
    -p | --passwd <MySQL password>   - Mantis database user password
    -c | --clean                     - Remove current Trac tickets before importing
    --help | help                    - This help info

  Additional configuration options can be defined directly in the script.
  }}} 

  == Other ==

  Since trac uses a SQL database to store the data, you can import from other systems by examining the database tables. Just go into [http://www.sqlite.org/sqlite.html sqlite] command line to look at the tables and import into them from your application.


name: TracFastCgi
author: trac
ipnr: 127.0.0.1
text:
  = Trac with FastCGI =

  Since version 0.9, Trac supports being run through the [http://www.fastcgi.com/ FastCGI] interface. Like [wiki:TracModPython mod_python], this allows Trac to remain resident, and is faster than external CGI interfaces which must start a new process for each request. However, unlike mod_python, it is able to support [http://httpd.apache.org/docs/suexec.html SuEXEC]. Additionally, it is supported by much wider variety of web servers.

  == Simple Apache configuration ==
  {{{
  # Enable fastcgi for .fcgi files
  # (If you're using a distro package for mod_fcgi, something like
  # this is probably already present)
  <IfModule mod_fastcgi.c>
     AddHandler fastcgi-script .fcgi
     FastCgiIpcDir /var/lib/apache2/fastcgi 
  </IfModule>
  LoadModule fastcgi_module /usr/lib/apache2/modules/mod_fastcgi.so
  }}}

  You can either setup the `TRAC_ENV` as an overall default:
  {{{
  FastCgiConfig -initial-env TRAC_ENV=/path/to/env/trac
  }}}

  Or you can serve multiple Trac projects in a directory like:
  {{{
  FastCgiConfig -initial-env TRAC_ENV_PARENT_DIR=/parent/dir/of/projects
  }}}

  Configure `ScriptAlias` or similar options as described in TracCgi, but calling `trac.fcgi` instead of `trac.cgi`.

  == Simple Lighttpd Configuration ==

  The FastCGI front-end was developed primarily for use with alternative webservers, such as [http://www.lighttpd.net/ lighttpd].

  lighttpd is a secure, fast, compliant and very flexible web-server that has been optimized for high-performance
  environments.  It has a very low memory footprint compared to other web servers and takes care of CPU load.

  For using `trac.fcgi` with lighttpd add the following to your lighttpd.conf:
  {{{
  fastcgi.server = ("/trac" =>
                     ("trac" =>
                       ("socket" => "/tmp/trac-fastcgi.sock",
                        "bin-path" => "/path/to/cgi-bin/trac.fcgi",
                        "check-local" => "disable",
                        "bin-environment" =>
                          ("TRAC_ENV" => "/path/to/projenv")
                       )
                     )
                   )
  }}}

  Note that you will need to add a new entry to `fastcgi.server` for each separate Trac instance that you wish to run. Alternatively, you may use the `TRAC_ENV_PARENT_DIR` variable instead of `TRAC_ENV` as described  above.

  Other important information like [http://trac.lighttpd.net/trac/wiki/TracInstall this updated TracInstall page], [wiki:TracCgi#MappingStaticResources and this] are useful for non-fastcgi specific installation aspects.

  Relaunch lighttpd, and browse to `http://yourhost.example.org/trac` to access Trac.

  ----
  See also TracCgi, TracModPython, TracInstall, TracGuide


name: TracIni
author: trac
ipnr: 127.0.0.1
text:
  = The Trac Configuration File =
  [[TracGuideToc]]

  Trac configuration is done by editing the '''`trac.ini`''' config file, located in `<projectenv>/conf/trac.ini`.

  == Global Configuration ==

  Since version 0.9, Trac can also read the configuration from a global `trac.ini` file. These global options will then be merged with the environment-specific options, where local options override global options.

  The global configuration is by default localted in `$prefix/share/trac/conf/trac.ini`. It can be moved to a different location (for example, `/etc/trac.ini`), but that requires changing the file `trac/siteconfig.py` which gets created when Trac is installed. 

  == Reference ==

  This is a brief reference of available configuration options.

  == [trac] ==
  || `database`        || [wiki:TracEnvironment#DatabaseConnectionStrings Database connection string] for this project ||
  || `default_charset` || Charset used in text files in the subversion repository (default is `iso-8859-15`) ||
  || `default_handler` || Name of the component that handles requests to the base URL (default is `WikiHandler`) (''since 0.9'') ||
  || `repository_dir`  || Path to local Subversion repository ||
  || `authz_file`      || Path to Subversion [http://svnbook.red-bean.com/en/1.1/ch06s04.html#svn-ch-6-sect-4.4.2 authorization (authz) file]. ||
  || `authz_module_name` || The module prefix used in the `authz_file` (See FineGrainedPermissions)||
  || `check_auth_ip` || Whether the IP address of the user should be checked for authentication (true, false) (''since 0.9'') ||
  || `ignore_auth_case` || Whether case should be ignored for login names (true, false) (''since 0.9'') ||
  || `templates_dir`   || Path to the !ClearSilver templates ||

  == [project] ==
  || `name`   || Project name ||
  || `descr`  || Short project description ||
  || `url`    || URL to the main project website ||
  || `icon`   || URL to icon file to use as shortcut icon (favicon) ||
  || `footer` || Page footer text (right-aligned) ||

  == [header_logo] ==
  || `src`    || URL to image to use as header logo ||
  || `link`   || Destination URL to link to from header logo ||
  || `alt`    || ''alt'' text for header logo ||
  || `width`  || Header logo width in pixels ||
  || `height` || Header logo height in pixels ||
  See also: TracInterfaceCustomization.

  == [logging] ==
  || `log_type`  || Logging facility to use. (none, file, stderr, syslog, winlog) ||
  || `log_file`  || If ''log_type'' is ''file'', this should be a path to the log-file ||
  || `log_level` || Level of verbosity in log (CRITICAL, ERROR, WARN, INFO, DEBUG) ||
  See also: TracLogging

  == [attachment] ==
  || `max_size` || Maximum allowed file size for ticket and wiki attachments ||

  == [notification] ==
  || `smtp_enabled`   || Enable SMTP (email) notification (true, false) ||
  || `smtp_server`    || SMTP server to use for email notifications ||
  || `smtp_user`      || Username for SMTP server (''since 0.9'') ||
  || `smtp_password`  || Password for SMTP server (''since 0.9'') ||
  || `smtp_from`      || Sender address to use in notification emails ||
  || `smtp_replyto`   || Reply-To address to use in notification emails ||
  || `smtp_always_cc` || Email address(es) to always send notifications to ||
  || `always_notify_reporter` || Always send notifications to any address in the ''reporter'' field ||
  || `always_notify_owner` || Always send notifications to the ticket owner (''since 0.9'') ||
  See also: TracNotification

  == [mimeviewer] ==
  || `enscript_path` || Path to the Enscript program ||
  || `php_path` || Path to the PHP program ||
  || `max_preview_size` || Maximum file size for HTML preview (''since 0.9'') ||
  || `tab_width` || Displayed tab width in file preview (''since 0.9'') ||

  == [ticket] ==
  || `default_version`   || Default version for newly created tickets ||
  || `default_severity`  || Default severity for newly created tickets ||
  || `default_priority`  || Default priority for newly created tickets ||
  || `default_milestone` || Default milestone for newly created tickets ||
  || `default_component` || Default component for newly created tickets ||
  || `restrict_owner`    || Make the owner field of tickets use a drop-down menu (''since 0.9'') ||

  == [ticket-custom] ==
  Creates [wiki:TracTicketsCustomFields user-defined ticket fields].

  == [timeline] ==
  || `default_daysback` || Default "depth" of the Timeline, in days (''since 0.9'') ||
  || `changeset_show_files` || Number of files to show (-1 for unlimited, 0 to disable) ||
  || `ticket_show_details` || Enable the display of all ticket changes in the timeline ||

  == [browser] ==
  || `hide_properties` || List of subversion properties to hide from the repository browser (''since 0.9'') ||

  == [wiki] ==
  || `ignore_missing_pages` || enable/disable highlighting CamelCase links to missing pages (''since 0.9'') ||

  == [components] ==
  (''since 0.9'')

  This section is used to enable or disable components provided by plugins, as well as by Trac itself. The component to enable/disable is specified via the name of the option. Whether its enabled is determined by the option value; setting the value to `enabled` or `on` will enable the component, any other value (typically `disabled` or `off`) will disable the component.

  The option name is either the fully qualified name of the components or the module/package prefix of the component. The former enables/disables a specific component, while the latter enables/disables any component in the specified package/module.

  Consider the following configuration snippet:
  {{{
  [components]
  trac.ticket.report.ReportModule = disabled
  webadmin.* = enabled
  }}}

  The first option tells Trac to disable the [wiki:TracReports report module]. The second option instructs Trac to enable all components in the `webadmin` package. Note that the trailing wildcard is required for module/package matching.

  See the ''Plugins'' page on ''About Trac'' to get the list of active components (requires `CONFIG_VIEW` [wiki:TracPermissions permissions].)

  See also: TracPlugins

    ''Note that prior to Trac r2335 (that applies to 0.9b1 and 0.9b2), you would use a `[disabled_components]` section instead. See a [http://projects.edgewall.com/trac/wiki/TracIni?version=42 previous version] of this page for the details.''

  ----
  See also: TracGuide, TracAdmin, TracEnvironment


name: WikiRestructuredText
author: trac
ipnr: 127.0.0.1
text:
  = reStructuredText Support in Trac =

  Trac supports using ''reStructuredText'' (RST) as an alternative to wiki markup in any context WikiFormatting is used.

  From the reStucturedText webpage:
   "''reStructuredText is an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser   system. It is useful for in-line program documentation (such as Python docstrings), for quickly creating  simple web pages, and for standalone documents. reStructuredText is designed for extensibility for  specific application domains. ''"

  === Requirements ===
  Note that to activate RST support in Trac, the python docutils package must be installed. 
  If not already available on your operating system, you can download it at the [http://docutils.sourceforge.net/rst.html RST Website].

  === More information on RST ===

   * reStructuredText Website -- http://docutils.sourceforge.net/rst.html
   * RST Quick Reference -- http://docutils.sourceforge.net/docs/rst/quickref.html

  ----

  == Using RST in Trac ==
  To specify that a block of text should be parsed using RST, use the ''rst'' processor. 

  === TracLinks in reStructuredText ===

   * Trac provides a custom RST reference-directive 'trac' to allow TracLinks from within RST text.

   Example:
   {{{
   {{{
   #!rst
   This is a reference to |a ticket|

   .. |a ticket| trac:: #42
   }}}
   }}}

   For a complete example of all uses of the ''trac''-directive, please see WikiRestructuredTextLinks. 


   * Trac allows an even easier way of creating TracLinks in RST, using the custom '':trac:'' link naming scheme.

   Example:
   {{{
   {{{
   #!rst
   This is a reference to ticket `#12`:trac:

   To learn how to use Trac, see `TracGuide`:trac:
   }}}
   }}}

  === Syntax highlighting in reStructuredText ===

  There is a directive for doing TracSyntaxColoring in ReST as well. The directive is called
  code-block

  Example

  {{{
  {{{
  #!rst

  .. code-block:: python

   class Test:

      def TestFunction(self):
          pass

  }}}
  }}}

  Will result in the below.

  {{{
  #!rst

  .. code-block:: python

   class Test:

      def TestFunction(self):
          pass

  }}}

  === WikiMacros in reStructuredText ===

  For doing WikiMacros in ReST you use the same directive as for syntax highlightning i.e
  code-block. To work you must use a version of trac that has #801 applied. 

  === WikiMacro Example ===

  {{{
  {{{
  #!rst

  .. code-block:: HelloWorld
   
     Something I wanted to say


  }}}
  }}}

  Will result in the below.

  [[HelloWorld(Something I wanted to say)]]


  === Bigger ReST Example ===
  The example below should be mostly self-explanatory:
  {{{
  #!html
  <pre class="wiki">{{{
  #!rst
  FooBar Header
  =============
  reStructuredText is **nice**. It has its own webpage_.

  A table:

  =====  =====  ======
     Inputs     Output
  ------------  ------
    A      B    A or B
  =====  =====  ======
  False  False  False
  True   False  True
  False  True   True
  True   True   True
  =====  =====  ======

  RST TracLinks
  -------------

  See also ticket `#42`:trac:.

  .. _webpage: http://docutils.sourceforge.net/rst.html
  }}}</pre>
  }}}


  Results in:
  {{{
  #!rst
  FooBar Header
  =============
  reStructuredText is **nice**. It has its own webpage_.

  A table:

  =====  =====  ======
     Inputs     Output
  ------------  ------
    A      B    A or B
  =====  =====  ======
  False  False  False
  True   False  True
  False  True   True
  True   True   True
  =====  =====  ======

  RST TracLinks
  -------------

  See also ticket `#42`:trac:.

  .. _webpage: http://docutils.sourceforge.net/rst.html
  }}}


  ----
  See also: WikiRestructuredTextLinks, WikiProcessors, WikiFormatting


name: TracPermissions
author: trac
ipnr: 127.0.0.1
text:
  = Trac Permissions =
  [[TracGuideToc]]

  Trac uses a simple but flexible permission system to control what users can and can't access.

  Permission privileges are managed using the [wiki:TracAdmin trac-admin] tool.

  Regular visitors, non-authenticated users, accessing the system are assigned the default 
  role (''user'') named {{{anonymous}}}. 
  Assign permissions to the {{{anonymous}}} user to set privileges for non-authenticated/guest users.

  In addition to these privileges users can be granted additional individual 
  rights in effect when authenticated and logged into the system.

  == Available Privileges ==

  To enable all privileges for a user, use the `TRAC_ADMIN` permission. Having `TRAC_ADMIN` is like being `root` on a *NIX system, it will let you do anything you want.

  Otherwise, individual privileges can be assigned to users for the various different functional areas of Trac:

  === Repository Browser ===

  || `BROWSER_VIEW` || View directory listings in the [wiki:TracBrowser repository browser] ||
  || `LOG_VIEW` || View revision logs of files and directories in the [wiki:TracBrowser repository browser] ||
  || `FILE_VIEW` || View files in the [wiki:TracBrowser repository browser] ||
  || `CHANGESET_VIEW` || View [wiki:TracChangeset repository check-ins] ||

  === Ticket System ===

  || `TICKET_VIEW` || View existing [wiki:TracTickets tickets] and perform [wiki:TracQuery ticket queries] ||
  || `TICKET_CREATE` || Create new [wiki:TracTickets tickets] ||
  || `TICKET_APPEND` || Add comments or attachments to [wiki:TracTickets tickets] ||
  || `TICKET_CHGPROP` || Modify [wiki:TracTickets ticket] properties ||
  || `TICKET_MODIFY` || Includes both `TICKET_APPEND` and `TICKET_CHGPROP`, and in addition allows resolving [wiki:TracTickets tickets] ||
  || `TICKET_ADMIN` || All `TICKET_*` permissions, plus the deletion of ticket attachments. ||

  === Roadmap ===

  || `MILESTONE_VIEW` || View a milestone ||
  || `MILESTONE_CREATE` || Create a new milestone ||
  || `MILESTONE_MODIFY` || Modify existing milestones ||
  || `MILESTONE_DELETE` || Delete milestones ||
  || `MILESTONE_ADMIN` || All `MILESTONE_*` permissions ||
  || `ROADMAP_VIEW` || View the [wiki:TracRoadmap roadmap] page ||
  || `ROADMAP_ADMIN` || Alias for `MILESTONE_ADMIN` (deprecated) ||

  === Reports ===

  || `REPORT_VIEW` || View [wiki:TracReports reports] ||
  || `REPORT_SQL_VIEW` || View the underlying SQL query of a [wiki:TracReports report] ||
  || `REPORT_CREATE` || Create new [wiki:TracReports reports] ||
  || `REPORT_MODIFY` || Modify existing [wiki:TracReports reports] ||
  || `REPORT_DELETE` || Delete [wiki:TracReports reports] ||
  || `REPORT_ADMIN` || All `REPORT_*` permissions ||

  === Wiki System ===

  || `WIKI_VIEW` || View existing [wiki:TracWiki wiki] pages ||
  || `WIKI_CREATE` || Create new [wiki:TracWiki wiki] pages ||
  || `WIKI_MODIFY` || Change [wiki:TracWiki wiki] pages ||
  || `WIKI_DELETE` || Delete [wiki:TracWiki wiki] pages and attachments ||
  || `WIKI_ADMIN` || All `WIKI_*` permissions, plus the management of ''readonly'' pages. ||

  === Others ===

  || `TIMELINE_VIEW` || View the [wiki:TracTimeline timeline] page ||
  || `SEARCH_VIEW` || View and execute [wiki:TracSearch search] queries ||
  || `CONFIG_VIEW` || Enables additional pages on ''About Trac'' that show the current configuration or the list of installed plugins ||

  == Granting Privileges ==

  Currently the only way to grant privileges to users is by using the `trac-admin` script. The current set of privileges can be listed with the following command:
  {{{
    $ trac-admin /path/to/projenv permission list
  }}}

  This command will allow the user ''bob'' to delete reports:
  {{{
    $ trac-admin /path/to/projenv permission add bob REPORT_DELETE
  }}}

  == Permission Groups ==

  Permissions can be grouped together to form roles such as ''developer'', ''admin'', etc.
  {{{
    $ trac-admin /path/to/projenv permission add developer WIKI_ADMIN
    $ trac-admin /path/to/projenv permission add developer REPORT_ADMIN
    $ trac-admin /path/to/projenv permission add developer TICKET_MODIFY
    $ trac-admin /path/to/projenv permission add bob developer
    $ trac-admin /path/to/projenv permission add john developer
  }}}

  == Default Permissions ==

  Granting privileges to the special user ''anonymous'' can be used to control what an anonymous user can do before they have logged in.

  In the same way, privileges granted to the special user ''authenticated'' will apply to any authenticated (logged in) user.

  ----
  See also: TracAdmin, TracGuide


name: TracSupport
author: trac
ipnr: 127.0.0.1
text:
  = Trac Support =

  Like in most [http://www.opensource.org/ open source projects], "free" Trac support is available primarily through the community itself, mainly through the [http://projects.edgewall.com/trac/wiki/MailingList mailing list] and the project wiki.

  There is also an [http://projects.edgewall.com/trac/wiki/IrcChannel IRC channel], where people might be able to help out. Much of the 'live' development discussions also happen there.

  Before you start a new support query, make sure you've done the appropriate searching:
   * in the project's [http://projects.edgewall.com/trac/wiki/TracFaq FAQ]
   * in past messages to the Trac [http://blog.gmane.org/gmane.comp.version-control.subversion.trac.general?set_user_css=http%3A%2F%2Fwww.edgewall.com%2Fcss%2Fgmane.css&do_set_user_css=t Mailing List]
   * in the Trac ticket system, using either a [http://projects.edgewall.com/trac/search?q=&ticket=on&wiki=on full search] or a [http://projects.edgewall.com/trac/query?summary=~&keywords=~" ticket query].

  ----
  See also: [http://projects.edgewall.com/trac/wiki/MailingList MailingList]


name: WikiHtml
author: trac
ipnr: 127.0.0.1
text:
  = Using HTML in Wiki Text =

  Trac supports inserting HTML into any wiki context, accomplished using the HTML [wiki:WikiProcessors WikiProcessor].

  HTML support is built-in, and does not require installing any additional packages.

  == How to Use HTML ==
  To inform the wiki engine that a block of text should be treated as HTML, use the ''html'' processor. 

  This example should explain:
  {{{
  #!html
  <pre class="wiki">{{{
  #!html
  &lt;h1 style="text-align: right; color: blue"&gt;HTML Test&lt;/h1&gt;
  }}}</pre>
  }}}

  Results in:
  {{{
  #!html
  <h1 style="text-align: right; color: blue">HTML Test</h1>
  }}}

  == More Information ==

   * http://www.w3.org/ -- World Wide Web Consortium
   * http://www.w3.org/MarkUp/ -- HTML Markup Home Page

  ----
  See also:  WikiProcessors, WikiFormatting, WikiRestructuredText


name: TracSyntaxColoring
author: trac
ipnr: 127.0.0.1
text:
  = Syntax Coloring of Source Code =
  Trac supports language-specific syntax highlighting of source code in [wiki:WikiFormatting wiki formatted] text and the [wiki:TracBrowser repository browser].

  To do this, Trac uses external libraries with support for a great number of programming languages.

  Currently Trac supports syntax coloring using one or more of the following packages:

   * [http://people.ssh.fi/mtr/genscript/ GNU Enscript]
   * [http://silvercity.sourceforge.net/ SilverCity]

  To activate syntax coloring, simply install either one (or more) of these packages. No additional configuration is required, however to modify the colors, have a look at `trac/htdocs/css/code.css`.

  When in use, Trac will automatically prioritize !SilverCity highlighting over Enscript if possible, (see note below). 

  If neither package is available, Trac will display the data as plain text. 

  '''Note:''' Enscript supports a greater number of languages, however !SilverCity is generally faster since it is a library and isn't executed in an external process.

  === About SilverCity ===
  !SilverCity uses the lexer from [http://www.scintilla.org/ Scintilla]. Scintilla supports more languages than !SilverCity implements. If you want to add a language to !SilverCity supported by Scintilla, it's not very difficult. See [http://projects.edgewall.com/trac/wiki/SilverCityAddLanguage SilverCityAddLanguage] for some information how.


  == Syntax Coloring Support ==

  || || !SilverCity || Enscript ||
  || Ada      ||   || X ||
  || Asm      ||   || X ||
  || * ASP    || X || X ||
  || * C      || X || X ||
  || * C++    || X || X ||
  || * Java   ||   || X ||
  || Awk      ||   || X ||
  || CSS      || X ||   ||
  || Diff     ||   || X ||
  || Eiffel   ||   || X ||
  || Elisp    ||   || X ||
  || Fortran  ||   || X ||
  || Haskell  ||   || X ||
  || HTML     || X || X ||
  || IDL      ||   || X ||
  || Javascript || X || X ||

  || m4       ||   || X ||
  || Makefile ||   || X ||
  || Matlab   ||   || X ||
  || Objective-C|| || X ||
  || Pascal   ||   || X ||
  || * Perl   || X || X ||
  || * PHP    || X || X ||
  || PSP      || X ||   ||
  || Pyrex    ||   || X ||
  || * Python || X || X ||
  || * Ruby   || X || X (1) ||
  || Scheme   ||   || X ||
  || Shell    ||   || X ||
  || SQL      || X || X ||
  || Troff    ||   || X ||
  || TCL      ||   || X ||
  || Tex      ||   || X ||
  || Verilog  ||   || X ||
  || VHDL     ||   || X ||
  || Visual Basic |||| X ||
  || VRML     ||   || X ||
  || XML      || X || X ||

  ''(*) Supported as inline code blocks in [wiki:WikiFormatting Wiki text] using WikiProcessors.''

  ''(1) Ruby highlighting is not included in the Enscript distribution.  Highlighting rules for Ruby can be obtained from: http://neugierig.org/software/ruby/

  == Extra Software ==
   * GNU Enscript -- http://people.ssh.fi/mtr/genscript/
   * !SilverCity -- http://silvercity.sf.net/

  ----
  See also: WikiProcessors, WikiFormatting, TracWiki, TracBrowser


name: TracModPython
author: trac
ipnr: 127.0.0.1
text:
  = Trac and mod_python =

  Trac supports [http://www.modpython.org/ mod_python], which speeds up Trac's response times considerably and permits use of many Apache features not possible with [wiki:TracStandalone tracd]/mod_proxy.

  == Simple configuration ==

  If you just installed mod_python, you may have to add a line to load the module in the Apache configuration:
  {{{
  LoadModule python_module modules/mod_python.so
  }}}

  A simple setup of Trac on mod_python looks like this:
  {{{
  <Location /projects/myproject>
     SetHandler mod_python
     PythonHandler trac.web.modpython_frontend 
     PythonOption TracEnv /var/trac/myproject
     PythonOption TracUriRoot /projects/myproject
  </Location>
  }}}

  Note that the option `TracUriRoot` may or may not be necessary in your setup. Try without first, and if the URLs produced by Trac look wrong or if Trac does not seem to recognize the URLs correctly, add the `TracUriRoot` option.

  Configuring authentication works the same as for [wiki:TracCgi#AddingAuthentication CGI]:
  {{{
  <Location "/projects/myproject/login">
    AuthType Basic
    AuthName "myproject"
    AuthUserFile /var/trac/myproject/.htaccess
    Require valid-user
  </Location>
  }}}

  If the Trac installation isn't installed in your Python path, you'll have to tell Apache where to find the Trac mod_python handler  using the `PythonPath` directive:
  {{{
  <Location /projects/myproject>
    ...
    PythonPath "sys.path + ['/path/to/trac']"
    ...
  </Location>
  }}}


  == Setting up multiple projects ==

  The Trac mod_python handler handler supports a configuration option similar to Subversion's `SvnParentPath`, called `TracEnvParentDir`:
  {{{
  <Location /projects>
    SetHandler mod_python
    PythonHandler trac.web.modpython_frontend 
    PythonOption TracEnvParentDir /var/trac
    PythonOption TracUriRoot /projects
  </Location>
  }}}

  When you request the `/projects` URL, you will get a listing of all subdirectories of the directory you set as `TracEnvParentDir`. Selecting any project in the list will bring you to the corresponding Trac environment.

  If you don't want to have the subdirectory listing as your projects home page you can use a
  {{{
  <LocationMatch "/.+/">
  }}}

  This will instruct Apache to use mod_python for all locations different from root while having the possibility of placing a custom home page for root in your !DocumentRoot folder.

  You can also use the same authentication realm for all of the projects using a `<LocationMatch>` directive:
  {{{
  <LocationMatch "/[^/]+/login">
    AuthType Basic
    AuthName "Trac"
    AuthUserFile /var/trac/.htaccess
    Require valid-user
  </LocationMatch>
  }}}

  == Virtual Host Configuration ==

  Below is the sample configuration required to set up your trac as a virtual server (i.e. when you access it at the URLs like
  !http://trac.mycompany.com):

  {{{
  <VirtualHost * >
      DocumentRoot /var/trac/myproject
      ServerName trac.mycompany.com
      <Directory />
          SetHandler mod_python
          PythonHandler trac.web.modpython_frontend
          PythonOption TracEnv /var/trac/myproject
          PythonOption TracUriRoot /
      </Directory>
      <Location /login>
          AuthType Basic
          AuthName "MyCompany Trac Server"
          AuthUserFile /var/trac/myproject/.htusers
          Require valid-user
      </Location>
  </VirtualHost>
  }}}

  == Troubleshooting ==

  === Form submission problems ===

  If you're experiencing problems submitting some of the forms in Trac (a common problem is that you get redirected to the start page after submission), check whether your {{{DocumentRoot}}} contains a folder or file with the same path that you mapped the mod_python handler to. For some reason, mod_python gets confused when it is mapped to a location that also matches a static resource.

  === Using .htaccess ===

  Although it may seem trivial to rewrite the above configuration as a directory in your document root with a `.htaccess` file, this does not work. Apache will append a "/" to any Trac URLs, which interferes with its correct operation.

  It may be possible to work around this with mod_rewrite, but I failed to get this working. In all, it is more hassle than it is worth. Stick to the provided instructions. :)

  === Win32 Issues ===

  If you run trac with mod_python (3.1.3 or 3.1.4) on Windows, 
  uploading attachments will '''not''' work.
  This is a known problem which we can't solve cleanly at the Trac level.

  However, there is a workaround for this at the mod_python level, 
  which is to apply the following patch [http://projects.edgewall.com/trac/attachment/ticket/554/util_py.patch attachment:ticket:554:util_py.patch] 
  to the (Lib/site-packages)/modpython/util.py file.

  If you don't have the `patch` command, that file can be replaced with the [http://svn.apache.org/viewcvs.cgi/httpd/mod_python/trunk/lib/python/mod_python/util.py?rev=103562&view=markup  fixed util.py] (fix which, although done prior to the 3.1.4 release, is ''not'' 
  present in 3.1.4).

  === OS X issues ===

  When using mod_python on OS X you will not be able to restart Apache using `apachectl restart`. This is apparently fixed in mod_python 3.2, but there's also a patch available for earlier versions [http://www.dscpl.com.au/projects/vampire/patches.html here].

  ----
  See also TracGuide, TracInstall, TracCgi, TracFastCgi


name: WikiFormatting
author: trac
ipnr: 127.0.0.1
text:
  = WikiFormatting =
  [[TracGuideToc]]

  Wiki markup is a core feature in Trac, tightly integrating all the other parts of Trac into a flexible and powerful whole.

  Trac has a built in small and powerful wiki rendering engine. This wiki engine implements an ever growing subset of the commands from other popular Wikis,
  especially [http://moinmoin.wikiwikiweb.de/ MoinMoin]. 


  This page demonstrates the formatting syntax available anywhere WikiFormatting is allowed.


  == Font Styles ==

  The Trac wiki supports the following font styles:
  {{{
   * '''bold'''
   * ''italic''
   * '''''bold italic'''''
   * __underline__
   * {{{monospace}}} or `monospace`
   * ~~strike-through~~
   * ^superscript^ 
   * ,,subscript,,
  }}}

  Display:
   * '''bold'''
   * ''italic''
   * '''''bold italic'''''
   * __underline__
   * {{{monospace}}} or `monospace`
   * ~~strike-through~~
   * ^superscript^ 
   * ,,subscript,,

  Note that the `{{{...}}}` and {{{`...`}}} commands not only select a monospace font, but also treat their content as verbatim text, meaning that no further wiki processing is done on this text.

  == Headings ==

  You can create heading by starting a line with one up to five ''equal'' characters ("=")
  followed by a single space and the headline text. The line should end with a space 
  followed by the same number of ''='' characters.

  Example:
  {{{
  = Heading =
  == Subheading ==
  === About ''this'' ===
  }}}

  Display:
  = Heading =
  == Subheading ==
  === About ''this'' ===


  == Paragraphs ==

  A new text paragraph is created whenever two blocks of text are separated by one or more empty lines.

  A forced line break can also be inserted, using:
  {{{
  Line 1[[BR]]Line 2
  }}}
  Display:

  Line 1[[BR]]Line 2


  == Lists ==

  The wiki supports both ordered/numbered and unordered lists.

  Example:
  {{{
   * Item 1
     * Item 1.1
   * Item 2

   1. Item 1
     1. Item 1.1
   1. Item 2
  }}}

  Display:
   * Item 1
     * Item 1.1
   * Item 2

   1. Item 1
     1. Item 1.1
   1. Item 2

  Note that there must be one or more spaces preceding the list item markers, otherwise the list will be treated as a normal paragraph.


  == Definition Lists ==

  The wiki also supports definition lists.

  Example:
  {{{
   llama::
     some kind of mammal, with hair
   ppython::
     some kind of reptile, without hair
     (can you spot the typo?)
  }}}

  Display:
   llama::
     some kind of mammal, with hair
   ppython::
     some kind of reptile, without hair
     (can you spot the typo?)

  Note that you need a space in front of the defined term.


  == Preformatted Text ==

  Block containing preformatted text are suitable for source code snippets, notes and examples. Use three ''curly braces'' wrapped around the text to define a block quote. The curly braces need to be on a separate line.
    
  Example:
  {{{
   {{{
    def HelloWorld():
        print "Hello World"
   }}}
  }}}

  Display:
  {{{
   def HelloWorld():
       print "Hello World"
  }}}


  == Blockquotes ==

  In order to mark a paragraph as blockquote, indent that paragraph with two spaces.

  Example:
  {{{
    This text is a quote from someone else.
  }}}

  Display:
    This text is a quote from someone else.

  == Tables ==

  Simple tables can be created like this:
  {{{
  ||Cell 1||Cell 2||Cell 3||
  ||Cell 4||Cell 5||Cell 6||
  }}}

  Display:
  ||Cell 1||Cell 2||Cell 3||
  ||Cell 4||Cell 5||Cell 6||

  Note that more complex tables can be created using
  [wiki:WikiRestructuredText#BiggerReSTExample reStructuredText].


  == Links ==

  Hyperlinks are automatically created for WikiPageNames and URLs. !WikiPageLinks can be disabled by prepending an exclamation mark "!" character, such as {{{!WikiPageLink}}}.

  Example:
  {{{
   TitleIndex, http://www.edgewall.com/, !NotAlink
  }}}

  Display:
   TitleIndex, http://www.edgewall.com/, !NotAlink

  Links can be given a more descriptive title by writing the link followed by a space and a title and all this inside square brackets.  If the descriptive title is omitted, then the explicit prefix is disguarded, unless the link is an external link. This can be useful for wiki pages not adhering to the WikiPageNames convention.

  Example:
  {{{
   * [http://www.edgewall.com/ Edgewall Software]
   * [wiki:TitleIndex Title Index]
   * [wiki:ISO9000]
  }}}

  Display:
   * [http://www.edgewall.com/ Edgewall Software]
   * [wiki:TitleIndex Title Index]
   * [wiki:ISO9000]


  === Trac Links ===

  Wiki pages can link directly to other parts of the Trac system. Pages can refer to tickets, reports, changesets, milestones, source files and other Wiki pages using the following notations:
  {{{
   * Tickets: #1 or ticket:1
   * Reports: {1} or report:1
   * Changesets: r1, [1] or changeset:1
   * Revision Logs: r1:3, [1:3] or log:branches/0.8-stable#1:3
   * Wiki pages: CamelCase or wiki:CamelCase
   * Milestones: milestone:1.0 or milestone:"End-of-days Release"
   * Files: source:trunk/COPYING
   * Attachments: attachment:"file name.doc"
   * A specific file revision: source:/trunk/COPYING#200
   * A filename with embedded space: source:"/trunk/README FIRST"
  }}}

  Display:
   * Tickets: #1 or ticket:1
   * Reports: {1} or report:1
   * Changesets: r1, [1] or changeset:1
   * Revision Logs: r1:3, [1:3] or log:branches/0.8-stable#1:3
   * Wiki pages: CamelCase or wiki:CamelCase
   * Milestones: milestone:1.0 or milestone:"End-of-days Release"
   * Files: source:trunk/COPYING
   * Attachments: attachment:"file name.doc"
   * A specific file revision: source:/trunk/COPYING#200
   * A filename with embedded space: source:"/trunk/README FIRST"

  See TracLinks for more in-depth information.


  == Escaping Links and WikiPageNames ==

  You may avoid making hyperlinks out of TracLinks by preceding an expression with a single "!" (exclamation mark).

  Example:
  {{{
   !NoHyperLink
   !#42 is not a link
  }}}

  Display:
   !NoHyperLink
   !#42 is not a link


  == Images ==

  Urls ending with `.png`, `.gif` or `.jpg` are automatically interpreted as image links, and converted to `<img>` tags.

  Example:
  {{{
  http://www.edgewall.com/gfx/trac_example_image.png
  }}}

  Display:

  http://www.edgewall.com/gfx/trac_example_image.png

  However, this doesn't give much control over the display mode. This way of inserting images is deprecated in favor of the more powerful `Image` macro (see WikiMacros).


  == Macros ==

  Macros are ''custom functions'' to insert dynamic content in a page.

  Example:
  {{{
   [[Timestamp]]
  }}}

  Display:
   [[Timestamp]]

  See WikiMacros for more information, and a list of installed macros.


  == Processors ==

  Trac supports alternative markup formats using WikiProcessors. For example, processors are used to write pages in 
  [wiki:WikiRestructuredText reStructuredText] or [wiki:WikiHtml HTML]. 

  Example 1:
  {{{
  #!html
  <pre class="wiki">{{{
  #!html
  &lt;h1 style="text-align: right; color: blue"&gt;HTML Test&lt;/h1&gt;
  }}}</pre>
  }}}

  Display:
  {{{
  #!html
  <h1 style="text-align: right; color: blue">HTML Test</h1>
  }}}

  Example:
  {{{
  #!html
  <pre class="wiki">{{{
  #!python
  class Test:
      def __init__(self):
          print "Hello World"
  if __name__ == '__main__':
     Test()
  }}}</pre>
  }}}

  Display:
  {{{
  #!python
  class Test:
      def __init__(self):
          print "Hello World"
  if __name__ == '__main__':
     Test()
  }}}

  Perl:
  {{{
  #!perl
  my ($test) = 0;
  if ($test > 0) {
  echo "hello";
  }
  }}}

  See WikiProcessors for more information.


  == Miscellaneous ==

  Four or more dashes will be replaced by a horizontal line (<HR>)

  Example:
  {{{
   ----
  }}}

  Display:
  ----


  ----
  See also: TracLinks, TracGuide, WikiHtml, WikiMacros, WikiProcessors, TracSyntaxColoring.


name: TracBrowser
author: trac
ipnr: 127.0.0.1
text:
  = The Trac Browser =
  [[TracGuideToc]]

  The Trac browser can be used to browse directories, change logs 
  and specific revisions of files stored in a subversion repository.

  Directory entries are displayed in a list with sortable columns. The list 
  entries can be sorted by ''name'', ''size'' or ''age'' by clicking on the column
  headers. The sort order can be reversed by clicking on a given column
  header again.

  The browser can be used to navigate through the directory structure 
  by clicking on the directory names. Clicking on a file name will show
  the contents of the file. Clicking on the revision number of a file or
  directory will take you to the revision history for that file.

  It's also possible to browse directories or files as they were in history,
  at any given repository revision. The default behavior is to display the
  latest revision but another revision number can easily be selected using
  the ''View revision'' input field at the top of the page.

  == RSS Support ==

  The browser module provided RSS feeds to monitor changes to a file or
  directory. To subscribe to an RSS feed for a file or directory, open its
  revision log in the browser and click the orange 'XML' icon at the bottom
  of the page. For more information on RSS support in Trac, see TracRss.

  ----
  See also: TracGuide, TracChangeset, FineGrainedPermissions


name: WikiRestructuredTextLinks
author: trac
ipnr: 127.0.0.1
text:
  = TracLinks in reStructuredText =

  This document is for testing the ``..trac::`` directive. The page is written like

  {{{
  {{{
  #!rst 

  Examples
  ...
  ...

  }}}
  }}}


  This is a list of example uses of the ''trac'' directive, providing use of TracLinks in WikiRestructuredText.

  {{{
  #!rst

  Examples
  --------

  trac role
  =========
  Syntax is \`link\`\:trac: or :trac:\`link\`, and could be put anywhere in the text. 'link' has the same format as explain for the ``.. trac::`` directive below.

  ``In the middle of my text `WikiFormatting`:trac: see!!!!`` 
     In the middle of my text `WikiFormatting`:trac: see!!!!

  or

  ``In the middle of my text :trac:`WikiFormatting` see!!!!`` 
     In the middle of my text :trac:`WikiFormatting` see!!!!


  wiki
  ====
  ``.. trac:: WikiFormatting``
  	.. trac:: WikiFormatting

  ``.. trac:: wiki:WikiFormatting``
         .. trac:: wiki:WikiFormatting

  ``.. trac:: wiki:WikiFormatting WikiFormatting``
  	.. trac:: wiki:WikiFormatting WikiFormatting

  ``.. trac:: wiki:WikiFormatting LinkText``
  	.. trac:: wiki:WikiFormatting LinkText

  tickets
  =======

  ``.. trac:: #1``
  	.. trac:: #1
  ``.. trac:: #1 ticket one``
  	.. trac:: #1 ticket one
  ``.. trac:: ticket:1``
  	.. trac:: ticket:1
  ``.. trac:: ticket:1 ticket one``
  	.. trac:: ticket:1 ticket one

  reports
  =======

  ``.. trac:: {1}``
  	.. trac:: {1}
  ``.. trac:: {1} report one``
          .. trac:: {1} report one
  ``.. trac:: report:1``
  	.. trac:: report:1
  ``.. trac:: report:1 report one``
  	.. trac:: report:1 report one

  changesets
  ==========

  ``.. trac:: [42]``
  	.. trac:: [42]
  ``.. trac:: [42] changeset 42``
  	.. trac:: [42] changeset 42
  ``.. trac:: changeset:42``
  	.. trac:: changeset:42
  ``.. trac:: changeset:42 changeset 42``
  	.. trac:: changeset:42 changeset 42
  ``.. trac:: foo``
  	.. trac:: foo

  files
  =====

  ``.. trac:: browser:/trunk/trac``
  	.. trac:: browser:/trunk/trac

  The leading ``/`` can be omitted...

  ``.. trac:: repos:trunk/trac trunk/trac``
  	.. trac:: repos:trunk/trac trunk/trac
  ``.. trac:: source:trunk/trac Trac source code``
  	.. trac:: source:trunk/trac Trac source code

  ``.. trac:: browser:trunk/README``
  	.. trac:: browser:trunk/README
  ``.. trac:: repos:trunk/README trunk/README``
  	.. trac:: repos:trunk/README trunk/README
  ``.. trac:: source:trunk/README README in trunk``
  	.. trac:: source:trunk/README README in trunk

  Note that if ``hoo`` is a file, the link targets its revision log. In order to see the file's content, you need to specify the revision explicitely, like here:

  ``.. trac:: browser:/trunk/README#latest latest of trunk/README``
  	.. trac:: browser:/trunk/README#latest latest of trunk/README
  ``.. trac:: repos:trunk/README#42 trunk/README in rev 42``
  	.. trac:: repos:trunk/README#42 trunk/README in rev 42
  }}}

  ----
  See also: WikiRestructuredTextLinks, TracLinks


name: TracNotification
author: trac
ipnr: 127.0.0.1
text:
  = Email Notification of Ticket Changes =
  [[TracGuideToc]]

  Trac supports basic notification for ticket changes using email. 

  Email notification is useful to keep users up-to-date on tickets/issues of interest, and also provides a convenient way to post ticket changes to a dedicated mailing list. '''Note:''' As an example, this is how the [http://lists.edgewall.com/archive/trac-tickets/ Trac-tickets] mailing list works.

  Disabled by default, notification can be activated and configured in [wiki:TracIni trac.ini].

  == Receiving Notification ==
  When reporting a new ticket or adding a comment, enter a valid email address in the ''reporter'', ''editor'' or ''cc'' field. Trac will automatically send you an email when changes are made to the ticket.

  This is useful to keep up-to-date on an issue or enhancement request that interests you.

  == Configuring SMTP Notification ==

  === Configuration Options ===
  These are the available options for the ''[notification]'' section in trac.ini.
   * '''smtp_enabled''': Enable email notification.
   * '''smtp_server''': SMTP server used for notification messages.
   * '''smtp_user''': (''requires [milestone:0.9 0.9]'') user name for authentication SMTP account.
   * '''smtp_password''': (''requires [milestone:0.9 0.9]'') password for authentication SMTP account.
   * '''smtp_from''': Email address to use for ''Sender''-headers in notification emails.
   * '''smtp_replyto''': Email address to use for ''Reply-To''-headers in notification emails.
   * '''smtp_always_cc''': List of email addresses to always send notifications to. ''Typically used to post ticket changes to a dedicated mailing list.''
   * '''always_notify_reporter''':  Always send notifications to any address in the reporter field.
   * '''always_notify_owner''': (''requires [milestone:0.9 0.9]'') Always send notifications to the address in the owner field.

  Either '''smtp_from''' or '''smtp_replyto''' (or both) ''must'' be set, otherwise Trac refuses to send notification mails.

  === Example Configuration ===

  {{{
  [notification]
  smtp_enabled = true
  smtp_server = mail.example.com
  smtp_from = notifier@example.com
  smtp_replyto = myproj@projects.example.com
  smtp_always_cc = ticketmaster@example.com, theboss+myproj@example.com
  }}}

  == Sample Email ==
  {{{
  #42: testing
  ---------------------------+------------------------------------------------
         Id:  42             |      Status:  assigned                
  Component:  report system  |    Modified:  Fri Apr  9 00:04:31 2004
   Severity:  major          |   Milestone:  0.9                     
   Priority:  lowest         |     Version:  0.6                     
      Owner:  anonymous      |    Reporter:  jonas@example.com               
  ---------------------------+------------------------------------------------
  Changes:
    * component:  changset view => search system
    * priority:  low => highest
    * owner:  jonas => anonymous
    * cc:  daniel@example.com =>
           daniel@example.com, jonas@example.com
    * status:  new => assigned

  Comment:
  I'm interested too!

  --
  Ticket URL: <http://example.com/trac/ticket/42>
  My Project <http://myproj.example.com/>
  }}}
  ----
  See also: TracTickets, TracIni, TracGuide


name: TracUnicode
author: trac
ipnr: 127.0.0.1
text:
  = Unicode Support in Trac =
  Trac stores all text using UTF-8 encoding, including text in tickets and wiki pages. 

  As such, it supports most (all?) commonly used character encodings.


  == Examples ==
  Please keep sorted order when you add an entry.

  === Arabic ===
  تراك يقوم بحفظ كل الكلمات باستخدام صيغة UTF-8، بما في ذلك الكلمات المستخدمة في صفحات  التيكت والويكي.

  === Bulgarian ===
  Българският език работи ли?

  === Česky ===
  Čeština v kódování UTF-8, žádný problém.

  === Chinese ===
  Traditional: ''繁體中文, 許功蓋會育''; Simplified: ''简体中文，许功盖会育''

  === English ===
  Yes indeed, Trac supports English. Fully.

  === Français ===
  ''Il est possible d'écrire en Français : à, ç, û, ...''

  === German ===
  Trac-Wiki muß auch deutsche Umlaute richtig anzeigen: ö, ä, ü, ...

  === Greek ===
  Τα Ελληνικά υποστηρίζονται επαρκώς επίσης.

  === Hebrew ===
  אני יכול לאכול זכוכית וזה לא מזיק לי

  === Icelandic ===
  ''Ævar sagði við ömmu sína: Sjáðu hvað ég er stór!''

  === Japanese ===
  ''漢字 ひらがな カタカナ ﾊﾝｶｸｶﾅ''

  === Korean ===
  ''이번에는 한글로 써보겠습니다. 잘 보이나요?''

  === Persian (Farsi) ===
  این یک متن فارسی است ولی از چپ به راست

  === Polish ===
  Pchnąć w tę łódź jeża lub ośm skrzyń fig

  === Portuguese ===
  É possível guardar caracteres especias da língua portuguesa, incluindo o símbolo da moeda européia '€', trema 'ü', crase 'à', agudos 'áéíóú', circunflexos 'âêô', til 'ãõ', cedilha 'ç', ordinais 'ªº', grau '°¹²³'.

  === Russian ===
  Проверка русского языка: кажется работает...

  === Serbian ===
  Podržan, uprkos činjenici da se za njegovo pisanje koriste чак два алфабета.

  === Slovenian ===
  Ta suhi škafec pušča vodo že od nekdaj!

  === Spanish ===
  Esto es un pequeño texto en Español, ahora una con acentó

  === Swedish ===
  ''Räven raskar över isen med luva på.''

  === Thai ===
  Trac แสดงภาษาไทยได้อย่างถูกต้อง!

  === Ukrainian ===
  Перевірка української мови...


name: TracAccessibility
author: trac
ipnr: 127.0.0.1
text:
  = Accessibility Support in Trac =

  Not every user has a graphic environment with a mouse or other pointing device. Some users rely on keyboard, alternative keyboard or voice input to navigate links, activate form controls, etc. In Trac, we work to assure users may interact with devices other than a pointing device.

  Trac supports accessibility keys for the most common operations. On Windows and Linux platforms, press any of the keys listed below in combination with the `<Alt>` key; on a Mac, use the `<ctrl>` key instead.

  ''Note that when using Internet Explorer on Windows, you need to hit enter after having used the access key.''

  == Global Access Keys ==

   * `1` - WikiStart
   * `2` - [wiki:TracTimeline Timeline]
   * `3` - [wiki:TracRoadmap Roadmap]
   * `4` - [wiki:TracSearch Search]
   * `6` - [wiki:TracGuide Trac Guide / Documentation]
   * `7` - [wiki:TracTickets New Ticket]
   * `9` - [../about About Trac]
   * `0` - This page

  ----
  See also: TracGuide


name: TracEnvironment
author: trac
ipnr: 127.0.0.1
text:
  = Trac Storage - The Environment =

  Trac uses a directory structure and a database for storing project data.

  == Creating an Environment ==

  A new Trac environment is created using [wiki:TracAdmin trac-admin]:
  {{{
  $ trac-admin /path/to/projectenv initenv
  }}}

  [wiki:TracAdmin trac-admin] will ask you for the name of the project, the
  database connection string (explained below), and where your subversion
  repository is located.

    ''Note: The web server user will require file system write permission to
  the environment directory and all the files inside. Please remember to set
  the appropriate permissions. The same applies to the Subversion
  repository, although Trac will only require read access as long as you're
  not using the BDB file system.''

  == Database Connection Strings ==

  Since version 0.9, Trac supports both [http://sqlite.org/ SQLite] and
  [http://www.postgresql.org/ PostgreSQL] as database backends.  The default
  is to use SQLite, which is probably sufficient for most projects. The database file
  is then stored in the environment directory, and can easily be
  [wiki:TracBackup backed up] together with the rest of the environment.

  The connection string for an embedded SQLite database is:
  {{{
  sqlite:db/trac.db
  }}}

  If you want to use PostgreSQL instead, you'll have to use a different
  connection string. For example, to connect to a database on the same
  machine called `trac`, that allows access to the user `johndoe` with
  the password `letmein`, use:
  {{{
  postgres://johndoe:letmein@localhost/trac
  }}}

  If PostgreSQL is running on a non-standard port (for example 9342), use:
  {{{
  postgres://johndoe:letmein@localhost:9342/trac
  }}}

  Note that with PostgreSQL you will have to create the database before running
  `trac-admin initenv`.

  == Directory Structure ==

  An environment directory will usually consist of the following files and directories:

   * `README` - Brief description of the environment.
   * `VERSION` - Contains the environment version identifier.
   * `attachments` - Attachments to wiki pages and tickets are stored here.
   * `conf`
     * `trac.ini` - Main configuration file. See TracIni.
   * `db`
     * `trac.db` - The SQLite database (if you're using SQLite).
   * `plugins` - Environment-specific [wiki:TracPlugins plugins] (Python eggs)
   * `templates` - Custom environment-specific templates.
     * `site_css.cs` - Custom CSS rules.
     * `site_footer.cs` - Custom page footer.
     * `site_header.cs` - Custom page header.
   * `wiki-macros` - Environment-specific [wiki:WikiMacros Wiki macros].

  ----
  See also: TracAdmin, TracBackup, TracIni, TracGuide


name: TracReports
author: trac
ipnr: 127.0.0.1
text:
  = Trac Reports =
  [[TracGuideToc]]

  The Trac reports module provides a simple, yet powerful reporting facility
  to present information about tickets in the Trac database.

  Rather than have its own report definition format, TracReports relies on standard SQL
  `SELECT` statements for custom report definition. 

    '''Note:''' ''The report module is being phased out in its current form because it seriously limits the ability of the Trac team to make adjustments to the underlying database schema. We believe that the [wiki:TracQuery query module] is a good replacement that provides more flexibility and better usability. While there are certain reports that cannot yet be handled by the query module, we intend to further enhance it so that at some point the reports module can be completely removed. This also means that there will be no major enhancements to the report module anymore.''

    ''You can already completely replace the reports module by the query module simply be disabling the former in [wiki:TracIni trac.ini]:''
    {{{
    [components]
    trac.ticket.report.* = disabled
    }}}
    ''This will make the query module the default handler for the “View Tickets” navigation item. We encourage you to try this configuration and report back what kind of features of reports you are missing, if any.''

  A report consists of these basic parts:
   * '''ID''' -- Unique (sequential) identifier 
   * '''Title'''  -- Descriptive title
   * '''Description'''  -- A brief description of the report, in WikiFormatting text.
   * '''Report Body''' -- List of results from report query, formatted according to the methods described below.
   * '''Footer''' -- Links to alternative download formats for this report.

  == Changing Sort Order ==
  Simple reports - ungrouped reports to be specific - can be changed to be sorted by any column simply by clicking the column header. 

  If a column header is a hyperlink (red), click the column you would like to sort by. Clicking the same header again reverses the order.


  == Alternate Download Formats ==
  Aside from the default HTML view, reports can also be exported in a number of alternate formats.
  At the bottom of the report page, you will find a list of available data formats. Click the desired link to 
  download the alternate report format.

  === Comma-delimited - CSV (Comma Separated Values) ===
  Export the report as plain text, each row on its own line, columns separated by a single comma (',').
  '''Note:''' Carriage returns, line feeds, and commas are stripped from column data to preserve the CSV structure.

  === Tab-delimited ===
  Like above, but uses tabs (\t) instead of comma.

  === RSS - XML Content Syndication ===
  All reports support syndication using XML/RSS 2.0. To subscribe to an RSS feed, click the orange 'XML' icon at the bottom of the page. See TracRss for general information on RSS support in Trac.

  ----

  == Creating Custom Reports ==

  ''Creating a custom report requires a comfortable knowledge of SQL.''

  A report is basically a single named SQL query, executed and presented by
  Trac.  Reports can be viewed and created from a custom SQL expression directly
  in from the web interface.

  Typically, a report consists of a SELECT-expression from the 'ticket' table,
  using the available columns and sorting the way you want it.

  == Ticket columns ==
  The ''ticket'' table has the following columns:
   * id
   * time
   * changetime
   * component
   * severity  
   * priority 
   * owner
   * reporter
   * cc
   * version
   * milestone
   * status
   * resolution
   * summary
   * description

  See TracTickets for a detailed description of the column fields.

  '''all active tickets, sorted by priority and time'''

  '''Example:''' ''All active tickets, sorted by priority and time''
  {{{
  SELECT id AS ticket, status, severity, priority, owner, 
         time as created, summary FROM ticket 
    WHERE status IN ('new', 'assigned', 'reopened')
    ORDER BY priority, time
  }}}


  ----


  == Advanced Reports: Dynamic Variables ==
  For more flexible reports, Trac supports the use of ''dynamic variables'' in report SQL statements. 
  In short, dynamic variables are ''special'' strings that are replaced by custom data before query execution.

  === Using Variables in a Query ===
  The syntax for dynamic variables is simple, any upper case word beginning with '$' is considered a variable.

  Example:
  {{{
  SELECT id AS ticket,summary FROM ticket WHERE priority='$PRIORITY'
  }}}

  To assign a value to $PRIORITY when viewing the report, you must define it as an argument in the report URL, leaving out the the leading '$'.

  Example:
  {{{
   http://projects.edgewall.com/trac/reports/14?PRIORITY=high
  }}}

  To use multiple variables, separate them with an '&'.

  Example:
  {{{
   http://projects.edgewall.com/trac/reports/14?PRIORITY=high&SEVERITY=critical
  }}}


  === Special/Constant Variables ===
  There is one ''magic'' dynamic variable to allow practical reports, its value automatically set without having to change the URL. 

   * $USER -- Username of logged in user.

  Example (''List all tickets assigned to me''):
  {{{
  SELECT id AS ticket,summary FROM ticket WHERE owner='$USER'
  }}}


  ----


  == Advanced Reports: Custom Formatting ==
  Trac is also capable of more advanced reports, including custom layouts,
  result grouping and user-defined CSS styles. To create such reports, we'll use
  specialized SQL statements to control the output of the Trac report engine.

  == Special Columns ==
  To format reports, TracReports looks for 'magic' column names in the query
  result. These 'magic' names are processed and affect the layout and style of the 
  final report.

  === Automatically formatted columns ===
   * '''ticket''' -- Ticket ID number. Becomes a hyperlink to that ticket. 
   * '''created, modified, date, time''' -- Format cell as a date and/or time.

   * '''description''' -- Ticket description field, parsed through the wiki engine.

  '''Example:'''
  {{{
  SELECT id as ticket, created, status, summary FROM ticket 
  }}}

  === Custom formatting columns ===
  Columns whose names begin and end with 2 underscores (Example: '''_''''''_color_''''''_''') are
  assumed to be ''formatting hints'', affecting the appearance of the row.
   
   * '''_''''''_group_''''''_''' -- Group results based on values in this column. Each group will have its own header and table.
   * '''_''''''_color_''''''_''' -- Should be a numeric value ranging from 1 to 5 to select a pre-defined row color. Typically used to color rows by issue priority.
   * '''_''''''_style_''''''_''' -- A custom CSS style expression to use for the current row. 

  '''Example:''' ''List active tickets, grouped by milestone, colored by priority''
  {{{
  SELECT p.value AS __color__,
       t.milestone AS __group__,
       (CASE owner WHEN 'daniel' THEN 'font-weight: bold; background: red;' ELSE '' END) AS __style__,
         t.id AS ticket, summary
    FROM ticket t,enum p
    WHERE t.status IN ('new', 'assigned', 'reopened') 
      AND p.name=t.priority AND p.type='priority'
    ORDER BY t.milestone, p.value, t.severity, t.time
  }}}

  '''Note:''' A table join is used to match ''ticket'' priorities with their
  numeric representation from the ''enum'' table.

  === Changing layout of report rows ===
  By default, all columns on each row are display on a single row in the HTML
  report, possibly formatted according to the descriptions above. However, it's
  also possible to create multi-line report entries.

   * '''column_''' -- ''Break row after this''. By appending an underscore ('_') to the column name, the remaining columns will be be continued on a second line.

   * '''_column_''' -- ''Full row''. By adding an underscore ('_') both at the beginning and the end of a column name, the data will be shown on a separate row.

   * '''_column'''  --  ''Hide data''. Prepending an underscore ('_') to a column name instructs Trac to hide the contents from the HTML output. This is useful for information to be visible only if downloaded in other formats (like CSV or RSS/XML).

  '''Example:''' ''List active tickets, grouped by milestone, colored by priority, with  description and multi-line layout''

  {{{
  SELECT p.value AS __color__,
         t.milestone AS __group__,
         (CASE owner 
            WHEN 'daniel' THEN 'font-weight: bold; background: red;' 
            ELSE '' END) AS __style__,
         t.id AS ticket, summary AS summary_,             -- ## Break line here
         component,version, severity, milestone, status, owner,
         time AS created, changetime AS modified,         -- ## Dates are formatted
         description AS _description_,                    -- ## Uses a full row
         changetime AS _changetime, reporter AS _reporter -- ## Hidden from HTML output
    FROM ticket t,enum p
    WHERE t.status IN ('new', 'assigned', 'reopened') 
      AND p.name=t.priority AND p.type='priority'
    ORDER BY t.milestone, p.value, t.severity, t.time
  }}}

  === Reporting on custom fields ===

  If you have added custom fields to your tickets (experimental feature in v0.8, see TracTicketsCustomFields), you can write a SQL query to cover them. You'll need to make a join on the ticket_custom table, but this isn't especially easy.

  If you have tickets in the database ''before'' you declare the extra fields in trac.ini, there will be no associated data in the ticket_custom table. To get around this, use SQL's "LEFT OUTER JOIN" clauses. See TracIniReportCustomFieldSample for some examples.

  ----
  See also: TracTickets, TracQuery, TracGuide


name: WikiMacros
author: trac
ipnr: 127.0.0.1
text:
  =  Wiki Macros =
  Trac macros are plugins to extend the Trac engine with custom 'functions' written in Python. A macro inserts dynamic HTML data in any context supporting WikiFormatting.

  Another kind of macros are WikiProcessors. They typically deal with alternate markup formats and representation of larger blocks of information (like source code highlighting).

  == Using Macros ==
  Macro calls are enclosed in two ''square brackets''. Like python functions, macros can also have arguments, a comma separated list within parentheses. 

  === Examples ===

  {{{
   [[Timestamp]]
  }}}
  Display:
   [[Timestamp]]

  {{{
   [[HelloWorld(Testing)]]
  }}}
  Display:
   [[HelloWorld(Testing)]]

  == Available Macros ==

  ''Note that the following list will only contain the macro documentation if you've not enabled `-OO` optimizations, or not set the `PythonOptimize` option for [wiki:TracModPython mod_python].''

  [[MacroList]]

  == Macros from around the world ==
  The [http://projects.edgewall.com/trac/ Trac Project] has a section dedicated to user-contributed macros, [http://projects.edgewall.com/trac/wiki/MacroBazaar MacroBazaar]. If you're looking for new macros, or have written new ones to share with the world, don't hesitate adding it to the [http://projects.edgewall.com/trac/wiki/MacroBazaar MacroBazaar] wiki page.

  ----

  == Developing Custom Macros ==
  Macros, like Trac itself, are written in the [http://www.python.org/ Python programming language]. They are very simple modules, identified by the filename and should contain a single ''entry point'' function. Trac will display the returned data inserted into the HTML where the macro was called.

  It's easiest to learn from an example:
  {{{
  #!python
  # MyMacro.py -- The world's simplest macro

  def execute(hdf, args, env):
      return "Hello World called with args: %s" % args
  }}}

  You can also use the environment (`env`) object, for example to access configuration data and the database, for example:
  {{{
  #!python
  def execute(hdf, txt, env):
      return env.get_config('trac', 'repository_dir')
  }}}

  Note that since version 0.9, wiki macros can also be written as TracPlugins. This gives them some capabilities than “classic” macros do not have, such as directly access the HTTP request.

  For more information about developing macros, see the [http://projects.edgewall.com/trac/wiki/TracDev development resources] on the main project site.

  ----
  See also:  WikiProcessors, WikiFormatting, TracGuide


name: TracCgi
author: trac
ipnr: 127.0.0.1
text:
  = Installing Trac as CGI =

  To install Trac as a CGI script, you need to make the `trac.cgi` executable as a CGI by your web server. If you're using [http://httpd.apache.org/ Apache HTTPD], there are a couple ways to do that:

   1. Use a `ScriptAlias` to map a URL to the `trac.cgi` script
   2. Copy the `trac.cgi` file into the directory for CGI executables used by your web server (commonly named `cgi-bin`). You can also create a symbolic link, but in that case make sure that the `FollowSymLinks` option is enabled for the `cgi-bin` directory.

  The first option is recommended as it also allows you to map the CGI to a friendly URL.

  Now, edit the Apache configuration file and add this snippet, file names and locations changed to match your installation:
  {{{
  ScriptAlias /trac /usr/share/trac/cgi-bin/trac.cgi

  # Trac needs to know where the database is located
  <Location "/trac">
    SetEnv TRAC_ENV "/path/to/projectenv"
  </Location>
  }}}

  This will make Trac available at `http://yourhost.example.org/trac`.

   ''Note: Make sure that the modules mod_alias and mod_env modules are available and enabled in your Apache configuration, otherwise Apache will complain about the above snippet.''

   ''Note: If you are using the [http://httpd.apache.org/docs/suexec.html Apache suEXEC] feature see [http://projects.edgewall.com/trac/wiki/ApacheSuexec ApacheSuexec] (on the main Trac site).''

  == Mapping Static Resources ==

  Out of the box, Trac will serve static resources such as style sheets or images itself. For a CGI setup, though, this is highly undesirable, because it results in the CGI script being invoked for documents that could be more efficiently served by the web server.

  Web servers such as [http://httpd.apache.org/ Apache HTTPD] allow you to create “Aliases” to resources, thereby giving them a virtual URL that doesn't necessarily bear any resemblance to the layout of the servers file system. We already used this capability above when defining a `ScriptAlias` for the CGI script, and we'll use it now to map requests to the static resources to the directory on the file system that contains them, thereby bypassing the processing of such requests by the CGI script.

  Edit the Apache configuration file again and add the following snippet '''before''' the `ScriptAlias` for the CGI script , file names and locations changed to match your installation:
  {{{
  Alias /trac/chrome/common /usr/share/trac/htdocs
  <Directory "/usr/share/trac/htdocs">
    Order allow,deny
    Allow from all
  </Directory>
  }}}

  Note that whatever URL path you mapped the `trac.cgi` script to, the path `/chrome/common` is the path you have to append to that location to intercept requests to the static resources. 

  For example, if Trac is mapped to `/cgi-bin/trac.cgi` on your server, the URL of the Alias should be `/cgi-bin/trac.cgi/chrome/common`.

  Alternatively, you can set the `htdocs_location` configuration option in [wiki:TracIni trac.ini]:
  {{{
  [trac]
  htdocs_location = /trac-htdocs
  }}}

  Trac will then use this URL when embedding static resources into HTML pages. Of course, you still need to make the Trac `htdocs` directory available through the web server at the specified URL, for example by copying (or linking) the directory into the document root of the web server.

  == Adding Authentication ==

  The simplest way to enable authentication with Apache is to create a password file. Use the `htpasswd` program to create the password file:
  {{{
  $ htpasswd -c /somewhere/trac.htpasswd admin
  New password: <type password>
  Re-type new password: <type password again>
  Adding password for user admin
  }}}

  After the first user, you dont need the "-c" option anymore:
  {{{
  $ htpasswd /somewhere/trac.htpasswd john
  New password: <type password>
  Re-type new password: <type password again>
  Adding password for user john
  }}}

    ''See the man page for `htpasswd` for full documentation.''

  After you've created the users, you can set their permissions using TracPermissions.

  Now, you'll need to enable authentication against the password file in the Apache configuration:
  {{{
  <Location "/cgi-bin/trac.cgi/login">
    AuthType Basic
    AuthName "Trac"
    AuthUserFile /somewhere/trac.htpasswd
    Require valid-user
  </Location>
  }}}

  For better security, it is recommended that you either enable SSL or at least use the “Digest” authentication scheme instead of “Basic”. Please read the [http://httpd.apache.org/docs/2.0/ Apache HTTPD documentation] to find out more.

  ----
  See also:  TracGuide, TracInstall, TracFastCgi, TracModPython


name: CamelCase
author: trac
ipnr: 127.0.0.1
text:
  = !CamelCase =
  New words created by smashing together capitalized words.

  CamelCase is the original wiki convention for creating hyperlinks, with the additional requirement that the capitals are followed by a lower-case letter; hence “AlabamA” and “ABc” will not be links.

  == More information on !CamelCase ==

   * http://c2.com/cgi/wiki?WikiCase
   * http://en.wikipedia.org/wiki/CamelCase

  ----
  See also: WikiPageNames, WikiNewPage, WikiFormatting, TracWiki


name: WikiProcessors
author: trac
ipnr: 127.0.0.1
text:
  = Wiki Processors =
  Processors are WikiMacros designed to provide alternative markup formats for the Trac Wiki engine. Processors can be thought of as ''macro functions to process user-edited text''. 

  The wiki engine uses processors to allow using [wiki:WikiRestructuredText Restructured Text] and [wiki:WikiHtml raw HTML] in any wiki text throughout Trac.

  == Using Processors ==
  To use a processor on a block of text, use a wiki blockquote, selecting a processor by name using ''shebang notation'' (#!), familiar to most UNIX users from scripts.

  '''Example 1''' (''inserting raw HTML in a wiki text''):

  {{{
  #!html
  <pre class="wiki">{{{
  #!html
  &lt;h1 style="color: orange"&gt;This is raw HTML&lt;/h1&gt;
  }}}</pre>
  }}}

  '''Results in:'''
  {{{
  #!html
  <h1 style="color: orange">This is raw HTML</h1>
  }}}

  ----

  '''Example 2''' (''inserting Restructured Text in wiki text''):

  {{{
  #!html
  <pre class="wiki">{{{
  #!rst
  A header
  --------
  This is some **text** with a footnote [*]_.

  .. [*] This is the footnote.
  }}}</pre>
  }}}

  '''Results in:'''
  {{{
  #!rst
  A header
  --------
  This is some **text** with a footnote [*]_.

  .. [*] This is the footnote.
  }}}
  ----
  '''Example 3''' (''inserting a block of C source code in wiki text''):

  {{{
  #!html
  <pre class="wiki">{{{
  #!c
  int main(int argc, char *argv[])
  {
    printf("Hello World\n");
    return 0;
  }
  }}}</pre>
  }}}

  '''Results in:'''
  {{{
  #!c
  int main(int argc, char *argv[])
  {
    printf("Hello World\n");
    return 0;
  }
  }}}

  ----

  == Available Processors ==
  The following processors are included in the Trac distribution:
   * '''html''' -- Insert custom HTML in a wiki page. See WikiHtml.
   * '''rst''' -- Trac support for Restructured Text. See WikiRestructuredText.
   * '''textile''' -- Supported if  [http://dealmeida.net/projects/textile/ Textile] is installed.

  === Code Highlighting Support ===
  Trac includes processors to provide inline [wiki:TracSyntaxColoring syntax highlighting] for the following languages:
   * '''c''' -- C
   * '''cpp''' -- C++
   * '''python''' -- Python
   * '''perl''' -- Perl
   * '''ruby''' -- Ruby
   * '''php''' -- PHP
   * '''asp''' --- ASP
   * '''sql''' -- SQL
   * '''xml''' -- XML
  '''Note:''' ''Trac relies on external software packages for syntax coloring. See TracSyntaxColoring for more info.''

  By using the MIME type as processor, it is possible to syntax-highlight the same languages that are supported when browsing source code. For example, you can write:
  {{{
  {{{
  #!text/html
  <h1>text</h1>
  }}}
  }}}

  The result will be syntax highlighted HTML code. The same is valid for all other mime types supported.


  For more processor macros developed and/or contributed by users, visit: 
   * [http://projects.edgewall.com/trac/wiki/ProcessorBazaar ProcessorBazaar]
   * [http://projects.edgewall.com/trac/wiki/MacroBazaar MacroBazaar]


  == Advanced Topics: Developing Processor Macros ==
  Developing processors is no different than WikiMacros. In fact they work the same way, only the usage syntax differs. See WikiMacros for more information.

  '''Example:''' (''Restructured Text Processor''):
  {{{
  from docutils.core import publish_string

  def execute(hdf, text, env):
      html = publish_string(text, writer_name = 'html')
      return html[html.find('<body>')+6:html.find('</body>')].strip()
  }}}

  ----
  See also: WikiMacros, WikiHtml, WikiRestructuredText, TracSyntaxColoring, WikiFormatting, TracGuide


name: TracSearch
author: trac
ipnr: 127.0.0.1
text:
  = Using Search =

  Trac has a built-in search engine to allow finding occurrences of keywords and substrings in wiki pages, tickets and changeset descriptions.

  Using the Trac search facility is straightforward and its interface should be familiar to most www users.

  Apart from the [search: Search module], you will also find a small search field above the navigation bar at all time. It provides convenient access to the search module from all pages.

  == Quickjumps ==
  For intermediate and advanced use, Trac has a useful way to quickly navigate to a given resource, named '''quickjumps'''.

  If you enter a [wiki:TracLinks TracLink] in the search field above the navigation bar, Trac will recognize this and assume you know where you're going. 

  For example:

   * ![42] -- Opens change set 42
   * !#42 -- Opens ticket number 42
   * !{1} -- Opens report 1

  '''Note:''' ''This is a particularly useful feature to quickly navigate to a specific issue ticket or changeset.''

  === Advanced: Disabling Quickjumps ===
  To disable the quickjump feature for a search keyword - for example when searching for occurences of the literal word !TracGuide - begin the query with an exclamation mark (!).

  ----
  See also: TracGuide, TracLinks, TracQuery


name: TracQuery
author: trac
ipnr: 127.0.0.1
text:
  = Trac Ticket Queries =
  [[TracGuideToc]]

  In addition to [wiki:TracReports reports], Trac provides support for ''custom ticket queries'', used to display lists of tickets meeting a specified set of criteria. 

  To configure and execute a custom query, switch to the ''View Tickets'' module from the navigation bar, and select the ''Custom Query'' link.

  == Filters ==
  When you first go to the query page the default filters will display all open tickets, or if you're logged in it will display open tickets assigned to you.  Current filters can be removed by clicking the button to the right with the minus sign on the label.  New filters are added from the pulldown list in the bottom-right corner of the filters box.  Filters with either a text box or a pulldown menu of options can be added multiple times to perform an ''or'' of the criteria.

  You can use the fields just below the filters box to group the results based on a field, or display the full description for each ticket.

  Once you've edited your filters click the ''Update'' button to refresh your results.

  == Navigating Tickets ==
  Clicking on one of the query results will take you to that ticket.  You can navigate through the results by clicking the ''Next Ticket'' or ''Previous Ticket'' links just below the main menu bar, or click the ''Back to Query'' link to return to the query page.  

  You can safely edit any of the tickets and continue to navigate through the results using the ''Next/Previous/Back to Query'' links after saving your results.  When you return to the query any tickets you edited will be displayed with italicized text.  If one of the tickets was edited such that it no longer matches the query criteria the text will also be greyed.  The query results can be refreshed and cleared of these status indicators by clicking the ''Update'' button again.

  == Saving Queries ==

  While Trac does not yet allow saving a named query and somehow making it available in a navigable list, you can save references to queries in Wiki content, as described below.

  === Using TracLinks ===

  You may want to save some queries so that you can come back to them later.  You can do this by making a link to the query from any Wiki page.
  {{{
  [query:status=new|assigned|reopened&version=0.8 Active tickets against 0.8]
  }}}

  Which is displayed as:
    [query:status=new|assigned|reopened&version=0.8 Active tickets against 0.8]

  This uses a very simple query language to specify the criteria (see [wiki:TracQuery#QueryLanguage Query Language]).

  Alternatively, you can copy the query string of a query and paste that into the Wiki link, including the leading `?` character:
  {{{
  [query:?status=new&status=assigned&status=reopened&group=owner Assigned tickets by owner]
  }}}

  Whis is displayed as:
    [query:?status=new&status=assigned&status=reopened&group=owner Assigned tickets by owner]

  The advantage of this approach is that you can also specify the grouping and ordering, which is not possible using the first syntax.

  === Using the `[[TicketQuery]]` Macro ===

  The `[[TicketQuery]]` macro lets you display lists of tickets matching certain criteria anywhere you can use WikiFormatting.

  Example:
  {{{
  [[TicketQuery(version=0.9b1|0.9b2&resolution=duplicate)]]
  }}}

  This is displayed as:
    [[TicketQuery(version=0.9b1|0.9b2&resolution=duplicate)]]

  Just like the [wiki:TracQuery#UsingTracLinks query: wiki links], the parameter of this macro expects a query string formatted according to the rules of the simple [wiki:TracQuery#QueryLanguage ticket query language].

  A more compact representation without the ticket summaries is also available:
  {{{
  [[TicketQuery(version=0.9b1|0.9b2&resolution=duplicate, compact)]]
  }}}

  This is displayed as:
    [[TicketQuery(version=0.9b1|0.9b2&resolution=duplicate, compact)]]

  === Query Language ===

  `query:` TracLinks and the `[[TicketQuery]]` macro both use a mini “query language” for specifying query filters. Basically, the filters are separate by ampersands (`&`). Each filter then consists of the ticket field name, an operator, and one or more values. More than one value are separated by a pipe (`|`), meaning that the filter matches any of the values.

  The available operators are:
  || '''=''' || the field content exactly matches the one of the values ||
  || '''~=''' || the field content contains one or more of the values ||
  || '''!^=''' || the field content starts with one of the values ||
  || '''$=''' || the field content ends with one of the values ||

  All of these operators can also be negated:
  || '''!=''' || the field content matches none of the values ||
  || '''!~=''' || the field content does not contain any of the values ||
  || '''!!^=''' || the field content does not start with any of the values ||
  || '''!$=''' || the field content does not end with any of the values ||

  ----
  See also: TracTickets, TracReports, TracGuide


name: WikiStart
author: trac
ipnr: 127.0.0.1
text:
  = Welcome to Trac 0.9.5 =

  Trac is a '''minimalistic''' approach to '''web-based''' management of
  '''software projects'''. Its goal is to simplify effective tracking and handling of software issues, enhancements and overall progress.

  All aspects of Trac have been designed with the single goal to 
  '''help developers write great software''' while '''staying out of the way'''
  and imposing as little as possible on a team's established process and
  culture.

  As all Wiki pages, this page is editable, this means that you can
  modify the contents of this page simply by using your
  web-browser. Simply click on the "Edit this page" link at the bottom
  of the page. WikiFormatting will give you a detailed description of
  available Wiki formatting commands.

  "[wiki:TracAdmin trac-admin] ''yourenvdir'' initenv" created
  a new Trac environment, containing a default set of wiki pages and some sample
  data. This newly created environment also contains 
  [wiki:TracGuide documentation] to help you get started with your project.

  You can use [wiki:TracAdmin trac-admin] to configure
  [http://trac.edgewall.com/ Trac] to better fit your project, especially in
  regard to ''components'', ''versions'' and ''milestones''. 


  TracGuide is a good place to start.

  Enjoy! [[BR]]
  ''The Trac Team''

  == Starting Points ==

   * TracGuide --  Built-in Documentation
   * [http://projects.edgewall.com/trac/ The Trac project] -- Trac Open Source Project
   * [http://projects.edgewall.com/trac/wiki/TracFaq Trac FAQ] -- Frequently Asked Questions
   * TracSupport --  Trac Support

  For a complete list of local wiki pages, see TitleIndex.

  Trac is brought to you by [http://www.edgewall.com/ Edgewall Software],
  providing professional Linux and software development services to clients
  worldwide. Visit http://www.edgewall.com/ for more information.


name: TracLogging
author: trac
ipnr: 127.0.0.1
text:
  = Trac Logging =
  [[TracGuideToc]]

  Trac supports logging of system messages using the standard [http://docs.python.org/lib/module-logging.html logging module] that comes with Python.

  Logging is configured in the {{{[logging]}}} section in [wiki:TracIni trac.ini].

  == Supported Logging Methods ==

  The log method is set using the `log_type` configuration option, which takes any of the following values:
   '''none'':: Suppress all log messages.
   '''file''':: Log messages to a file, specified with the `log_file` option in [wiki:TracIni trac.ini]. 
   '''stderr''':: Output all log entries to console ([wiki:TracStandalone tracd] only).
   '''syslog''':: (UNIX) Send messages to local syslogd via named pipe `/dev/log`.
   '''eventlog''':: (Windows) Use the system's NT eventlog for Trac logging.

  == Log Levels ==

  The verbosity level of logged messages can be set using the ''log_level'' directive in [wiki:TracIni trac.ini]. The log level defines the minimum level of urgency required for a message to be logged.

  The levels are:
   '''CRITICAL''':: Log only the most critical (typically fatal) errors.
   '''ERROR''':: Log failures, bugs and errors. 
   '''WARN''':: Log warnings, non-interrupting events.
   '''INFO''':: Diagnostic information, log information about all processing.
   '''DEBUG''':: Trace messages, profiling, etc.

  ----
  See also: TracIni, TracGuide, TracEnvironment


name: SandBox
author: trac
ipnr: 127.0.0.1
text:
  = The Sandbox =

  This is just a page to practice and learn WikiFormatting. 

  Go ahead, edit it freely.


name: TracStandalone
author: trac
ipnr: 127.0.0.1
text:
  = Tracd =

  Tracd is a lightweight standalone Trac web server. In most cases it's easier to setup and runs faster than the [wiki:TracCgi CGI script].

  == Pros ==

   * Fewer dependencies: You don't need to install apache or any other web-server.
   * Fast: Should be as fast as the [wiki:TracModPython mod_python] version (and much faster than the [wiki:TracCgi CGI]).

  == Cons ==

   * Less features: Tracd implements a very simple web-server and is not as configurable as Apache HTTPD.
   * No native HTTPS support: [http://www.rickk.com/sslwrap/ sslwrap] can be used instead,
     or [http://lists.edgewall.com/archive/trac/2005-August/004381.html STUNNEL].

  == Usage examples ==

  A single project on port 8080. (http://localhost:8080/)
  {{{
   $ tracd -p 8080 /path/to/project
  }}}
  With more than one project. (http://localhost:8080/project1/ and http://localhost:8080/project2/)
  {{{
   $ tracd -p 8080 /path/to/project1 /path/to/project2
  }}}

  You can't have the last portion of the path identical between the projects since that's how trac keeps the URLs of the
  different projects unique. So if you use /project1/path/to and /project2/path/to, you will only see the second project.

  == Using Authentication ==

  Tracd provides support for both Basic and Digest authentication. The default is to use Digest; to use Basic authentication, replace `--auth` with `--basic-auth` in the examples below, and omit the realm.

  If the file `/path/to/users.htdigest` contain user accounts for project1 with the realm "mycompany.com", you'd use the following command-line to start tracd:
  {{{
   $ tracd -p 8080 --auth project1,/path/to/users.htdigest,mycompany.com /path/to/project1
  }}}
  ''Note that the project “name” passed to the `--auth` option is actually the base name of the project environment directory.""

  Of course, the digest file can be be shared so that it is used for more than one project:
  {{{
   $ tracd -p 8080 \
     --auth project1,/path/to/users.htdigest,mycompany.com \
     --auth project2,/path/to/users.htdigest,mycompany.com \
     /path/to/project1 /path/to/project2
  }}}

  == Generating Passwords Without Apache ==

  If you don't have Apache available, you can use this simple Python script to generate your passwords:

  {{{
  from optparse import OptionParser
  import md5

  # build the options
  usage = "usage: %prog [options]"
  parser = OptionParser(usage=usage)
  parser.add_option("-u", "--username",action="store", dest="username", type = "string",
                    help="the username for whom to generate a password")
  parser.add_option("-p", "--password",action="store", dest="password", type = "string",
                    help="the password to use")
  (options, args) = parser.parse_args()

  # check options
  if (options.username is None) or (options.password is None):
     parser.error("You must supply both the username and password")
     
  # Generate the string to enter into the htdigest file
  realm = 'trac'
  kd = lambda x: md5.md5(':'.join(x)).hexdigest()
  print ':'.join((options.username, realm, kd([options.username, realm, options.password])))
  }}}

  ----
  See also: TracInstall, TracCgi, TracModPython, TracGuide


name: TracLinks
author: trac
ipnr: 127.0.0.1
text:
  = Trac Links =
  As you might have guessed, TracLinks are a very fundamental feature of Trac.

  They allow hyperlinking between Trac entities (tickets, reports, changesets, Wiki
  pages, milestones and source files) from anywhere WikiFormatting is used.

  TracLinks are generally of the form '''type:id''' (where ''id'' represents the
  number, name or path of the item) though some frequently used kinds of items
  also have short-hand notations.

  Some examples:
   * Tickets: '''!#1''' or '''!ticket:1'''
   * Reports: '''!{1}''' or '''!report:1'''
   * Changesets: '''!r1''', '''![1]''' or '''!changeset:1'''
   * Revision log: '''!r1:3''', '''![1:3]''' or '''!log:#1:3'''
   * Wiki pages: '''CamelCase''' or '''!wiki:CamelCase'''
   * Milestones: '''!milestone:1.0'''
   * Attachment: '''!attachment:ticket:944:attachment.1073.diff'''
   * Files: '''!source:trunk/COPYING'''
   * A specific file revision: '''!source:/trunk/COPYING#200'''
  Display:
   * Tickets: #1 or ticket:1
   * Reports: {1} or report:1
   * Changesets: r1, [1] or changeset:1
   * Differences: r1:3, [1:3] or log:#1:3
   * Wiki pages: CamelCase or wiki:CamelCase
   * Milestones: milestone:1.0
   * Files: source:trunk/COPYING
   * Attachment: attachment:ticket:944:attachment.1073.diff
   * A specific file revision: source:/trunk/COPYING#200

  '''Note:''' The wiki:CamelCase form is rarely used, but it can be convenient to refer to
  pages whose names do not follow WikiPageNames rules, i.e., single words,
  non-alphabetic characters, etc.

  Trac links using the full (non-shorthand) notation can also be given a custom
  link title like this:

  {{{
  [ticket:1 This is a link to ticket number one].
  }}}

  Display: [ticket:1 This is a link to ticket number one].

  If the title is be omitted, only the id (the part after the colon) is displayed:

  {{{
  [ticket:1]
  }}}

  Display: [ticket:1]

  It might seem a simple enough concept at a glance, but actually allows quite a complex network of information. In practice, it's very intuitive and simple to use, and we've found the "link trail" extremely helpful to better understand what's happening in a project or why a particular change was made.

  == attachement: links ==

  The link syntax for attachments is as follows:
   * !attachment:the_file.txt creates a link to the attachment the_file.txt of the current object
   * !attachment:wiki:MyPage:the_file.txt creates a link to the attachment the_file.txt of the !MyPage wiki page
   * !attachment:ticket:753:the_file.txt creates a link to the attachment the_file.txt of the ticket 753 !attachment:wiki:MyPage:the_file.txt

  == source: links ==

  The default behavior for a source:/some/path link is to open the directory browser 
  if the path points to a directory and otherwise open the log view. 
  It's also possible to link directly to a specific revision of a file like this: source:/some/file@123 
  or like this to link to the latest revision: source:/some/file@latest.
  If the revision is specified, one can even link to a specific line number: !source:/some/file@123#L10 
  [[comment(TODO: remove the ! when Edgewall Trac is upgraded with the support for the line syntax)]]

  == Quoting space in TracLinks ==

  The usual syntax for quoting space is:

   * !attachment:'the file.txt' or
   * !attachment:"the file.txt" 

  == Where to use TracLinks ==
  You can use TracLinks in:

   * Source code (Subversion) commit messages
   * Wiki pages
   * Full descriptions for tickets, reports and milestones

  and any other text fields explicitly marked as supporting WikiFormatting.

  == Escaping Links ==

  To prevent parsing of a !TracLink, you can escape it by preceding it with a '!' (exclamation mark).
  {{{
   !NoLinkHere.
   ![42] is not a link either.
  }}}

  Display:
   !NoLinkHere.
   ![42] is not a link either.

  ----
  See also: WikiFormatting, TracWiki
   


name: TracPlugins
author: trac
ipnr: 127.0.0.1
text:
  = Trac Plugins =
  [[TracGuideToc]]

  Since version 0.9, Trac supports plugins that extend the built-in functionality. The plugin functionality is based on the [http://projects.edgewall.com/trac/wiki/TracDev/ComponentArchitecture component architecture].

  == Requirements ==

  To use plugins in Trac, you need to have [http://peak.telecommunity.com/DevCenter/setuptools setuptools] (version 0.6) installed.

  To install `setuptools`, download the bootstrap module [http://peak.telecommunity.com/dist/ez_setup.py ez_setup.py] and execute it as follows:
  {{{
  $ python ez_setup.py
  }}}

  If the `ez_setup.py` script fails to install the setuptools release, you can download it from [http://www.python.org/pypi/setuptools PyPI] and install it manually.

  == Installing a Trac Plugin ==

  === For a Single Project ===

  Plugins are packaged as [http://peak.telecommunity.com/DevCenter/PythonEggs Python eggs]. That means they are ZIP archives with the file extension `.egg`. If you have downloaded a source distribution of a plugin, you can run:
  {{{
  $ python setup.py bdist_egg
  }}}
  to build the `.egg` file.

  Once you have the plugin archive, you need to copy it into the `plugins` directory of the [wiki:TracEnvironment project environment]. Also, make sure that the web server has sufficient permissions to read the plugin egg.

  === For All Projects ===

  Plugins that you want to use in all your projects (such as [http://projects.edgewall.com/trac/wiki/WebAdmin WebAdmin]) can be installed globally by running:
  {{{
  $ python setup.py install
  }}}

  Alternatively, you can just drop the `.egg` file in the Python `site-packages` directory.

  Unlike plugins installed per-environment, you'll have to explicitly enable globally installed plugins via [wiki:TracIni trac.ini]. This is done in the `[components]` section of the configuration file, for example:
  {{{
  [components]
  webadmin.* = enabled
  }}}

  The name of the option is the Python package of the plugin. This should be specified in the documentation of the Plugin, but can also be easily find out by looking at the source (look for a top-level directory that contains a file named `__init__.py`.)

  == Setting up the Plugin Cache ==

  Some plugins will need to be extracted by the Python eggs runtime (`pkg_resources`), so that their contents are actual files on the file system. The directory in which they are extracted defaults to the home directory of the current user, which may or may not be a problem. You can however override the default location using the `PYTHON_EGG_CACHE` environment variable.

  To do this from the Apache configuration, use the `SetEnv` directive as follows:
  {{{
  SetEnv PYTHON_EGG_CACHE /path/to/dir
  }}}

  This works whether your using the [wiki:TracCgi CGI] or the [wiki:TracModPython mod_python] front-end. Put this directive next to where you set the path to the [wiki:TracEnvironment Trac environment], i.e. in the same `<Location>` block.

  For example (for CGI):
  {{{
   <Location /trac>
     SetEnv TRAC_ENV /path/to/projenv
     SetEnv PYTHON_EGG_CACHE /path/to/dir
   </Location>
  }}}

  or (for mod_python):
  {{{
   <Location /trac>
     SetHandler mod_python
     ...
     SetEnv PYTHON_EGG_CACHE /path/to/dir
   </Location>
  }}}

  For [wiki:TracFastCgi FastCGI], you'll need to `-initial-env` option, or whatever is provided by your web server for setting environment variables.

  ----
  See also TracGuide, [http://projects.edgewall.com/trac/wiki/PluginList plugin list], [http://projects.edgewall.com/trac/wiki/TracDev/ComponentArchitecture component architecture]


name: TracRoadmap
author: trac
ipnr: 127.0.0.1
text:
  = The Trac Roadmap =
  [[TracGuideToc]]

  The roadmap provides a view on the [wiki:TracTickets ticket system] that helps planning and managing the future development of a project.

  == The Roadmap View ==

  Basically, the roadmap is just a list of future milestones. You can add a description to milestones (using WikiFormatting) describing main objectives, for example. In addition, tickets targeted for a milestone are aggregated, and the ratio between active and resolved tickets is displayed as a milestone progress bar.

  == The Milestone View ==

  It is possible to drill down into this simple statistic by viewing the individual milestone pages. By default, the active/resolved ratio will be grouped and displayed by component. You can also regroup the status by other criteria, such as ticket owner or severity. Ticket numbers are linked to [wiki:TracQuery custom queries] listing corresponding tickets.

  == Roadmap Administration ==

  It is possible to add, modify and remove milestones using either TracAdmin or the web interface. 

  '''Note:''' Milestone descriptions can currently only be edited from the web interface. With appropriate permissions, you'll see buttons for milestone management on the roadmap and milestone pages.

  == iCalendar Support ==

  The Roadmap supports the [http://www.ietf.org/rfc/rfc2445.txt iCalendar] format to keep track of planned milestones and related tickets from your favorite calendar software. Calendar applications supporting the iCalendar specification include [http://www.apple.com/ical/ Apple iCal] for Mac OS X and the cross-platform [http://www.mozilla.org/projects/calendar/ Mozilla Calendar]. [http://kdepim.kde.org/components/korganizer.php Korganiser] (the calendar application of the [http://www.kde.org/ KDE] project) and [http://www.novell.com/de-de/products/desktop/features/evolution.html Evolution] also support iCalendar.

  To subscribe to the roadmap, copy the iCalendar link from the roadmap (found at the bottom of the page) and choose the "Subscribe to remote calendar" action (or similar) of your calendar application, and insert the URL just copied.

  '''Note:''' For tickets to be included in the calendar as tasks, you need to be logged in when copying the link. You will only see tickets assigned to yourself, and associated with a milestone.

  More information about iCalendar can be found at [http://en.wikipedia.org/wiki/ICalendar Wikipedia].
  ----
  See also: TracTickets, TracReports, TracQuery, TracGuide


name: TracUpgrade
author: trac
ipnr: 127.0.0.1
text:
  = Upgrade Instructions =
  [[TracGuideToc]]

  A Trac environment sometimes needs to be upgraded before it can be used with a new version of Trac. This document describes the steps necessary to upgrade an environment.

   '''Note''': ''Environment upgrades are not necessary for minor version releases unless otherwise noted. For example, there's no need to upgrade a Trac environment created with (or upgraded) 0.8.0 when installing 0.8.4 (or any other 0.8.x release).''

  == General Instructions ==

  Typically, there are four steps involved in upgrading to a newer version of Trac:

  === Update the Trac Code ===

  Get the new version of Trac, either by downloading an offical release package or by checking it out from the [http://projects.edgewall.com/trac/wiki/SubversionRepository Subversion repository].

  If you have a source distribution, you need to run
  {{{
  python setup.py install
  }}}

  to install the new version. If you've downloaded the Windows installer, you execute it, and so on.

  In any case, if you're doing a major version upgrade (such as from 0.8 to 0.9), it is ''highly'' recommended that you first remove the existing Trac code. To do this, you need to delete the `trac` directory from the Python `lib/site-packages` directory. You may also want to remove the Trac `cgi-bin`, `htdocs` and `templates` directories that are commonly found in a directory called `share/trac` (the exact location depends on your platform).

  === Upgrade the Trac Environment ===

  Unless noted otherwise, upgrading between major versions (such as 0.8 and 0.9) involves changes to the database schema, and possibly the layout of the [wiki:TracEnvironment environment directory]. Fortunately, Trac provides automated upgrade scripts to ease the pain. These scripts are run via [wiki:TracAdmin trac-admin]:
  {{{
  trac-admin /path/to/projenv upgrade
  }}}

  This command will do nothing if the environment is already up-to-date.

  Note that if you are using a PostgreSQL database, this command will fail with the message that the environment can only be backed up when you use an SQLite database. This means that you will have to backup the repository and the database manually. Then, to perform the actual upgrade, run:
  {{{
  trac-admin /path/to/projenv upgrade --no-backup
  }}}

  === Update the Trac Documentation ===

  Every [wiki:TracEnvironment Trac environment] includes a copy of the Trac documentation for the installed version. As you probably want to keep the included documentation in sync with the installed version of Trac, [wiki:TracAdmin trac-admin] provides a command to upgrade the documentation:
  {{{
  trac-admin /path/to/projenv wiki upgrade
  }}}

  Note that this procedure will of course leave your `WikiStart` page intact.

  === Restart the Web Server ===

  In order to reload the new Trac code you will need to restart your web server (note this is not necessary for [wiki:TracCgi CGI]).

  == Specific Versions ==

  The following sections discuss any extra actions that may need to be taken to upgrade to specific versions of Trac.

  == From 0.9-beta to 0.9 ==

  If inclusion of the static resources (style sheets, javascript, images) is not working, check the value of the `htdocs_location` in trac.ini. For [wiki:TracModPython mod_python], [wiki:TracStandalone Tracd] and [wiki:TracFastCgi FastCGI], you can simply remove the option altogether. For [wiki:TracCgi CGI], you should fix it to point to the URL you mapped the Trac `htdocs` directory to (although you can also remove it and then [wiki:TracCgi#MappingStaticResources map the static resources]). If you're still having problems after removing the option, check the paths in the `trac/siteconfig.py` file and fix them if they're incorrect.

  If you've been using plugins with a beta release of Trac 0.9, or have disabled some of the built-in components, you might have to update the rules for disabling/enabling components in [wiki:TracIni trac.ini]. In particular, globally installed plugins now need to be enabled explicitly. See TracPlugins and TracIni for more information.

  If you want to enable the display of all ticket changes in the timeline (the “Ticket Details” option), you now have to explicitly enable that in [wiki:TracIni trac.ini], too:

  {{{
  [timeline]
  ticket_show_details = true
  }}}

  == From 0.8.x to 0.9 ==

  [wiki:TracModPython mod_python] users will also need to change the name of the mod_python handler in the Apache HTTPD configuration:
  {{{
     from: PythonHandler trac.ModPythonHandler
     to:   PythonHandler trac.web.modpython_frontend
  }}}

  If you have [http://initd.org/tracker/pysqlite PySQLite] 2.x installed, Trac will now try to open your SQLite database using the SQLite 3.x file format. The database formats used by SQLite 2.8.x and SQLite 3.x are incompatible. If you get an error like ''“file is encrypted or is not a database”'' after upgrading, then you must convert your database file.

  To do this, you need to have both SQLite 2.8.x and SQLite 3.x installed (they have different filenames so can coexist on the same system). Then use the following commands:
  {{{
   $ mv trac.db trac2.db
   $ sqlite trac2.db .dump | sqlite3 trac.db
  }}}

  After testing that the conversion was successful, the `trac2.db` file can be deleted. For more information on the SQLite upgrade see http://www.sqlite.org/version3.html.

  == From 0.7.x to 0.8 ==

  0.8 adds a new roadmap feature which requires additional permissions. While a
  fresh installation will by default grant ROADMAP_VIEW and MILESTONE_VIEW
  permissions to anonymous, these permissions have to be granted manually when
  upgrading:
  {{{
   $ trac-admin /path/to/projectenv permission add anonymous MILESTONE_VIEW
   $ trac-admin /path/to/projectenv permission add anonymous ROADMAP_VIEW
  }}}

  -----
  See also: TracGuide, TracInstall


name: TracChangeset
author: trac
ipnr: 127.0.0.1
text:
  = Trac Changeset Module =
  [[TracGuideToc]]

  Trac has a built-in functionality for visualizing “diffs” - changes to files.

  When viewing a repository check-in, such as when following a
  changeset [wiki:TracLinks link] or a changeset event in the 
  [wiki:TracTimeline timeline], Trac will display the exact changes
  made by the check-in.

  The changeset view consists of two parts, the ''header'' and the ''diff views''.

  == Changeset Header ==

  The header shows an overview of the whole changeset.
  Here you will find information such as:

   * Timestamp -- When the changeset was commited
   * Author -- Who commited the changeset
   * Message -- A brief description from the author (the commit log message)
   * Files -- A list of files affected by this changeset

  In front of each listed file, you'll find  a colored rectangle. The color
  indicates how the file is affected by the changeset.
   
   * Green: Added
   * Red: Removed
   * Yellow: Modified
   * Blue: Copied
   * Gray: Moved

  The color legend is located below the header as a reminder.

  == Diff Views ==

  Below the header is the main part of the changeset, the diff view. Each file is shown in a separate section, each of which will contain only the regions of the file that are affected by the changeset. There are two different styles of displaying the diffs: ''inline'' or ''side-by-side'' (you can switch between those styles using the preferences form):

   * The ''inline'' style shows the changed regions of a file underneath each other. A region removed from the file will be colored red, an added region will be colored green. If a region was modified, the old version is displayed above the new version. Line numbers on the left side indicate the exact position of the change in both the old and the new version of the file.
   * The ''side-by-side'' style shows the old version on the left and the new version on the right (this will typically require more screen width than the inline style.) Added and removed regions will be colored in the same way as with the inline style (green and red, respectively), but modified regions will have a yellow background.

  In addition, various advanced options are available in the preferences form for adjusting the display of the diffs:
   * You can set how many lines are displayed before and after every change
   * You can toggle whether blank lines, case changes and white space changes are ignored, thereby letting you find the functional changes more quickly

  ----
  See also: TracGuide, TracBrowser


name: TracAdmin
author: trac
ipnr: 127.0.0.1
text:
  = TracAdmin =
  [[TracGuideToc]]

  Trac is distributed with a powerful command-line configuration tool. This tool can be used  to configure and customize your Trac-installation to better fit your needs.

  == Usage ==

  You can get a comprehensive list of the available options, commands and sub-commands by invoking `trac-admin` with the `help` command:
  {{{
  trac-admin help
  }}}

  Unless you're executing the `help`, `about` or `version` sub-commands, you'll need to specify the path to the TracEnvironment that you want to administer as the first argument, for example:
  {{{
  trac-admin /path/to/projenv wiki list
  }}}

  == Interactive Mode ==

  When passing the environment path as the only argument, `trac-admin` starts in interactive mode.
  Commands can then be executed on the selected environment using the prompt, which offers tab-completion
  (on non-Windows environments, and when the Python `readline` module is available) and automatic repetition of the last command issued.

  Once you're in interactive mode, you can also get help on specific commands or subsets of commands:

  For example, to get an explanation of the `resync` command, run:
  {{{
  > help resync
  }}}

  To get help on a all the Wiki-related commands, run:
  {{{
  > help wiki
  }}}

  ----
  See also: TracGuide, TracBackup, TracPermissions, TracEnvironment, TracIni


name: TracGuide
author: trac
ipnr: 127.0.0.1
text:
  = The Trac User and Administration Guide =
  [[TracGuideToc]]

  The TracGuide is meant to serve as a starting point for all documentation regarding Trac usage and development. The guide is a free document, a collaborative effort, and a part of the [http://projects.edgewall.com/trac/ Trac Project] itself.

  == Table of Contents ==
  Currently available documentation:
   * TracGuide (This page)  -- Documentation starting point.
     * TracInstall -- How to install and run Trac.
     * TracUpgrade -- How to upgrade existing installations.
     * TracAdmin -- Administrating a Trac project.
     * TracImport -- Importing tickets from other bug databases.
     * TracIni -- Trac configuration file reference. 
     * TracPermissions -- Access control and permissions.
     * TracInterfaceCustomization -- Customizing the Trac interface.
     * TracPlugins -- Installing and managing Trac extensions.
     * TracWiki -- How to use the built-in Wiki.
     * TracBrowser -- Browsing source code with Trac.
     * TracChangeset -- Viewing changes to source code.
     * TracTickets -- Using the issue tracker.
     * TracReports -- Writing and using reports.
     * TracQuery -- Executing custom ticket queries.
     * TracRoadmap -- The roadmap helps tracking project progress.
     * TracTimeline -- The timeline provides a historic perspective on a project.
     * TracLogging -- The Trac logging facility.
     * TracRss -- RSS content syndication in Trac.
     * TracNotification -- Email notification.

   * [http://projects.edgewall.com/trac/wiki/TracFaq Trac FAQ] - A collection of Frequently Asked Questions (on the project website)

  == Support and Other Sources of Information ==
  If you are looking for a good place to ask a question about Trac, look no further than the [http://projects.edgewall.com/trac/wiki/MailingList MailingList]. It provides a friendly environment to discuss openly among Trac users and developers.

  See also the TracSupport page for more information resources.


name: TracWiki
author: trac
ipnr: 127.0.0.1
text:
  = The Trac Wiki Engine =
  [[TracGuideToc]]

  Trac has a built-in wiki engine, used for text and documentation throughout the system. WikiFormatting is used in [wiki:TitleIndex wiki pages], [wiki:TracTickets tickets] and [wiki:TracChangeset check-in log messages].  This allows for formatted text and hyperlinks in and between all Trac modules.

  Editing wiki text is easy, using any web browser and a simple formatting system (see WikiFormatting), rather than more complex markup languages like HTML.  The reasoning behind its design is that HTML, with its large collection of nestable tags, is too complicated to allow fast-paced editing, and distracts from the actual content of the pages. Note though that Trac also supports [wiki:WikiHtml HTML] and [wiki:WikiRestructuredText reStructuredText] as alternative markup formats.

  The main goal of the wiki is making editing text easier and ''encourage'' people to contribute and annotate text content for a project. 

  The wiki itself does not enforce any structure, but rather resembles a stack of empty paper sheets, where you can organize information and documentation as you see fit, and later reorganize if necessary. 

  For more help on editing wiki text, see:
   * WikiFormatting
   * WikiPageNames
   * WikiNewPage
   * TracLinks
   * WikiMacros
   * WikiProcessors

  If you want to practice editing, please use the SandBox.

  Some more information about wiki on the web:
   * http://wikipedia.org/wiki/Wiki
   * http://c2.com/cgi/wiki?WikiHistory
   * http://www.usemod.com/cgi-bin/mb.pl?WhyWikiWorks


name: TracInterfaceCustomization
author: trac
ipnr: 127.0.0.1
text:
  = Customizing the Trac Interface =
  [[TracGuideToc]]

  == Introduction ==
  This page is meant to give users suggestions on how they can customize the look of Trac.  Topics on this page cover editing the HTML templates and CSS files, but not the program code itself.  The topics are intended to show users how they can modify the look of Trac to meet their specific needs.  Suggestions for changes to Trac's interface applicable to all users should be filed as tickets, not listed on this page.

  == Project Logo and Icon ==
  The easiest parts of the Trac interface to customize are the logo and the site icon.  Both of these can be configured with settings in [wiki:TracIni trac.ini].

  The logo or icon image should be put in a folder named "htdocs" in your project's environment folder.  (''Note: in projects created with a Trac version prior to 0.9 you will need to create this folder'')

  Now configure the appropriate section of your [wiki:TracIni trac.ini]:

  === Logo ===
  Change the `src` setting to `site/` followed by the name of your image file.  The `width` and `height` settings should be modified to match your image's dimensions.

  {{{
  [header_logo]
  src = site/my_logo.gif
  alt = My Project
  width = 300
  height = 100
  }}}

  === Icon ===
  Icons should be a 16x16 image in `.gif` or `.ico` format.  Change the `icon` setting to `site/` followed by the name of your icon file.  Icons will typically be displayed by your web browser next to the site's URL and in the `Bookmarks` menu.

  {{{
  [project]
  icon = site/my_icon.ico
  }}}

  Note though that this icon is ignored by Internet Explorer, which only accepts a file named ``favicon.ico`` at the root of the host. To make the project icon work in both IE and other browsers, you can store the icon in the document root of the host, and reference it from ``trac.ini`` as follows:

  {{{
  [project]
  icon = /favicon.ico
  }}}

  == Site Header & Footer ==
  In the environment folder for each Trac project there should be a directory called {{{templates}}}.  This folder contains files {{{site_header.cs}}} and {{{site_footer.cs}}}.  Users can customize their Trac site by adding the required HTML markup to these files.  The content of these two files will be placed immediately following the opening {{{<body>}}} tag and immediately preceding the closing {{{</body>}}} tag of each page in the site, respectively.

  These files may contain static HTML, though if users desire to have dynamically generated content they can make use of the [http://www.clearsilver.net/ ClearSilver] templating language from within the pages as well. When you need to see what variables are available to the template, append the query string `?hdfdump=1` to the URL of your Trac site. This will display a structured view of the template data.

  == Site CSS ==
  The primary means to adjust the layout of a Trac site is by add [http://www.w3.org/TR/REC-CSS2/ CSS] style rules that overlay the default rules. This is best done by editing the `site_css.cs` file in the enviroment's `templates` directory. The content of that template gets inserted into a `<style type="text/css></style>` element on every HTML page generated by Trac.

  While you can add your custom style rules directory to the `site_css.cs` file, it is recommended that you simply reference an external style sheet, thereby enabling browsers to cache the CSS file instead of transmitting the rules with every response.

  The following example would import a style sheet located in the `style` root directory of your host:
  {{{
  @import url(/style/mytrac.css);
  }}}

  You can use a !ClearSilver variable to reference a style sheet stored in the project environment's `htdocs` directory:
  {{{
  @import url(<?cs var:chrome.href ?>/site/style.css);
  }}}

  == Main Templates ==

  It is also possible to use your own modified versions of the Trac [http://www.clearsilver.net/ ClearSilver] templates. Note though that this technique is not recommended because it makes upgrading Trac rather problematic: there are unfortunately several dependencies between the templates and the application code, such as the name of form fields and the structure of the template data, and these are likely to change between different versions of Trac.

  If you absolutely need to use modified templates, copy the template files from the default templates directory (usually in found in `$prefix/share/trac/templates`) into the `templates` directory of the project environment. Then modify those copies to get the desired results.


  ----
  See also TracGuide, TracIni


name: WikiNewPage
author: trac
ipnr: 127.0.0.1
text:
  = Steps to Add a New Wiki Page =

   1. Choose a name for your new page. See WikiPageNames for naming conventions.
   1. Edit an existing page and add a hyperlink to your new page. Save your changes.
   1. Follow the link you created to take you to the new page. Trac will display a "describe !PageName here" message.
   1. Click the "Edit this page" button to edit and add content to your new page. Save your changes.
   1. All done. Your new page is published.


  See also: TracWiki, WikiFormatting, TracLinks, WikiDeletePage 


name: SandBox
author: count0
ipnr: 201.52.69.185
text:
  = The Sandbox =

  This is just a page to practice and learn WikiFormatting. 

  Go ahead, edit it freely.

  Blah


name: SandBox
author: anonymous
ipnr: 201.52.69.185
text:
  = The Sandbox =

  This is just a page to practice and learn WikiFormatting. 

  Go ahead, edit it freely.

  Blah

  [[Equation($1+1=2$)]]

  [[Equation(\[\int_0^\infinity\frac{1}{x}dx = \infty\])]]


name: SandBox
author: anonymous
ipnr: 201.52.69.185
text:
  = The Sandbox =

  This is just a page to practice and learn WikiFormatting. 

  Go ahead, edit it freely.

  Blah

  [[Equation($1+1=2$)]]

  [[Equation(\[\int_0^\infty\frac{1}{x}dx = \infty\])]]


name: SandBox
author: anonymous
ipnr: 201.52.69.185
text:
  = The Sandbox =

  This is just a page to practice and learn WikiFormatting. 

  Go ahead, edit it freely.

  Blah

  [[Equation($1+1=2$)]]

  Inline [[Equation($\int_0^\infty\frac{1}{x}dx = \infty$]] test


name: SandBox
author: anonymous
ipnr: 201.52.69.185
text:
  = The Sandbox =

  This is just a page to practice and learn WikiFormatting. 

  Go ahead, edit it freely.

  Blah

  [[Equation($1+1=2$)]]

  Inline [[Equation($\int_0^\infty\frac{1}{x}dx = \infty$)]] test


name: SandBox
author: anonymous
ipnr: 201.52.69.185
text:
  = The Sandbox =

  This is just a page to practice and learn WikiFormatting. 

  Go ahead, edit it freely.

  Blah

  [[Equation($1+1=2$)]]

  Inline [[Equation(\[\int_0^\infty\frac{1}{x}dx = \infty\])]] test


name: SandBox
author: anonymous
ipnr: 201.52.69.185
text:
  = The Sandbox =

  This is just a page to practice and learn WikiFormatting. 

  Go ahead, edit it freely.

  Blah

  [[Equation($1+1=2$)]]

  Inline [[Equation($\int_\epsilon^\infty\frac{1}{x}dx = \infty$)]] test


name: SandBox
author: count0
ipnr: 201.52.69.185
text:
  = The Sandbox =

  This is just a page to practice and learn WikiFormatting. 

  Go ahead, edit it freely.

  Blah

  [[Equation($1+1=2$)]]

  Inline [[Equation($\int_\epsilon^\infty\frac{1}{x}dx = \infty$)]] test

  {{{
  #!graphviz
  digraph G {Hello->World->Graphviz->Rules}
  }}}


name: GraphvizExamples/WikiLinksPng
author: trac
ipnr: 127.0.0.1
text:
  = Graphviz Example Wiki Links, PNG Image =

  The links in the diagram use Trac wiki links to point to various places:
   * '''Ticket 1''' points to ticket:1
   * '''Report 1''' points to report:1
   * '''Changeset 1''' points to changeset:1
   * '''Graphviz Examples''' points to wiki:GraphvizExamples
   * '''Milestone 1''' points to milestone:milestone1
   * '''Source Link''' points to source:Readme.txt

  {{{
  #!graphviz.circo/png
  digraph G {
      "Ticket 1"          [style=filled, fillcolor=white, URL="ticket:1"];
      "Report 1"          [style=filled, fillcolor=white, URL="report:1"];
      "Changeset 1"       [style=filled, fillcolor=white, URL="changeset:1"];
      "Graphviz Examples" [style=filled, fillcolor=white, URL="wiki:GraphvizExamples"];
      "Milestone 1"       [style=filled, fillcolor=white, URL="milestone:milestone1"];
      "Readme.txt"        [style=filled, fillcolor=white, URL="source:Readme.txt"];

      "Ticket 1";
      "Report 1";
      "Changeset 1";
      "Graphviz Examples";
      "Milestone 1";
      "Readme.txt";
  }
  }}}


name: GraphvizExamples/MapNodesPng
author: trac
ipnr: 127.0.0.1
text:
  = Graphviz Eamples Map Nodes, PNG Image =

  The individual nodes of the image point to the various pages on the Edgewall Trac project site.

  {{{
  #!graphviz.circo/png
  digraph G {
      Trac [URL="http://trac.edgewall.com/"];
      TracProject [URL="http://projects.edgewall.com/trac/"];
      Guide [URL="http://projects.edgewall.com/trac/wiki/TracGuide"];
      FAQ [URL="http://projects.edgewall.com/trac/wiki/TracFaq"];
      Download [URL="http://projects.edgewall.com/trac/wiki/TracDownload"];
      ChangeLog [URL="http://projects.edgewall.com/trac/wiki/ChangeLog"];
      MailingList [URL="http://projects.edgewall.com/trac/wiki/MailingList"];
      TracProject [URL="http://projects.edgewall.com/trac/wiki/TracProject"];
      RoadMap [URL="http://projects.edgewall.com/trac/wiki/RoadMap"];
      Team [URL="http://projects.edgewall.com/trac/wiki/TracTeam"];

      Trac -> TracProject;
      Trac -> Guide;
      Trac -> FAQ;
      Trac -> Download;
      Trac -> ChangeLog;
      Trac -> MailingList;
      Trac -> RoadMap;
      Trac -> Team;
  }
  }}}


name: GraphvizExamples/InvokingNeato
author: trac
ipnr: 127.0.0.1
text:
  = Graphviz Example Invoking Neato =
  {{{
  #!graphviz.neato
  digraph G {
      Hello->World
      Hello->Goodbye
      World->Graphviz
      Graphviz->Rules
  }
  }}}


name: GraphvizExamples/MapWhole
author: trac
ipnr: 127.0.0.1
text:
  = Graphviz Example Map Whole Image =

  The '''TracProject''' portion points to the Trac project page at Edgewall while the rest of the image points to the Edgewall site.

  {{{
  #!graphviz
  digraph G {
      URL="http://www.edgewall.com/";
      label = "Edgewall"

      TracProject [URL="http://projects.edgewall.com/trac/"];
      TracProject;
  }
  }}}


name: GraphvizExamples/InvokingFdp
author: trac
ipnr: 127.0.0.1
text:
  = Graphviz Example Invoking Fdp =
  {{{
  #!graphviz.fdp
  digraph G {
      Hello->World
      Hello->Goodbye
      World->Graphviz
      Graphviz->Rules
  }
  }}}


name: GraphvizExamples/OutputSvg
author: trac
ipnr: 127.0.0.1
text:
  = Graphviz Example Output Svg =
  {{{
  #!graphviz.dot/svg
  digraph G {

  	subgraph cluster_0 {
  		style=filled;
  		color=lightgrey;
  		node [style=filled,color=white];
  		a0 -> a1 -> a2 -> a3;
  		label = "process #1";
  	}

  	subgraph cluster_1 {
  		node [style=filled];
  		b0 -> b1 -> b2 -> b3;
  		label = "process #2";
  		color=red
  	}
  	start -> a0;
  	start -> b0;
  	a1 -> b3;
  	b2 -> a3;
  	a3 -> a0;
  	a3 -> end;
  	b3 -> end;

  	start [shape=Mdiamond];
  	end [shape=Msquare];
  }
  }}}


name: GraphvizExamples
author: trac
ipnr: 127.0.0.1
text:
  = Graphviz Examples =

  == Just the basics ==

  Invoking [wiki:GraphvizExamples/InvokingDot dot], [wiki:GraphvizExamples/InvokingNeato neato], [wiki:GraphvizExamples/InvokingTwopi twopi], [wiki:GraphvizExamples/InvokingCirco circo] and [wiki:GraphvizExamples/InvokingFdp fdp] with the same graph description.

  == Output Formats ==

  Setting the output format to [wiki:GraphvizExamples/OutputPng png], [wiki:GraphvizExamples/OutputJpg jpg], [wiki:GraphvizExamples/OutputGif gif] and [wiki:GraphvizExamples/OutputSvg svg].

  == Image Maps ==

  Using client side image maps to [wiki:GraphvizExamples/MapWhole map whole image], [wiki:GraphvizExamples/MapNodesPng map nodes (png)], [wiki:GraphvizExamples/MapNodesSvg map nodes (svg)], [wiki:GraphvizExamples/WikiLinksPng wiki links (png)], and [wiki:GraphvizExamples/WikiLinksSvg wiki links (svg)].


name: GraphvizExamples/WikiLinksSvg
author: trac
ipnr: 127.0.0.1
text:
  = Graphviz Example Wiki Links, SVG Image =

  The links in the diagram use Trac wiki links to point to various places:
   * '''Ticket 1''' points to ticket:1
   * '''Report 1''' points to report:1
   * '''Changeset 1''' points to changeset:1
   * '''Graphviz Examples''' points to wiki:GraphvizExamples
   * '''Milestone 1''' points to milestone:milestone1
   * '''Source Link''' points to source:Readme.txt

  {{{
  #!graphviz.circo/svg
  digraph G {
      "Ticket 1"          [style=filled, fillcolor=white, URL="ticket:1"];
      "Report 1"          [style=filled, fillcolor=white, URL="report:1"];
      "Changeset 1"       [style=filled, fillcolor=white, URL="changeset:1"];
      "Graphviz Examples" [style=filled, fillcolor=white, URL="wiki:GraphvizExamples"];
      "Milestone 1"       [style=filled, fillcolor=white, URL="milestone:milestone1"];
      "Readme.txt"        [style=filled, fillcolor=white, URL="source:Readme.txt"];

      "Ticket 1";
      "Report 1";
      "Changeset 1";
      "Graphviz Examples";
      "Milestone 1";
      "Readme.txt";
  }
  }}}


name: GraphvizExamples/OutputGif
author: trac
ipnr: 127.0.0.1
text:
  = Graphviz Example Output Gif =
  {{{
  #!graphviz.dot/gif
  digraph G {

  	subgraph cluster_0 {
  		style=filled;
  		color=lightgrey;
  		node [style=filled,color=white];
  		a0 -> a1 -> a2 -> a3;
  		label = "process #1";
  	}

  	subgraph cluster_1 {
  		node [style=filled];
  		b0 -> b1 -> b2 -> b3;
  		label = "process #2";
  		color=red
  	}
  	start -> a0;
  	start -> b0;
  	a1 -> b3;
  	b2 -> a3;
  	a3 -> a0;
  	a3 -> end;
  	b3 -> end;

  	start [shape=Mdiamond];
  	end [shape=Msquare];
  }
  }}}


name: GraphvizExamples/MapNodesSvg
author: trac
ipnr: 127.0.0.1
text:
  = Graphviz Eamples Map Nodes, SVG Image =

  The individual nodes of the image point to the various pages on the Edgewall Trac project site.

  Notice that the entire oval for the Trac node is an active link while the others are only active on the text and the oval outline. The use of the '''style=filled''' and '''fillcolor=red''' force the SVG links to be activated for the whole node.

  {{{
  #!graphviz.circo/svg
  digraph G {
      Trac [style=filled, fillcolor=red, URL="http://trac.edgewall.com/"];
      TracProject [URL="http://projects.edgewall.com/trac/"];
      Guide [URL="http://projects.edgewall.com/trac/wiki/TracGuide"];
      FAQ [URL="http://projects.edgewall.com/trac/wiki/TracFaq"];
      Download [URL="http://projects.edgewall.com/trac/wiki/TracDownload"];
      ChangeLog [URL="http://projects.edgewall.com/trac/wiki/ChangeLog"];
      MailingList [URL="http://projects.edgewall.com/trac/wiki/MailingList"];
      TracProject [URL="http://projects.edgewall.com/trac/wiki/TracProject"];
      RoadMap [URL="http://projects.edgewall.com/trac/wiki/RoadMap"];
      Team [URL="http://projects.edgewall.com/trac/wiki/TracTeam"];

      Trac -> TracProject;
      Trac -> Guide;
      Trac -> FAQ;
      Trac -> Download;
      Trac -> ChangeLog;
      Trac -> MailingList;
      Trac -> RoadMap;
      Trac -> Team;
  }
  }}}


name: GraphvizExamples/GraphvizExample2
author: trac
ipnr: 127.0.0.1
text:
  {{{
  #!graphviz
  digraph g {
  graph [
  rankdir = "LR"
  ];
  node [
  fontsize = "16"
  shape = "ellipse"
  ];
  edge [
  ];
  "node0" [
  label = "<f0> 0x10ba8| <f1>"
  shape = "record"
  ];
  "node1" [
  label = "<f0> 0xf7fc4380| <f1> | <f2> |-1"
  shape = "record"
  ];
  "node2" [
  label = "<f0> 0xf7fc44b8| | |2"
  shape = "record"
  ];
  "node3" [
  label = "<f0> 3.43322790286038071e-06|44.79998779296875|0"
  shape = "record"
  ];
  "node4" [
  label = "<f0> 0xf7fc4380| <f1> | <f2> |2"
  shape = "record"
  ];
  "node5" [
  label = "<f0> (nil)| | |-1"
  shape = "record"
  ];
  "node6" [
  label = "<f0> 0xf7fc4380| <f1> | <f2> |1"
  shape = "record"
  ];
  "node7" [
  label = "<f0> 0xf7fc4380| <f1> | <f2> |2"
  shape = "record"
  ];
  "node8" [
  label = "<f0> (nil)| | |-1"
  shape = "record"
  ];
  "node9" [
  label = "<f0> (nil)| | |-1"
  shape = "record"
  ];
  "node10" [
  label = "<f0> (nil)| <f1> | <f2> |-1"
  shape = "record"
  ];
  "node11" [
  label = "<f0> (nil)| <f1> | <f2> |-1"
  shape = "record"
  ];
  "node12" [
  label = "<f0> 0xf7fc43e0| | |1"
  shape = "record"
  ];
  "node0":f0 -> "node1":f0 [
  id = 0
  ];
  "node0":f1 -> "node2":f0 [
  id = 1
  ];
  "node1":f0 -> "node3":f0 [
  id = 2
  ];
  "node1":f1 -> "node4":f0 [
  id = 3
  ];
  "node1":f2 -> "node5":f0 [
  id = 4
  ];
  "node4":f0 -> "node3":f0 [
  id = 5
  ];
  "node4":f1 -> "node6":f0 [
  id = 6
  ];
  "node4":f2 -> "node10":f0 [
  id = 7
  ];
  "node6":f0 -> "node3":f0 [
  id = 8
  ];
  "node6":f1 -> "node7":f0 [
  id = 9
  ];
  "node6":f2 -> "node9":f0 [
  id = 10
  ];
  "node7":f0 -> "node3":f0 [
  id = 11
  ];
  "node7":f1 -> "node1":f0 [
  id = 12
  ];
  "node7":f2 -> "node8":f0 [
  id = 13
  ];
  "node10":f1 -> "node11":f0 [
  id = 14
  ];
  "node10":f2 -> "node12":f0 [
  id = 15
  ];
  "node11":f2 -> "node1":f0 [
  id = 16
  ];
  }
  }}}


name: GraphvizExamples/GraphvizExample3
author: trac
ipnr: 127.0.0.1
text:
  {{{
  #!graphviz
  digraph G {

  	subgraph cluster_0 {
  		style=filled;
  		color=lightgrey;
  		node [style=filled,color=white];
  		a0 -> a1 -> a2 -> a3;
  		label = "process #1";
  	}

  	subgraph cluster_1 {
  		node [style=filled];
  		b0 -> b1 -> b2 -> b3;
  		label = "process #2";
  		color=blue
  	}
  	start -> a0;
  	start -> b0;
  	a1 -> b3;
  	b2 -> a3;
  	a3 -> a0;
  	a3 -> end;
  	b3 -> end;

  	start [shape=Mdiamond];
  	end [shape=Msquare];
  }
  }}}


name: GraphvizExamples/InvokingDot
author: trac
ipnr: 127.0.0.1
text:
  = Graphviz Example Invoking Dot =
  {{{
  #!graphviz.dot
  digraph G {
      Hello->World
      Hello->Goodbye
      World->Graphviz
      Graphviz->Rules
  }
  }}}


name: GraphvizExamples/JustTestingGraphviz
author: trac
ipnr: 127.0.0.1
text:
  {{{
  #!graphviz.circo
  digraph G {
      Hello->World
      Hello->Goodbye
      World->Graphviz
      Graphviz->Rules
      Hello->Mary
      Hello->Peter
      Peter->Loves
      Loves->Mary
      Mary->Loves
      Loves->Peter
      Loves->Rio
      Loves->Mocha
  }
  }}}


name: GraphvizExamples/OutputJpg
author: trac
ipnr: 127.0.0.1
text:
  = Graphviz Example Output Jpg =
  {{{
  #!graphviz.dot/jpg
  digraph G {

  	subgraph cluster_0 {
  		style=filled;
  		color=lightgrey;
  		node [style=filled,color=white];
  		a0 -> a1 -> a2 -> a3;
  		label = "process #1";
  	}

  	subgraph cluster_1 {
  		node [style=filled];
  		b0 -> b1 -> b2 -> b3;
  		label = "process #2";
  		color=red
  	}
  	start -> a0;
  	start -> b0;
  	a1 -> b3;
  	b2 -> a3;
  	a3 -> a0;
  	a3 -> end;
  	b3 -> end;

  	start [shape=Mdiamond];
  	end [shape=Msquare];
  }
  }}}


name: GraphvizExamples/InvokingCirco
author: trac
ipnr: 127.0.0.1
text:
  = Graphviz Example Invoking Circo =
  {{{
  #!graphviz.circo
  digraph G {
      Hello->World
      Hello->Goodbye
      World->Graphviz
      Graphviz->Rules
  }
  }}}


name: GraphvizExamples/OutputPng
author: trac
ipnr: 127.0.0.1
text:
  = Graphviz Example Output Png =
  {{{
  #!graphviz.dot/png
  digraph G {

  	subgraph cluster_0 {
  		style=filled;
  		color=lightgrey;
  		node [style=filled,color=white];
  		a0 -> a1 -> a2 -> a3;
  		label = "process #1";
  	}

  	subgraph cluster_1 {
  		node [style=filled];
  		b0 -> b1 -> b2 -> b3;
  		label = "process #2";
  		color=red
  	}
  	start -> a0;
  	start -> b0;
  	a1 -> b3;
  	b2 -> a3;
  	a3 -> a0;
  	a3 -> end;
  	b3 -> end;

  	start [shape=Mdiamond];
  	end [shape=Msquare];
  }
  }}}


name: GraphvizExamples/InvokingTwopi
author: trac
ipnr: 127.0.0.1
text:
  = Graphviz Example Invoking Twopi =
  {{{
  #!graphviz.twopi
  digraph G {
      Hello->World
      Hello->Goodbye
      World->Graphviz
      Graphviz->Rules
  }
  }}}


name: WikiStart
author: count0
ipnr: 201.52.69.185
text:
  = What is graph-tool? =

  graph-tool is a program to help with statistical analysis of [http://en.wikipedia.org/wiki/Graph_%28mathematics%29 graphs]. Its feature set includes:

   * support for directed and undirected graphs
   * support for arbitrary vertex or edge properties
   * generic filtering of edges and vertices
   * several statistical measurements:
     * degree (or scalar property) histogram
     * vertex-vertex degree (or scalar property) correlation
     * average nearest neighbours degree (or scalar property)
     * vertex-edge-vertex correlation
     * clustering coefficients
     * assortativity coefficient
     * average distance
     * component statistics
   * generation of random graphs with arbitrary degree distribution and degree correlation

  The core algorithms are written in C++, making use of the [http://www.boost.org/libs/graph/doc/ Boost Graph Library], and [http://www.awprofessional.com/bookstore/product.asp?isbn=0321227255&rl=1 template metaprogramming] techniques, with performace in mind. The command line interface is written in [[http://www.python.org python]].

  graph-tool is [http://www.gnu.org/philosophy/free-sw.html free software], and is released under the [http://www.gnu.org/copyleft/gpl.html GPL].


name: WikiStart
author: count0
ipnr: 201.52.69.185
text:
  = What is graph-tool? =

  graph-tool is a program to help with statistical analysis of [http://en.wikipedia.org/wiki/Graph_%28mathematics%29 graphs]. Its feature set includes:

   * support for directed and undirected graphs
   * support for arbitrary vertex or edge properties
   * generic filtering of edges and vertices
   * several statistical measurements:
     * degree (or scalar property) histogram
     * vertex-vertex degree (or scalar property) correlation
     * average nearest neighbours degree (or scalar property)
     * vertex-edge-vertex correlation
     * clustering coefficients
     * assortativity coefficient
     * average distance
     * component statistics
   * generation of random graphs with arbitrary degree distribution and degree correlation
   * support for [http://graphml.graphdrawing.org/ graphml] and [http://www.graphviz.org/ dot] file formats

  The core algorithms are written in C++, making use of the [http://www.boost.org/libs/graph/doc/ Boost Graph Library], and [http://www.awprofessional.com/bookstore/product.asp?isbn=0321227255&rl=1 template metaprogramming] techniques, with performace in mind. The command line interface is written in [http://www.python.org python].

  See GraphToolGuide for instructions and examples of how to use the program.

  graph-tool is [http://www.gnu.org/philosophy/free-sw.html free software], and is released under the [http://www.gnu.org/copyleft/gpl.html GPL].


name: MailingList
author: count0
ipnr: 201.52.69.185
text:
  = graph-tool Mailing Lists =

  Discusstion and communication about the graph-tool project are done through mailing list conversations.

  There are currently two mailing lists:

  == graph-tool ==

    http://lists.forked.de/mailman/listinfo/graph-tool

  The main mailing list for the grapht-tool discussion. Subscribe to this list to participate in the project or talk about graph-tool-related matters.

  == graph-tool-tickets ==

    http://lists.forked.de/mailman/listinfo/graph-tool-tickets

  graph-tool-tickets is a fairly high traffic mailing list for ticket changes. Every time a graph-tool ticket is modified a new message is posted on this list. 

  == Archives ==

  The archive of each mailing list is available through the respective mailing list info page above.


name: MailingList
author: count0
ipnr: 201.52.69.185
text:
  = Graph-tool Mailing Lists =

  Discusstion and communication about the graph-tool project are done through mailing list conversations.

  There are currently two mailing lists:

  == graph-tool ==

    http://lists.forked.de/mailman/listinfo/graph-tool

  The main mailing list for the grapht-tool discussion. Subscribe to this list to participate in the project or talk about graph-tool-related matters.

  == graph-tool-tickets ==

    http://lists.forked.de/mailman/listinfo/graph-tool-tickets

  graph-tool-tickets is a fairly high traffic mailing list for ticket changes. Every time a graph-tool ticket is modified a new message is posted on this list. 

  == Mailing List Archives ==

  The archive of each mailing list is available through the respective mailing list info page above.


name: MailingList
author: count0
ipnr: 201.52.69.185
text:
  = Graph-tool Mailing Lists =

  Discusstion and communication about the graph-tool project are done through mailing list conversations.

  There are currently two mailing lists:

  == graph-tool ==

    http://lists.forked.de/mailman/listinfo/graph-tool

  The main mailing list for the graph-tool discussion. Subscribe to this list to participate in the project or talk about graph-tool-related matters.

  == graph-tool-tickets ==

    http://lists.forked.de/mailman/listinfo/graph-tool-tickets

  graph-tool-tickets is a fairly high traffic mailing list for ticket changes. Every time a graph-tool ticket is modified a new message is posted on this list. 

  == Mailing List Archives ==

  The archive of each mailing list is available through the respective mailing list info page above.


name: GraphToolDownload
author: count0
ipnr: 201.52.69.185
text:
  = Stable Releases =

  Nothing yet...

  = Latest Development Source Code =

  We use [http://subversion.tigris.org/ Subversion] for source revision control and code sharing.

  The Subversion repository URL for the graph-tool project is at:

    http://svn.forked.de/graph-tool/

  The latest revision can be checked out with the following command:

  {{{
  svn co http://svn.forked.de/graph-tool/trunk trac
  }}}

  Or with encryption:

  {{{
  svn co https://svn.forked.de/graph-tool/trunk trac
  }}}

  For further instructions on how to use Subversion, see [http://svnbook.red-bean.com/book.html The Subversion Book]


name: GraphToolDownload
author: count0
ipnr: 201.52.69.185
text:
  = Stable Releases =

  Nothing yet...

  = Latest Development Source Code =

  We use [http://subversion.tigris.org/ Subversion] for source revision control and code sharing.

  The Subversion repository URL for the graph-tool project is at:

    http://svn.forked.de/graph-tool/

  The latest revision can be checked out with the following command:

  {{{
  svn co http://svn.forked.de/graph-tool/trunk graph-tool
  }}}

  Or with encryption:

  {{{
  svn co https://svn.forked.de/graph-tool/trunk graph-tool
  }}}

  For further instructions on how to use Subversion, see [http://svnbook.red-bean.com/book.html The Subversion Book]


name: SandBox
author: anonymous
ipnr: 143.107.130.135
text:
  = The Sandbox =

  This is just a page to practice and learn WikiFormatting. 

  Go ahead, edit it freely.

  Blah

  [[Equation($1+1=2$)]]

  Inline [[Equation($\int_\epsilon^\infty\frac{1}{x}dx = \infty$)]] test

  [[Equation($\frac{1}{x}$)]]

  {{{
  #!graphviz
  digraph G {Hello->World->Graphviz->Rules->Blah}
  }}}


name: GraphToolSupport
author: count0
ipnr: 201.52.69.185
text:
  = graph-tool support =

  If you have a problem using graph-tool please go through the following steps:

   1. Check the [wiki:MailingList mailing list] archives to see if your problem is covered there.
   2. If it isn't, post a message to the mailing list describing your problem.
   3. If you think you found a bug, please consult the bug database, using either a [https://projects.forked.de/graph-tool/search?q=&ticket=on&wiki=on full search] or a [https://projects.forked.de/graph-tool/query?summary=~&keywords=~%22 ticket query].
   4. If the bug is not listed there, please submit a [https://projects.forked.de/graph-tool/newticket new ticket].

  ----
  See also: MailingList


name: WikiStart
author: count0
ipnr: 201.52.69.185
text:
  = What is graph-tool? =
  [[Image(small.png, class=floatright)]] 

  graph-tool is a program to help with statistical analysis of [http://en.wikipedia.org/wiki/Graph_%28mathematics%29 graphs]. Its feature set includes:

   * support for directed and undirected graphs
   * support for arbitrary vertex or edge properties
   * generic filtering of edges and vertices
   * several statistical measurements:
     * degree (or scalar property) histogram
     * vertex-vertex degree (or scalar property) correlation
     * average nearest neighbours degree (or scalar property)
     * vertex-edge-vertex correlation
     * clustering coefficients
     * assortativity coefficient
     * average distance
     * component statistics
   * generation of random graphs with arbitrary degree distribution and degree correlation
   * support for [http://graphml.graphdrawing.org/ graphml] and [http://www.graphviz.org/ dot] file formats

  The core algorithms are written in C++, making use of the [http://www.boost.org/libs/graph/doc/ Boost Graph Library], and [http://www.awprofessional.com/bookstore/product.asp?isbn=0321227255&rl=1 template metaprogramming] techniques, with performace in mind. The command line interface is written in [http://www.python.org python].

  See GraphToolGuide for instructions and examples of how to use the program.

  graph-tool is [http://www.gnu.org/philosophy/free-sw.html free software], and is released under the [http://www.gnu.org/copyleft/gpl.html GPL].


name: WikiStart
author: count0
ipnr: 201.52.69.185
text:
  = What is graph-tool? =
  [[Image(WikiStartAttachments:small.png, class=floatright)]] 

  graph-tool is a program to help with statistical analysis of [http://en.wikipedia.org/wiki/Graph_%28mathematics%29 graphs]. Its feature set includes:

   * support for directed and undirected graphs
   * support for arbitrary vertex or edge properties
   * generic filtering of edges and vertices
   * several statistical measurements:
     * degree (or scalar property) histogram
     * vertex-vertex degree (or scalar property) correlation
     * average nearest neighbours degree (or scalar property)
     * vertex-edge-vertex correlation
     * clustering coefficients
     * assortativity coefficient
     * average distance
     * component statistics
   * generation of random graphs with arbitrary degree distribution and degree correlation
   * support for [http://graphml.graphdrawing.org/ graphml] and [http://www.graphviz.org/ dot] file formats

  The core algorithms are written in C++, making use of the [http://www.boost.org/libs/graph/doc/ Boost Graph Library], and [http://www.awprofessional.com/bookstore/product.asp?isbn=0321227255&rl=1 template metaprogramming] techniques, with performace in mind. The command line interface is written in [http://www.python.org python].

  See GraphToolGuide for instructions and examples of how to use the program.

  graph-tool is [http://www.gnu.org/philosophy/free-sw.html free software], and is released under the [http://www.gnu.org/copyleft/gpl.html GPL].


name: WikiStart
author: count0
ipnr: 201.52.69.185
text:
  = What is graph-tool? =
  [[Image(WikiStartAttachments:small.png, class=floatright, nolink)]] 

  graph-tool is a program to help with statistical analysis of [http://en.wikipedia.org/wiki/Graph_%28mathematics%29 graphs]. Its feature set includes:

   * support for directed and undirected graphs
   * support for arbitrary vertex or edge properties
   * generic filtering of edges and vertices
   * several statistical measurements:
     * degree (or scalar property) histogram
     * vertex-vertex degree (or scalar property) correlation
     * average nearest neighbours degree (or scalar property)
     * vertex-edge-vertex correlation
     * clustering coefficients
     * assortativity coefficient
     * average distance
     * component statistics
   * generation of random graphs with arbitrary degree distribution and degree correlation
   * support for [http://graphml.graphdrawing.org/ graphml] and [http://www.graphviz.org/ dot] file formats

  The core algorithms are written in C++, making use of the [http://www.boost.org/libs/graph/doc/ Boost Graph Library], and [http://www.awprofessional.com/bookstore/product.asp?isbn=0321227255&rl=1 template metaprogramming] techniques, with performace in mind. The command line interface is written in [http://www.python.org python].

  See GraphToolGuide for instructions and examples of how to use the program.

  graph-tool is [http://www.gnu.org/philosophy/free-sw.html free software], and is released under the [http://www.gnu.org/copyleft/gpl.html GPL].


name: GraphToolGuide
author: count0
ipnr: 201.52.69.185
text:
  [[PageOutline]]
  = graph-tool Guide =

  == Invoking ==

  graph-tool is invoked by typing {{{graph-tool}}} in the command line. For a quick summary of options type
  {{{
  graph-tool --help
  }}}


  == Loading and saving files ==


name: GraphToolGuide
author: count0
ipnr: 201.52.69.185
text:
  = graph-tool Guide =

  [[PageOutline]]

  == Invoking ==

  graph-tool is invoked by typing {{{graph-tool}}} in the command line. For a quick summary of options type
  {{{
  graph-tool --help
  }}}


  == Loading and saving files ==

  Files can be loaded with the {{{--load}}} option. Graph tool supports both [http://graphml.graphdrawing.org/ graphml] and [http://www.graphviz.org/ dot] formats. The formats are identified by the file name extension: files ending in {{{.xml}}} are considered graphml files, and files ending in {{{.dot}}} are considered dot files. Files can also end in {{{.gz}}} or {{{.bz2}}} to indicate compression, such as {{{.xml.gz}}} or {{{.dot.bz2}}}.

  Below are two examples of the same graph in both formats:


name: GraphToolGuide
author: count0
ipnr: 201.52.69.185
text:
  = graph-tool Guide =

  [[PageOutline]]

  == Invoking ==

  graph-tool is invoked by typing {{{graph-tool}}} in the command line. For a quick summary of options type
  {{{
  graph-tool --help
  }}}


  == Loading and saving files ==

  Files can be loaded with the {{{--load}}} option. Graph tool supports both [http://graphml.graphdrawing.org/ graphml] and [http://www.graphviz.org/ dot] formats. The formats are identified by the file name extension: files ending in {{{.xml}}} are considered graphml files, and files ending in {{{.dot}}} are considered dot files. Files can also end in {{{.gz}}} or {{{.bz2}}} to indicate compression, such as {{{.xml.gz}}} or {{{.dot.bz2}}}.

  === File format description

  Consider the following graph:
  {{{
  #!graphviz
  digraph G {
  start="10";
  8;
  1->2
  2->3
  3->7
  4->5
  5->6
  5->3
  6->7
  7->2
  }
  }}}


name: GraphToolGuide
author: count0
ipnr: 201.52.69.185
text:
  = graph-tool Guide =

  [[PageOutline]]

  == Invoking ==

  graph-tool is invoked by typing {{{graph-tool}}} in the command line. For a quick summary of options type
  {{{
  graph-tool --help
  }}}


  == Loading and saving files ==

  Files can be loaded with the {{{--load}}} option. Graph tool supports both [http://graphml.graphdrawing.org/ graphml] and [http://www.graphviz.org/ dot] formats. The formats are identified by the file name extension: files ending in {{{.xml}}} are considered graphml files, and files ending in {{{.dot}}} are considered dot files. Files can also end in {{{.gz}}} or {{{.bz2}}} to indicate compression, such as {{{.xml.gz}}} or {{{.dot.bz2}}}. Files can be saved with the {{{--save}}} command, and the file name specifications are the same.

  == File format description ==

  Consider the following directed graph, with one floating point edge property:
  {{{
  #!graphviz
  digraph G {
  start="11";
  1->2 [label = "  1.2  ", len=0.6];
  2->3 [label = "  0.8  ", len=0.6];
  3->7 [label = "  0.5  ", len=0.6];
  4->5 [label = "  0.2  ", len=0.6];
  5->6 [label = "  10.1  ", len=0.6];
  5->3 [label = "  5.5", len=0.6];
  6->7 [label = "  2.0  ", len=0.6];
  7->2 [label = "  0.1  ", len=0.6];
  }
  }}}


name: GraphToolGuide
author: count0
ipnr: 201.52.69.185
text:
  = graph-tool Guide =

  [[PageOutline]]

  == Invoking ==

  graph-tool is invoked by typing {{{graph-tool}}} in the command line. For a quick summary of options type
  {{{
  graph-tool --help
  }}}


  == Loading and saving files ==

  Files can be loaded with the {{{--load}}} option. Graph tool supports both [http://graphml.graphdrawing.org/ graphml] and [http://www.graphviz.org/ dot] formats. The formats are identified by the file name extension: files ending in {{{.xml}}} are considered graphml files, and files ending in {{{.dot}}} are considered dot files. Files can also end in {{{.gz}}} or {{{.bz2}}} to indicate compression, such as {{{.xml.gz}}} or {{{.dot.bz2}}}. Files can be saved with the {{{--save}}} command, and the file name specifications are the same.

  == File format description ==

  Consider the following directed graph, with one floating point edge property called (which will be called "weight"):
  {{{
  #!html
  <div style="text-align: center;">
  }}}
  {{{
  #!graphviz
  digraph G {
  start="12";
  1->2 [label = "  1.2  ", len=0.6];
  2->3 [label = "  0.8  ", len=0.6];
  3->7 [label = "  0.5", len=0.6];
  4->5 [label = "  0.2  ", len=0.6];
  5->6 [label = "  10.1  ", len=0.6];
  5->3 [label = "  5.5", len=0.6];
  6->7 [label = "  2.0", len=0.6];
  7->2 [label = "  0.1", len=0.6];
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  It can be defined in dot format as such:

  {{{
  digraph G {
  1->2 [weight = "1.2"];
  2->3 [weight = "0.8"];
  3->7 [weight = "0.5"];
  4->5 [weight = "0.2"];
  5->6 [weight = "10.1"];
  5->3 [weight = "5.5"];
  6->7 [weight = "2.0"];
  7->2 [weight = "0.1"];
  }
  }}}

  and in graphml format as such:

  {{{
  <?xml version="1.0" encoding="UTF-8"?>
  <graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://graphml.graphdrawing.org/xmlns/1.0/graphml.xsd">
    <key id="d1" for="edge" attr.name="weight" attr.type="double"/>
    <graph id="G" edgedefault="directed">
      <node id="n0"/>
      <node id="n1"/>
      <node id="n2"/>
      <node id="n3"/>
      <node id="n4"/>
      <node id="n5"/>
      <node id="n6"/>
      <edge id="e0" source="n0" target="n1">
        <data key="d1">1.2</data>
      </edge>
      <edge id="e1" source="n1" target="n2">
        <data key="d1">0.8</data>
      </edge>
      <edge id="e2" source="n2" target="n6">
        <data key="d1">0.5</data>
      </edge>
      <edge id="e3" source="n3" target="n4">
        <data key="d1">0.2</data>
      </edge>
      <edge id="e4" source="n4" target="n5">
        <data key="d1">10.1</data>
      </edge>
      <edge id="e5" source="n4" target="n2">
        <data key="d1">5.5</data>
      </edge>
      <edge id="e6" source="n5" target="n6">
        <data key="d1">2.0</data>
      </edge>
      <edge id="e7" source="n6" target="n1">
        <data key="d1">0.1</data>
      </edge>
    </graph>
  </graphml>
  }}}


name: GraphToolGuide
author: count0
ipnr: 201.52.69.185
text:
  = graph-tool Guide =

  [[PageOutline]]

  == Invoking ==

  graph-tool is invoked by typing {{{graph-tool}}} in the command line. For a quick summary of options type
  {{{
  graph-tool --help
  }}}


  == Loading and saving files ==

  Files can be loaded with the {{{--load}}} option. Graph tool supports both [http://graphml.graphdrawing.org/ graphml] and [http://www.graphviz.org/ dot] formats. The formats are identified by the file name extension: files ending in {{{.xml}}} are considered graphml files, and files ending in {{{.dot}}} are considered dot files. Files can also end in {{{.gz}}} or {{{.bz2}}} to indicate compression, such as {{{.xml.gz}}} or {{{.dot.bz2}}}. Files can be saved with the {{{--save}}} command, and the file name specifications are the same.

  == File format description ==

  Consider the following directed graph, with one floating point edge property (which will be called "weight"):
  {{{
  #!html
  <div style="text-align: center;">
  }}}
  {{{
  #!graphviz
  digraph G {
  start="12";
  1->2 [label = "  1.2  ", len=0.6];
  2->3 [label = "  0.8  ", len=0.6];
  3->7 [label = "  0.5", len=0.6];
  4->5 [label = "  0.2  ", len=0.6];
  5->6 [label = "  10.1  ", len=0.6];
  5->3 [label = "  5.5", len=0.6];
  6->7 [label = "  2.0", len=0.6];
  7->2 [label = "  0.1", len=0.6];
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  It can be defined in dot format as such:

  {{{
  digraph G {
  1->2 [weight = "1.2"];
  2->3 [weight = "0.8"];
  3->7 [weight = "0.5"];
  4->5 [weight = "0.2"];
  5->6 [weight = "10.1"];
  5->3 [weight = "5.5"];
  6->7 [weight = "2.0"];
  7->2 [weight = "0.1"];
  }
  }}}

  and in graphml format as such:

  {{{
  <?xml version="1.0" encoding="UTF-8"?>
  <graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://graphml.graphdrawing.org/xmlns/1.0/graphml.xsd">
    <key id="d1" for="edge" attr.name="weight" attr.type="double"/>
    <graph id="G" edgedefault="directed">
      <node id="n0"/>
      <node id="n1"/>
      <node id="n2"/>
      <node id="n3"/>
      <node id="n4"/>
      <node id="n5"/>
      <node id="n6"/>
      <edge id="e0" source="n0" target="n1">
        <data key="d1">1.2</data>
      </edge>
      <edge id="e1" source="n1" target="n2">
        <data key="d1">0.8</data>
      </edge>
      <edge id="e2" source="n2" target="n6">
        <data key="d1">0.5</data>
      </edge>
      <edge id="e3" source="n3" target="n4">
        <data key="d1">0.2</data>
      </edge>
      <edge id="e4" source="n4" target="n5">
        <data key="d1">10.1</data>
      </edge>
      <edge id="e5" source="n4" target="n2">
        <data key="d1">5.5</data>
      </edge>
      <edge id="e6" source="n5" target="n6">
        <data key="d1">2.0</data>
      </edge>
      <edge id="e7" source="n6" target="n1">
        <data key="d1">0.1</data>
      </edge>
    </graph>
  </graphml>
  }}}


name: GraphToolGuide
author: count0
ipnr: 201.52.69.185
text:
  = graph-tool Guide =

  [[PageOutline]]

  == Invoking ==

  graph-tool is invoked by typing {{{graph-tool}}} in the command line. For a quick summary of options type
  {{{
  graph-tool --help
  }}}


  == Loading and saving files ==

  Files can be loaded with the {{{--load}}} option. Graph tool supports both [http://graphml.graphdrawing.org/ graphml] and [http://www.graphviz.org/ dot] formats. The formats are identified by the file name extension: files ending in {{{.xml}}} are considered graphml files, and files ending in {{{.dot}}} are considered dot files. Files can also end in {{{.gz}}} or {{{.bz2}}} to indicate compression, such as {{{.xml.gz}}} or {{{.dot.bz2}}}. Files can be saved with the {{{--save}}} command, and the file name specifications are the same.

  === File format description ===

  Consider the following directed graph, with one floating point edge property (which will be called "weight"):
  {{{
  #!html
  <div style="text-align: center;">
  }}}
  {{{
  #!graphviz
  digraph G {
  start="12";
  1->2 [label = "  1.2  ", len=0.6];
  2->3 [label = "  0.8  ", len=0.6];
  3->7 [label = "  0.5", len=0.6];
  4->5 [label = "  0.2  ", len=0.6];
  5->6 [label = "  10.1  ", len=0.6];
  5->3 [label = "  5.5", len=0.6];
  6->7 [label = "  2.0", len=0.6];
  7->2 [label = "  0.1", len=0.6];
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  It can be defined in dot format as such:

  {{{
  digraph G {
  1->2 [weight = "1.2"];
  2->3 [weight = "0.8"];
  3->7 [weight = "0.5"];
  4->5 [weight = "0.2"];
  5->6 [weight = "10.1"];
  5->3 [weight = "5.5"];
  6->7 [weight = "2.0"];
  7->2 [weight = "0.1"];
  }
  }}}

  and in graphml format as such:

  {{{
  <?xml version="1.0" encoding="UTF-8"?>
  <graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://graphml.graphdrawing.org/xmlns/1.0/graphml.xsd">
    <key id="d1" for="edge" attr.name="weight" attr.type="double"/>
    <graph id="G" edgedefault="directed">
      <node id="n0"/>
      <node id="n1"/>
      <node id="n2"/>
      <node id="n3"/>
      <node id="n4"/>
      <node id="n5"/>
      <node id="n6"/>
      <edge id="e0" source="n0" target="n1">
        <data key="d1">1.2</data>
      </edge>
      <edge id="e1" source="n1" target="n2">
        <data key="d1">0.8</data>
      </edge>
      <edge id="e2" source="n2" target="n6">
        <data key="d1">0.5</data>
      </edge>
      <edge id="e3" source="n3" target="n4">
        <data key="d1">0.2</data>
      </edge>
      <edge id="e4" source="n4" target="n5">
        <data key="d1">10.1</data>
      </edge>
      <edge id="e5" source="n4" target="n2">
        <data key="d1">5.5</data>
      </edge>
      <edge id="e6" source="n5" target="n6">
        <data key="d1">2.0</data>
      </edge>
      <edge id="e7" source="n6" target="n1">
        <data key="d1">0.1</data>
      </edge>
    </graph>
  </graphml>
  }}}


name: WikiStart
author: count0
ipnr: 201.52.69.185
text:
  = What is graph-tool? =
  [[Image(WikiStartAttachments:small.png, class=floatright, nolink)]] 

  graph-tool is a program to help with statistical analysis of [http://en.wikipedia.org/wiki/Graph_%28mathematics%29 graphs]. Its feature set includes:

   * support for directed and undirected graphs
   * support for arbitrary vertex or edge properties
   * generic filtering of edges and vertices
   * several statistical measurements:
     * degree (or scalar property) histogram
     * vertex-vertex degree (or scalar property) correlation
     * average nearest neighbours degree (or scalar property)
     * vertex-edge-vertex correlation
     * clustering coefficients
     * assortativity coefficient
     * average distance
     * component statistics
   * generation of random graphs with arbitrary degree distribution and degree correlation
   * support for [http://graphml.graphdrawing.org/ graphml] and [http://www.graphviz.org/ dot] file formats

  The core algorithms are written in C++, making use of the [http://www.boost.org/libs/graph/doc/ Boost Graph Library], and [http://www.awprofessional.com/bookstore/product.asp?isbn=0321227255&rl=1 template metaprogramming] techniques, with performace in mind. The command line interface is written in [http://www.python.org python].

  See GraphToolGuide for instructions and examples of how to use the program.

  graph-tool was written by [https://forked.de/bin/view/Main/TiagoPeixoto Tiago de Paula Peixoto] and is [http://www.gnu.org/philosophy/free-sw.html free software], released under the [http://www.gnu.org/copyleft/gpl.html GPL].


name: GraphToolGuide
author: count0
ipnr: 201.52.69.185
text:
  = graph-tool Guide =

  [[PageOutline]]

  == Invoking ==

  graph-tool is invoked by typing {{{graph-tool}}} in the command line. For a quick summary of options type
  {{{
  graph-tool --help
  }}}


  == Loading and saving files ==

  Files can be loaded with the {{{--load}}} option. Graph tool supports both [http://graphml.graphdrawing.org/ graphml] and [http://www.graphviz.org/ dot] formats. The formats are identified by the file name extension: files ending in {{{.xml}}} are considered graphml files, and files ending in {{{.dot}}} are considered dot files. Files can also end in {{{.gz}}} or {{{.bz2}}} to indicate compression, such as {{{.xml.gz}}} or {{{.dot.bz2}}}. Files can be saved with the {{{--save}}} command, and the file name specifications are the same.

  === File format description ===

  Consider the following directed graph, with one floating point edge property (which will be called "weight"):
  {{{
  #!html
  <div style="text-align: center;">
  }}}
  {{{
  #!graphviz
  digraph G {
  start="12";
  1->2 [label = "  1.2  ", len=0.6];
  2->3 [label = "  0.8  ", len=0.6];
  3->7 [label = "  0.5", len=0.6];
  4->5 [label = "  0.2  ", len=0.6];
  5->6 [label = "  10.1  ", len=0.6];
  5->3 [label = "  5.5", len=0.6];
  6->7 [label = "  2.0", len=0.6];
  7->2 [label = "  0.1", len=0.6];
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  It can be defined in dot format as such:

  {{{
  digraph G {
  1->2 [weight = "1.2"];
  2->3 [weight = "0.8"];
  3->7 [weight = "0.5"];
  4->5 [weight = "0.2"];
  5->6 [weight = "10.1"];
  5->3 [weight = "5.5"];
  6->7 [weight = "2.0"];
  7->2 [weight = "0.1"];
  }
  }}}

  and in graphml format as such:

  {{{
  #!xml
  <?xml version="1.0" encoding="UTF-8"?>
  <graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://graphml.graphdrawing.org/xmlns/1.0/graphml.xsd">
    <key id="d1" for="edge" attr.name="weight" attr.type="double"/>
    <graph id="G" edgedefault="directed">
      <node id="n0"/>
      <node id="n1"/>
      <node id="n2"/>
      <node id="n3"/>
      <node id="n4"/>
      <node id="n5"/>
      <node id="n6"/>
      <edge id="e0" source="n0" target="n1">
        <data key="d1">1.2</data>
      </edge>
      <edge id="e1" source="n1" target="n2">
        <data key="d1">0.8</data>
      </edge>
      <edge id="e2" source="n2" target="n6">
        <data key="d1">0.5</data>
      </edge>
      <edge id="e3" source="n3" target="n4">
        <data key="d1">0.2</data>
      </edge>
      <edge id="e4" source="n4" target="n5">
        <data key="d1">10.1</data>
      </edge>
      <edge id="e5" source="n4" target="n2">
        <data key="d1">5.5</data>
      </edge>
      <edge id="e6" source="n5" target="n6">
        <data key="d1">2.0</data>
      </edge>
      <edge id="e7" source="n6" target="n1">
        <data key="d1">0.1</data>
      </edge>
    </graph>
  </graphml>
  }}}


name: GraphToolGuide
author: count0
ipnr: 201.52.69.185
text:
  = graph-tool Guide =

  [[PageOutline]]

  == Invoking ==

  graph-tool is invoked by typing {{{graph-tool}}} in the command line. For a quick summary of options type
  {{{
  graph-tool --help
  }}}


  == Loading and saving files ==

  Files can be loaded with the {{{--load}}} option. Graph tool supports both [http://graphml.graphdrawing.org/ graphml] and [http://www.graphviz.org/ dot] formats. The formats are identified by the file name extension: files ending in {{{.xml}}} are considered graphml files, and files ending in {{{.dot}}} are considered dot files. Files can also end in {{{.gz}}} or {{{.bz2}}} to indicate compression, such as {{{.xml.gz}}} or {{{.dot.bz2}}}. Files can be saved with the {{{--save}}} command, and the file name specifications are the same.

  === File format description ===

  Consider the following directed graph, with one floating point edge property (which will be called "weight"):
  {{{
  #!html
  <div style="text-align: center;">
  }}}
  {{{
  #!graphviz
  digraph G {
  start="12";
  1->2 [label = "  1.2  ", len=0.6];
  2->3 [label = "  0.8  ", len=0.6];
  3->7 [label = "  0.5", len=0.6];
  4->5 [label = "  0.2  ", len=0.6];
  5->6 [label = "  10.1  ", len=0.6];
  5->3 [label = "  5.5", len=0.6];
  6->7 [label = "  2.0", len=0.6];
  7->2 [label = "  0.1", len=0.6];
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  It can be defined in dot format as such:

  {{{
  digraph G {
  1->2 [weight = "1.2"];
  2->3 [weight = "0.8"];
  3->7 [weight = "0.5"];
  4->5 [weight = "0.2"];
  5->6 [weight = "10.1"];
  5->3 [weight = "5.5"];
  6->7 [weight = "2.0"];
  7->2 [weight = "0.1"];
  }
  }}}

  and in graphml format as such:

  {{{
  #!text/xml
  <?xml version="1.0" encoding="UTF-8"?>
  <graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://graphml.graphdrawing.org/xmlns/1.0/graphml.xsd">
    <key id="d1" for="edge" attr.name="weight" attr.type="double"/>
    <graph id="G" edgedefault="directed">
      <node id="n0"/>
      <node id="n1"/>
      <node id="n2"/>
      <node id="n3"/>
      <node id="n4"/>
      <node id="n5"/>
      <node id="n6"/>
      <edge id="e0" source="n0" target="n1">
        <data key="d1">1.2</data>
      </edge>
      <edge id="e1" source="n1" target="n2">
        <data key="d1">0.8</data>
      </edge>
      <edge id="e2" source="n2" target="n6">
        <data key="d1">0.5</data>
      </edge>
      <edge id="e3" source="n3" target="n4">
        <data key="d1">0.2</data>
      </edge>
      <edge id="e4" source="n4" target="n5">
        <data key="d1">10.1</data>
      </edge>
      <edge id="e5" source="n4" target="n2">
        <data key="d1">5.5</data>
      </edge>
      <edge id="e6" source="n5" target="n6">
        <data key="d1">2.0</data>
      </edge>
      <edge id="e7" source="n6" target="n1">
        <data key="d1">0.1</data>
      </edge>
    </graph>
  </graphml>
  }}}


name: GraphToolGuide
author: count0
ipnr: 201.52.69.185
text:
  = graph-tool Guide =

  [[PageOutline]]

  == Invoking ==

  graph-tool is invoked by typing {{{graph-tool}}} in the command line. For a quick summary of options type
  {{{
  graph-tool --help
  }}}


  == Loading and saving files ==

  Files can be loaded with the {{{--load}}} option. Graph tool supports both [http://graphml.graphdrawing.org/ graphml] and [http://www.graphviz.org/ dot] formats. The formats are identified by the file name extension: files ending in {{{.xml}}} are considered graphml files, and files ending in {{{.dot}}} are considered dot files. Files can also end in {{{.gz}}} or {{{.bz2}}} to indicate compression, such as {{{.xml.gz}}} or {{{.dot.bz2}}}. Files can be saved with the {{{--save}}} command, and the file name specifications are the same.

  === File format description ===

  Consider the following directed graph, with one floating point edge property (which will be called "weight"):
  {{{
  #!html
  <div style="text-align: center;">
  }}}
  {{{
  #!graphviz
  digraph G {
  start="12";
  1->2 [label = "  1.2  ", len=0.6];
  2->3 [label = "  0.8  ", len=0.6];
  3->7 [label = "  0.5", len=0.6];
  4->5 [label = "  0.2  ", len=0.6];
  5->6 [label = "  10.1  ", len=0.6];
  5->3 [label = "  5.5", len=0.6];
  6->7 [label = "  2.0", len=0.6];
  7->2 [label = "  0.1", len=0.6];
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  It can be defined in dot format as such:

  {{{
  digraph G {
  1->2 [weight = "1.2"];
  2->3 [weight = "0.8"];
  3->7 [weight = "0.5"];
  4->5 [weight = "0.2"];
  5->6 [weight = "10.1"];
  5->3 [weight = "5.5"];
  6->7 [weight = "2.0"];
  7->2 [weight = "0.1"];
  }
  }}}

  and in graphml format as such:

  {{{
  #!xml
  <?xml version="1.0" encoding="UTF-8"?>
  <graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://graphml.graphdrawing.org/xmlns/1.0/graphml.xsd">
    <key id="d1" for="edge" attr.name="weight" attr.type="double"/>
    <graph id="G" edgedefault="directed">
      <node id="n0"/>
      <node id="n1"/>
      <node id="n2"/>
      <node id="n3"/>
      <node id="n4"/>
      <node id="n5"/>
      <node id="n6"/>
      <edge id="e0" source="n0" target="n1">
        <data key="d1">1.2</data>
      </edge>
      <edge id="e1" source="n1" target="n2">
        <data key="d1">0.8</data>
      </edge>
      <edge id="e2" source="n2" target="n6">
        <data key="d1">0.5</data>
      </edge>
      <edge id="e3" source="n3" target="n4">
        <data key="d1">0.2</data>
      </edge>
      <edge id="e4" source="n4" target="n5">
        <data key="d1">10.1</data>
      </edge>
      <edge id="e5" source="n4" target="n2">
        <data key="d1">5.5</data>
      </edge>
      <edge id="e6" source="n5" target="n6">
        <data key="d1">2.0</data>
      </edge>
      <edge id="e7" source="n6" target="n1">
        <data key="d1">0.1</data>
      </edge>
    </graph>
  </graphml>
  }}}

  {{{
  #!html
  <div class="note">
  }}}
  '''Note''': ''graphml files are preferred...''
  {{{
  #!html
  </div>
  }}}


name: WikiStart
author: count0
ipnr: 201.52.69.185
text:
  = What is graph-tool? =
  [[Image(WikiStartAttachments:small.png, class=floatright, nolink)]] 

  graph-tool is a program to help with statistical analysis of [http://en.wikipedia.org/wiki/Graph_%28mathematics%29 graphs]. Its feature set includes:

   * support for directed and undirected graphs
   * support for arbitrary vertex or edge properties
   * generic filtering of edges and vertices
   * several statistical measurements:
     * degree (or scalar property) histogram
     * vertex-vertex degree (or scalar property) correlation
     * average nearest neighbours degree (or scalar property)
     * vertex-edge-vertex correlation
     * clustering coefficients
     * assortativity coefficient
     * average distance
     * component statistics
   * generation of random graphs with arbitrary degree distribution and degree correlation
   * support for [http://graphml.graphdrawing.org/ graphml] and [http://www.graphviz.org/ dot] file formats

  The core algorithms are written in C++, making use of the [http://www.boost.org/libs/graph/doc/ Boost Graph Library], and [http://www.awprofessional.com/bookstore/product.asp?isbn=0321227255&rl=1 template metaprogramming] techniques, with performace in mind. The command line interface and other outlying code are written in [http://www.python.org python].

  See GraphToolGuide for instructions and examples of how to use the program.

  graph-tool was written by [https://forked.de/bin/view/Main/TiagoPeixoto Tiago de Paula Peixoto] and is [http://www.gnu.org/philosophy/free-sw.html free software], released under the [http://www.gnu.org/copyleft/gpl.html GPL].


name: GraphToolGuide
author: count0
ipnr: 201.52.69.185
text:
  = graph-tool Guide =

  [[PageOutline]]

  == Invoking ==

  graph-tool is invoked by typing {{{graph-tool}}} in the command line. For a quick summary of options type
  {{{
  graph-tool --help
  }}}


  == Loading and saving files ==

  Files can be loaded with the {{{--load}}} option. Graph tool supports both [http://graphml.graphdrawing.org/ graphml] and [http://www.graphviz.org/ dot] formats. The formats are identified by the file name extension: files ending in {{{.xml}}} are considered graphml files, and files ending in {{{.dot}}} are considered dot files. Files can also end in {{{.gz}}} or {{{.bz2}}} to indicate compression, such as {{{.xml.gz}}} or {{{.dot.bz2}}}. Files can be saved with the {{{--save}}} command, and the file name specifications are the same.

  === File format description ===

  Consider the following directed graph, with one floating point edge property (which will be called "weight"):
  {{{
  #!html
  <div style="text-align: center;">
  }}}
  {{{
  #!graphviz
  digraph G {
  start="12";
  1->2 [label = "  1.2  ", len=0.6];
  2->3 [label = "  0.8  ", len=0.6];
  3->7 [label = "  0.5", len=0.6];
  4->5 [label = "  0.2  ", len=0.6];
  5->6 [label = "  10.1  ", len=0.6];
  5->3 [label = "  5.5", len=0.6];
  6->7 [label = "  2.0", len=0.6];
  7->2 [label = "  0.1", len=0.6];
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  It can be defined in dot format as such:

  {{{
  digraph G {
  1->2 [weight = "1.2"];
  2->3 [weight = "0.8"];
  3->7 [weight = "0.5"];
  4->5 [weight = "0.2"];
  5->6 [weight = "10.1"];
  5->3 [weight = "5.5"];
  6->7 [weight = "2.0"];
  7->2 [weight = "0.1"];
  }
  }}}

  and in graphml format as such:

  {{{
  #!xml
  <?xml version="1.0" encoding="UTF-8"?>
  <graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://graphml.graphdrawing.org/xmlns/1.0/graphml.xsd">
    <key id="d1" for="edge" attr.name="weight" attr.type="double"/>
    <graph id="G" edgedefault="directed">
      <node id="n0"/>
      <node id="n1"/>
      <node id="n2"/>
      <node id="n3"/>
      <node id="n4"/>
      <node id="n5"/>
      <node id="n6"/>
      <edge id="e0" source="n0" target="n1">
        <data key="d1">1.2</data>
      </edge>
      <edge id="e1" source="n1" target="n2">
        <data key="d1">0.8</data>
      </edge>
      <edge id="e2" source="n2" target="n6">
        <data key="d1">0.5</data>
      </edge>
      <edge id="e3" source="n3" target="n4">
        <data key="d1">0.2</data>
      </edge>
      <edge id="e4" source="n4" target="n5">
        <data key="d1">10.1</data>
      </edge>
      <edge id="e5" source="n4" target="n2">
        <data key="d1">5.5</data>
      </edge>
      <edge id="e6" source="n5" target="n6">
        <data key="d1">2.0</data>
      </edge>
      <edge id="e7" source="n6" target="n1">
        <data key="d1">0.1</data>
      </edge>
    </graph>
  </graphml>
  }}}

  Vertex properties are done in an analogous manner. There's not limit on the number of properties the graph can have. 

  Graphs can also be undirected, and are loaded by specifiyng the option {{{--undirected}}} before {{{--load}}}. Here's an example:

  {{{
  #!html
  <div style="text-align: center;">
  }}}
  {{{
  #!graphviz
  graph G {
  start="12";
  1--2 
  2--3 
  3--7 
  4--5 
  5--6 
  5--3 
  6--7 
  7--2 
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  In dot format:

  {{{
  graph G {
  1--2 
  2--3 
  3--7 
  4--5 
  5--6 
  5--3 
  6--7 
  7--2 
  }
  }}}

  and in graphml format:

  {{{
  #!xml
  <?xml version="1.0" encoding="UTF-8"?>
  <graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://graphml.graphdrawing.org/xmlns/1.0/graphml.xsd">
    <graph id="G" edgedefault="undirected">
      <node id="n0"/>
      <node id="n1"/>
      <node id="n2"/>
      <node id="n3"/>
      <node id="n4"/>
      <node id="n5"/>
      <node id="n6"/>
      <edge id="e0" source="n0" target="n1"/>
      <edge id="e1" source="n1" target="n2"/>
      <edge id="e2" source="n2" target="n6"/>
      <edge id="e3" source="n3" target="n4"/>
      <edge id="e4" source="n4" target="n5"/>
      <edge id="e5" source="n4" target="n2"/>
      <edge id="e6" source="n5" target="n6"/>
      <edge id="e7" source="n6" target="n1"/>
    </graph>
  </graphml>
  }}}

  {{{
  #!html
  <div class="note">
  }}}
  ==== Which format to use? ====
  You can of course use either format, but in general graphml is preferred. It provides for a tighter definition of the graph, and since graph-tool understants the parse info attributes of the graph, you can speed up the loading of the file and reduce memory usage by using the following in your graph definition:

  {{{
  #!xml
  ...
   <graph id="G" edgedefault="directed" parse.nodeids="canonical" parse.edgeids="canonical" parse.order="nodesfirst">
  ...
  }}}

  This says that all vertices and edges are named "n0","n1", ..., "nN-1", and  "e0", "e1", ..., "eE-1", respectively. And also it says that the vertex list comes before the edge list. You're not forced to define your graph this way, but it does improve performace for large graphs.

  {{{
  #!html
  </div>
  }}}


name: GraphToolGuide
author: count0
ipnr: 201.52.69.185
text:
  = graph-tool Guide =

  [[PageOutline]]

  == Invoking ==

  graph-tool is invoked by typing {{{graph-tool}}} in the command line. For a quick summary of options type
  {{{
  graph-tool --help
  }}}


  == Loading and saving files ==

  Files can be loaded with the "{{{--load}}}" option. Graph tool supports both [http://graphml.graphdrawing.org/ graphml] and [http://www.graphviz.org/ dot] formats. The formats are identified by the file name extension: files ending in {{{.xml}}} are considered graphml files, and files ending in {{{.dot}}} are considered dot files. Files can also end in {{{.gz}}} or {{{.bz2}}} to indicate compression, such as {{{.xml.gz}}} or {{{.dot.bz2}}}. Files can be saved with the "{{{--save}}}" command, and the file name specifications are the same.

  === File format description ===

  Consider the following directed graph, with one floating point edge property (which will be called "weight"):
  {{{
  #!html
  <div style="text-align: center;">
  }}}
  {{{
  #!graphviz
  digraph G {
  start="12";
  1->2 [label = "  1.2  ", len=0.6];
  2->3 [label = "  0.8  ", len=0.6];
  3->7 [label = "  0.5", len=0.6];
  4->5 [label = "  0.2  ", len=0.6];
  5->6 [label = "  10.1  ", len=0.6];
  5->3 [label = "  5.5", len=0.6];
  6->7 [label = "  2.0", len=0.6];
  7->2 [label = "  0.1", len=0.6];
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  It can be defined in dot format as such:

  {{{
  digraph G {
  1->2 [weight = "1.2"];
  2->3 [weight = "0.8"];
  3->7 [weight = "0.5"];
  4->5 [weight = "0.2"];
  5->6 [weight = "10.1"];
  5->3 [weight = "5.5"];
  6->7 [weight = "2.0"];
  7->2 [weight = "0.1"];
  }
  }}}

  and in graphml format as such:

  {{{
  #!xml
  <?xml version="1.0" encoding="UTF-8"?>
  <graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://graphml.graphdrawing.org/xmlns/1.0/graphml.xsd">
    <key id="d1" for="edge" attr.name="weight" attr.type="double"/>
    <graph id="G" edgedefault="directed">
      <node id="n0"/>
      <node id="n1"/>
      <node id="n2"/>
      <node id="n3"/>
      <node id="n4"/>
      <node id="n5"/>
      <node id="n6"/>
      <edge id="e0" source="n0" target="n1">
        <data key="d1">1.2</data>
      </edge>
      <edge id="e1" source="n1" target="n2">
        <data key="d1">0.8</data>
      </edge>
      <edge id="e2" source="n2" target="n6">
        <data key="d1">0.5</data>
      </edge>
      <edge id="e3" source="n3" target="n4">
        <data key="d1">0.2</data>
      </edge>
      <edge id="e4" source="n4" target="n5">
        <data key="d1">10.1</data>
      </edge>
      <edge id="e5" source="n4" target="n2">
        <data key="d1">5.5</data>
      </edge>
      <edge id="e6" source="n5" target="n6">
        <data key="d1">2.0</data>
      </edge>
      <edge id="e7" source="n6" target="n1">
        <data key="d1">0.1</data>
      </edge>
    </graph>
  </graphml>
  }}}

  Vertex properties are done in an analogous manner. There's no limit on the number of properties the graph can have. 

  Graphs can also be undirected, and are loaded by specifiyng the option "{{{--undirected}}}" before "{{{--load}}}". Here's an example:

  {{{
  #!html
  <div style="text-align: center;">
  }}}
  {{{
  #!graphviz
  graph G {
  start="12";
  1--2 
  2--3 
  3--7 
  4--5 
  5--6 
  5--3 
  6--7 
  7--2 
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  In dot format:

  {{{
  graph G {
  1--2 
  2--3 
  3--7 
  4--5 
  5--6 
  5--3 
  6--7 
  7--2 
  }
  }}}

  and in graphml format:

  {{{
  #!xml
  <?xml version="1.0" encoding="UTF-8"?>
  <graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://graphml.graphdrawing.org/xmlns/1.0/graphml.xsd">
    <graph id="G" edgedefault="undirected">
      <node id="n0"/>
      <node id="n1"/>
      <node id="n2"/>
      <node id="n3"/>
      <node id="n4"/>
      <node id="n5"/>
      <node id="n6"/>
      <edge id="e0" source="n0" target="n1"/>
      <edge id="e1" source="n1" target="n2"/>
      <edge id="e2" source="n2" target="n6"/>
      <edge id="e3" source="n3" target="n4"/>
      <edge id="e4" source="n4" target="n5"/>
      <edge id="e5" source="n4" target="n2"/>
      <edge id="e6" source="n5" target="n6"/>
      <edge id="e7" source="n6" target="n1"/>
    </graph>
  </graphml>
  }}}

  {{{
  #!html
  <div class="note">
  }}}
  ==== Which format to use? ====

  You can of course use either format, but in general graphml is preferred. It provides for a tighter definition of the graph, and since graph-tool understants the parse info attributes of the graph, you can speed up the loading of the file and reduce memory usage by using the following in your graph definition:

  {{{
  #!xml
  ...
   <graph id="G" edgedefault="directed" parse.nodeids="canonical" parse.edgeids="canonical" parse.order="nodesfirst">
  ...
  }}}

  This says that all vertices and edges are named "n0","n1", ..., "nN-1", and  "e0", "e1", ..., "eE-1", respectively. And also it says that the vertex list comes before the edge list. You're not forced to define your graph this way, but it does improve performace for large graphs.

  {{{
  #!html
  </div>
  }}}

  ----

  == Basic Statistics ==

  The two most basic properties of the graph are the number of vertex and edges, which is obtainable through the "{{{--number-of-vertices}}}" and "{{{--number-of-edges}}}" options. Suppose the first graph in [[ref(File Format Description)]] is saved under {{{example.xml}}}. We can then get the number of vertices and edges by typing:

  {{{
  $ graph-tool --load example.xml --number-of-vertices=- --number-of-edges=-
  number of vertices:     7
  number of edges:        8
  }}}

  The "-" parameter to the options is necessary to output the results in the terminal. Otherwise it writes it to the file given in the parameter.

  === Degree Distribution ===

  The degree distribution can be obtained by the "{{{--degree-distribution}}}" option. It requires two parameters: degree type and file name. Degree type can be any of "in-degree", "out-degree", "total-degree" and _any vertex scalar property_. The file name is the file the histogram is written to, or "-" to be written to the terminal. Files may be terminated with {{{.gz}}} or {{{.bz2}}} for compression. Example:

  {{{
  $ graph-tool --load example.xml --degree-histogram="total-degree|deg-dist"
  $ cat deg-dist
  1.0     2
  2.0     1
  3.0     4
  }}}


  == Filtering ==

  == Graph Modifications ==

  == Correlations ==
  == Clustering ==
  == Layout ==
  == Random Graph Generation ==
  == Graph History ==


name: GraphToolGuide
author: count0
ipnr: 201.52.69.185
text:
  = graph-tool Guide =

  [[PageOutline]]

  == Invoking ==

  graph-tool is invoked by typing {{{graph-tool}}} in the command line. For a quick summary of options type
  {{{
  graph-tool --help
  }}}


  == Loading and saving files ==

  Files can be loaded with the "{{{--load}}}" option. Graph tool supports both [http://graphml.graphdrawing.org/ graphml] and [http://www.graphviz.org/ dot] formats. The formats are identified by the file name extension: files ending in {{{.xml}}} are considered graphml files, and files ending in {{{.dot}}} are considered dot files. Files can also end in {{{.gz}}} or {{{.bz2}}} to indicate compression, such as {{{.xml.gz}}} or {{{.dot.bz2}}}. Files can be saved with the "{{{--save}}}" command, and the file name specifications are the same.

  === File format description ===

  Consider the following directed graph, with one floating point edge property (which will be called "weight"):
  {{{
  #!html
  <div style="text-align: center;">
  }}}
  {{{
  #!graphviz
  digraph G {
  start="12";
  1->2 [label = "  1.2  ", len=0.6];
  2->3 [label = "  0.8  ", len=0.6];
  3->7 [label = "  0.5", len=0.6];
  4->5 [label = "  0.2  ", len=0.6];
  5->6 [label = "  10.1  ", len=0.6];
  5->3 [label = "  5.5", len=0.6];
  6->7 [label = "  2.0", len=0.6];
  7->2 [label = "  0.1", len=0.6];
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  It can be defined in dot format as such:

  {{{
  digraph G {
  1->2 [weight = "1.2"];
  2->3 [weight = "0.8"];
  3->7 [weight = "0.5"];
  4->5 [weight = "0.2"];
  5->6 [weight = "10.1"];
  5->3 [weight = "5.5"];
  6->7 [weight = "2.0"];
  7->2 [weight = "0.1"];
  }
  }}}

  and in graphml format as such:

  {{{
  #!xml
  <?xml version="1.0" encoding="UTF-8"?>
  <graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://graphml.graphdrawing.org/xmlns/1.0/graphml.xsd">
    <key id="d1" for="edge" attr.name="weight" attr.type="double"/>
    <graph id="G" edgedefault="directed">
      <node id="n0"/>
      <node id="n1"/>
      <node id="n2"/>
      <node id="n3"/>
      <node id="n4"/>
      <node id="n5"/>
      <node id="n6"/>
      <edge id="e0" source="n0" target="n1">
        <data key="d1">1.2</data>
      </edge>
      <edge id="e1" source="n1" target="n2">
        <data key="d1">0.8</data>
      </edge>
      <edge id="e2" source="n2" target="n6">
        <data key="d1">0.5</data>
      </edge>
      <edge id="e3" source="n3" target="n4">
        <data key="d1">0.2</data>
      </edge>
      <edge id="e4" source="n4" target="n5">
        <data key="d1">10.1</data>
      </edge>
      <edge id="e5" source="n4" target="n2">
        <data key="d1">5.5</data>
      </edge>
      <edge id="e6" source="n5" target="n6">
        <data key="d1">2.0</data>
      </edge>
      <edge id="e7" source="n6" target="n1">
        <data key="d1">0.1</data>
      </edge>
    </graph>
  </graphml>
  }}}

  Vertex properties are done in an analogous manner. There's no limit on the number of properties the graph can have. 

  Graphs can also be undirected, and are loaded by specifiyng the option "{{{--undirected}}}" before "{{{--load}}}". Here's an example:

  {{{
  #!html
  <div style="text-align: center;">
  }}}
  {{{
  #!graphviz
  graph G {
  start="12";
  1--2 
  2--3 
  3--7 
  4--5 
  5--6 
  5--3 
  6--7 
  7--2 
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  In dot format:

  {{{
  graph G {
  1--2 
  2--3 
  3--7 
  4--5 
  5--6 
  5--3 
  6--7 
  7--2 
  }
  }}}

  and in graphml format:

  {{{
  #!xml
  <?xml version="1.0" encoding="UTF-8"?>
  <graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://graphml.graphdrawing.org/xmlns/1.0/graphml.xsd">
    <graph id="G" edgedefault="undirected">
      <node id="n0"/>
      <node id="n1"/>
      <node id="n2"/>
      <node id="n3"/>
      <node id="n4"/>
      <node id="n5"/>
      <node id="n6"/>
      <edge id="e0" source="n0" target="n1"/>
      <edge id="e1" source="n1" target="n2"/>
      <edge id="e2" source="n2" target="n6"/>
      <edge id="e3" source="n3" target="n4"/>
      <edge id="e4" source="n4" target="n5"/>
      <edge id="e5" source="n4" target="n2"/>
      <edge id="e6" source="n5" target="n6"/>
      <edge id="e7" source="n6" target="n1"/>
    </graph>
  </graphml>
  }}}

  {{{
  #!html
  <div class="note">
  }}}
  ==== Which format to use? ====

  You can of course use either format, but in general graphml is preferred. It provides for a tighter definition of the graph, and since graph-tool understants the parse info attributes of the graph, you can speed up the loading of the file and reduce memory usage by using the following in your graph definition:

  {{{
  #!xml
  ...
   <graph id="G" edgedefault="directed" parse.nodeids="canonical" parse.edgeids="canonical" parse.order="nodesfirst">
  ...
  }}}

  This says that all vertices and edges are named "n0","n1", ..., "nN-1", and  "e0", "e1", ..., "eE-1", respectively. And also it says that the vertex list comes before the edge list. You're not forced to define your graph this way, but it does improve performace for large graphs.

  {{{
  #!html
  </div>
  }}}

  ----

  == Basic Statistics ==

  The two most basic properties of the graph are the number of vertex and edges, which is obtainable through the "{{{--number-of-vertices}}}" and "{{{--number-of-edges}}}" options. Suppose the first graph in [[ref(File Format Description)]] is saved under {{{example.xml}}}. We can then get the number of vertices and edges by typing:

  {{{
  $ graph-tool --load example.xml --number-of-vertices=- --number-of-edges=-
  number of vertices:     7
  number of edges:        8
  }}}

  The "-" parameter to the options is necessary to output the results in the terminal. Otherwise it writes it to the file given in the parameter.

  === Degree Histogram ===

  The degree histogram can be obtained by the "{{{--degree-histogram}}}" option. It requires two parameters, separated by "|": degree type and file name. Degree type can be any of "in-degree", "out-degree", "total-degree" and __any vertex scalar property__. The file name is the file the histogram is written to, or "-" to be written to the terminal. Files may be terminated with {{{.gz}}} or {{{.bz2}}} for compression. Example:

  {{{
  $ graph-tool --load example.xml --degree-histogram="total-degree|deg-dist"
  $ cat deg-dist
  1.0     2
  2.0     1
  3.0     4
  }}}

  For directed graphs, it is also possible to get the combined (in,out)-degree histogram with the "{{{--combined-degree-histogram}}}" option:

  {{{
  $ graph-tool --load example.xml --combined-degree-histogram="deg-dist"
  $ cat deg-dist
  0.0     1.0     2
  1.0     1.0     1
  1.0     2.0     1
  2.0     1.0     3
  }}}

  === Average Distance ===

  The average vertex-vertex distance can be obtained with the "{{{--average-distance}}}" option:

  {{{
  $ graph-tool --load example.xml --average-distance=-
  average distance:       0.714285714286
  }}}

  For directed and/or disconnected graphs, it may be better to use the average harmonic distance defined as:

  [[Equation(\[d_h = \left[\sum_{v,u}\frac{1}{d_{uv}}\right]^{-1}\])]], where [[Equation($d_{uv}$)]] is the regular graph distance between [[Equation($u$)]] and [[Equation($v$)]], which here is taken to be infinity when there's no path between those two vertices.

  Example:

  {{{
  $ graph-tool --load example.xml --average-harmonic-distance=-
  average harmonic distance:      4.1226993865
  }}}

  === Component Size Histogram === 


  == Filtering ==

  == Graph Modifications ==

  == Correlations ==
  == Clustering ==
  == Layout ==
  == Random Graph Generation ==
  == Graph History ==


name: GraphToolGuide
author: count0
ipnr: 201.52.69.185
text:
  = graph-tool Guide =

  [[PageOutline]]

  == Invoking ==

  graph-tool is invoked by typing {{{graph-tool}}} in the command line. For a quick summary of options type
  {{{
  graph-tool --help
  }}}


  == Loading and saving files ==

  Files can be loaded with the "{{{--load}}}" option. Graph tool supports both [http://graphml.graphdrawing.org/ graphml] and [http://www.graphviz.org/ dot] formats. The formats are identified by the file name extension: files ending in {{{.xml}}} are considered graphml files, and files ending in {{{.dot}}} are considered dot files. Files can also end in {{{.gz}}} or {{{.bz2}}} to indicate compression, such as {{{.xml.gz}}} or {{{.dot.bz2}}}. Files can be saved with the "{{{--save}}}" command, and the file name specifications are the same.

  === File format description ===

  Consider the following directed graph, with one floating point edge property (which will be called "weight"):
  {{{
  #!html
  <div style="text-align: center;">
  }}}
  {{{
  #!graphviz
  digraph G {
  start="12";
  1->2 [label = "  1.2  ", len=0.6];
  2->3 [label = "  0.8  ", len=0.6];
  3->7 [label = "  0.5", len=0.6];
  4->5 [label = "  0.2  ", len=0.6];
  5->6 [label = "  10.1  ", len=0.6];
  5->3 [label = "  5.5", len=0.6];
  6->7 [label = "  2.0", len=0.6];
  7->2 [label = "  0.1", len=0.6];
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  It can be defined in dot format as such:

  {{{
  digraph G {
  1->2 [weight = "1.2"];
  2->3 [weight = "0.8"];
  3->7 [weight = "0.5"];
  4->5 [weight = "0.2"];
  5->6 [weight = "10.1"];
  5->3 [weight = "5.5"];
  6->7 [weight = "2.0"];
  7->2 [weight = "0.1"];
  }
  }}}

  and in graphml format as such:

  {{{
  #!xml
  <?xml version="1.0" encoding="UTF-8"?>
  <graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://graphml.graphdrawing.org/xmlns/1.0/graphml.xsd">
    <key id="d1" for="edge" attr.name="weight" attr.type="double"/>
    <graph id="G" edgedefault="directed">
      <node id="n0"/>
      <node id="n1"/>
      <node id="n2"/>
      <node id="n3"/>
      <node id="n4"/>
      <node id="n5"/>
      <node id="n6"/>
      <edge id="e0" source="n0" target="n1">
        <data key="d1">1.2</data>
      </edge>
      <edge id="e1" source="n1" target="n2">
        <data key="d1">0.8</data>
      </edge>
      <edge id="e2" source="n2" target="n6">
        <data key="d1">0.5</data>
      </edge>
      <edge id="e3" source="n3" target="n4">
        <data key="d1">0.2</data>
      </edge>
      <edge id="e4" source="n4" target="n5">
        <data key="d1">10.1</data>
      </edge>
      <edge id="e5" source="n4" target="n2">
        <data key="d1">5.5</data>
      </edge>
      <edge id="e6" source="n5" target="n6">
        <data key="d1">2.0</data>
      </edge>
      <edge id="e7" source="n6" target="n1">
        <data key="d1">0.1</data>
      </edge>
    </graph>
  </graphml>
  }}}

  Vertex properties are done in an analogous manner. There's no limit on the number of properties the graph can have. 

  Graphs can also be undirected, and are loaded by specifiyng the option "{{{--undirected}}}" before "{{{--load}}}". Here's an example:

  {{{
  #!html
  <div style="text-align: center;">
  }}}
  {{{
  #!graphviz
  graph G {
  start="12";
  1--2 
  2--3 
  3--7 
  4--5 
  5--6 
  5--3 
  6--7 
  7--2 
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  In dot format:

  {{{
  graph G {
  1--2 
  2--3 
  3--7 
  4--5 
  5--6 
  5--3 
  6--7 
  7--2 
  }
  }}}

  and in graphml format:

  {{{
  #!xml
  <?xml version="1.0" encoding="UTF-8"?>
  <graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://graphml.graphdrawing.org/xmlns/1.0/graphml.xsd">
    <graph id="G" edgedefault="undirected">
      <node id="n0"/>
      <node id="n1"/>
      <node id="n2"/>
      <node id="n3"/>
      <node id="n4"/>
      <node id="n5"/>
      <node id="n6"/>
      <edge id="e0" source="n0" target="n1"/>
      <edge id="e1" source="n1" target="n2"/>
      <edge id="e2" source="n2" target="n6"/>
      <edge id="e3" source="n3" target="n4"/>
      <edge id="e4" source="n4" target="n5"/>
      <edge id="e5" source="n4" target="n2"/>
      <edge id="e6" source="n5" target="n6"/>
      <edge id="e7" source="n6" target="n1"/>
    </graph>
  </graphml>
  }}}

  {{{
  #!html
  <div class="note">
  }}}
  ==== Which format to use? ====

  You can of course use either format, but in general graphml is preferred. It provides for a tighter definition of the graph, and since graph-tool understants the parse info attributes of the graph, you can speed up the loading of the file and reduce memory usage by using the following in your graph definition:

  {{{
  #!xml
  ...
   <graph id="G" edgedefault="directed" parse.nodeids="canonical" parse.edgeids="canonical" parse.order="nodesfirst">
  ...
  }}}

  This says that all vertices and edges are named "n0","n1", ..., "nN-1", and  "e0", "e1", ..., "eE-1", respectively. And also it says that the vertex list comes before the edge list. You're not forced to define your graph this way, but it does improve performace for large graphs.

  {{{
  #!html
  </div>
  }}}

  ----

  == Basic Statistics ==

  The two most basic properties of the graph are the number of vertex and edges, which is obtainable through the "{{{--number-of-vertices}}}" and "{{{--number-of-edges}}}" options. Suppose the first graph in [[ref(File Format Description)]] is saved under {{{example.xml}}}. We can then get the number of vertices and edges by typing:

  {{{
  $ graph-tool --load example.xml --number-of-vertices=- --number-of-edges=-
  number of vertices:     7
  number of edges:        8
  }}}

  The "-" parameter to the options is necessary to output the results in the terminal. Otherwise it writes it to the file given in the parameter.

  === Degree Histogram ===

  The degree histogram can be obtained by the "{{{--degree-histogram}}}" option. It requires two parameters, separated by "|": degree type and file name. Degree type can be any of "in-degree", "out-degree", "total-degree" and __any vertex scalar property__. The file name is the file the histogram is written to, or "-" to be written to the terminal. Files may be terminated with {{{.gz}}} or {{{.bz2}}} for compression. Example:

  {{{
  $ graph-tool --load example.xml --degree-histogram="total-degree|deg-dist"
  $ cat deg-dist
  1.0     2
  2.0     1
  3.0     4
  }}}

  For directed graphs, it is also possible to get the combined (in,out)-degree histogram with the "{{{--combined-degree-histogram}}}" option:

  {{{
  $ graph-tool --load example.xml --combined-degree-histogram="deg-dist"
  $ cat deg-dist
  0.0     1.0     2
  1.0     1.0     1
  1.0     2.0     1
  2.0     1.0     3
  }}}

  === Average Distance ===

  The average vertex-vertex distance can be obtained with the "{{{--average-distance}}}" option:

  {{{
  $ graph-tool --load example.xml --average-distance=-
  average distance:       0.714285714286
  }}}

  For directed and/or disconnected graphs, it may be better to use the average harmonic distance defined as:

  [[Equation(\[d_h = \left[\sum_{v,u}\frac{1}{d_{uv}}\right]^{-1}\])]], where [[Equation($d_{uv}$)]] is the regular graph distance between [[Equation($u$)]] and [[Equation($v$)]], which here is taken to be infinity when there's no path between those two vertices.

  Example:

  {{{
  $ graph-tool --load example.xml --average-harmonic-distance=-
  average harmonic distance:      4.1226993865
  }}}

  === Component Size Histogram === 

  Component size statistics can be obtained by the "{{{component-size-histogram}}}" option. Consider the following graph:

  {{{
  #!html
  <div style="text-align: center;">
  }}}
  {{{
  #!graphviz
  digraph G {
  1->2
  2->3
  3->1

  4->5

  6->7
  7->8
  8->9
  9->10
  10->11
  11->6
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  Defined by the following dot file (henceforth referred to as {{{multi-comp.dot}}}):
  {{{
  digraph G {
  1->2
  2->3
  3->1

  4->5

  6->7
  7->8
  8->9
  9->10
  10->11
  11->6
  }
  }}}

  When called with a directed graph, the program returns the '''strong component''' statistics:

  {{{
  $graph-tool --load multi-comp.dot --component-size-histogram="comp-hist"
  $ cat comp-hist
  1.0     2
  3.0     1
  6.0     1
  }}}

  To see the component statistics if the graph were undirected, we just have to treat it as such:

  {{{
  $ graph-tool --load multi-comp.dot --undirected --component-size-histogram="comp-hist"
  $ cat comp-hist
  2.0     1
  3.0     1
  6.0     1
  }}}

  == Filtering ==

  == Graph Modifications ==

  == Correlations ==
  == Clustering ==
  == Layout ==
  == Random Graph Generation ==
  == Graph History ==


name: GraphToolGuide
author: count0
ipnr: 201.52.69.185
text:
  = graph-tool Guide =

  [[PageOutline]]

  == Invoking ==

  graph-tool is invoked by typing {{{graph-tool}}} in the command line. For a quick summary of options type
  {{{
  graph-tool --help
  }}}


  == Loading and saving files ==

  Files can be loaded with the "{{{--load}}}" option. Graph tool supports both [http://graphml.graphdrawing.org/ graphml] and [http://www.graphviz.org/ dot] formats. The formats are identified by the file name extension: files ending in {{{.xml}}} are considered graphml files, and files ending in {{{.dot}}} are considered dot files. Files can also end in {{{.gz}}} or {{{.bz2}}} to indicate compression, such as {{{.xml.gz}}} or {{{.dot.bz2}}}. Files can be saved with the "{{{--save}}}" command, and the file name specifications are the same.

  === File format description ===

  Consider the following directed graph, with one floating point edge property (which will be called "weight"):
  {{{
  #!html
  <div style="text-align: center;">
  }}}
  {{{
  #!graphviz
  digraph G {
  start="12";
  1->2 [label = "  1.2  ", len=0.6];
  2->3 [label = "  0.8  ", len=0.6];
  3->7 [label = "  0.5", len=0.6];
  4->5 [label = "  0.2  ", len=0.6];
  5->6 [label = "  10.1  ", len=0.6];
  5->3 [label = "  5.5", len=0.6];
  6->7 [label = "  2.0", len=0.6];
  7->2 [label = "  0.1", len=0.6];
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  It can be defined in dot format as such:

  {{{
  digraph G {
  1->2 [weight = "1.2"];
  2->3 [weight = "0.8"];
  3->7 [weight = "0.5"];
  4->5 [weight = "0.2"];
  5->6 [weight = "10.1"];
  5->3 [weight = "5.5"];
  6->7 [weight = "2.0"];
  7->2 [weight = "0.1"];
  }
  }}}

  and in graphml format as such:

  {{{
  #!xml
  <?xml version="1.0" encoding="UTF-8"?>
  <graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://graphml.graphdrawing.org/xmlns/1.0/graphml.xsd">
    <key id="d1" for="edge" attr.name="weight" attr.type="double"/>
    <graph id="G" edgedefault="directed">
      <node id="n0"/>
      <node id="n1"/>
      <node id="n2"/>
      <node id="n3"/>
      <node id="n4"/>
      <node id="n5"/>
      <node id="n6"/>
      <edge id="e0" source="n0" target="n1">
        <data key="d1">1.2</data>
      </edge>
      <edge id="e1" source="n1" target="n2">
        <data key="d1">0.8</data>
      </edge>
      <edge id="e2" source="n2" target="n6">
        <data key="d1">0.5</data>
      </edge>
      <edge id="e3" source="n3" target="n4">
        <data key="d1">0.2</data>
      </edge>
      <edge id="e4" source="n4" target="n5">
        <data key="d1">10.1</data>
      </edge>
      <edge id="e5" source="n4" target="n2">
        <data key="d1">5.5</data>
      </edge>
      <edge id="e6" source="n5" target="n6">
        <data key="d1">2.0</data>
      </edge>
      <edge id="e7" source="n6" target="n1">
        <data key="d1">0.1</data>
      </edge>
    </graph>
  </graphml>
  }}}

  Vertex properties are done in an analogous manner. There's no limit on the number of properties the graph can have. 

  Graphs can also be undirected, and are loaded by specifiyng the option "{{{--undirected}}}" before "{{{--load}}}". Here's an example:

  {{{
  #!html
  <div style="text-align: center;">
  }}}
  {{{
  #!graphviz
  graph G {
  start="12";
  1--2 
  2--3 
  3--7 
  4--5 
  5--6 
  5--3 
  6--7 
  7--2 
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  In dot format:

  {{{
  graph G {
  1--2 
  2--3 
  3--7 
  4--5 
  5--6 
  5--3 
  6--7 
  7--2 
  }
  }}}

  and in graphml format:

  {{{
  #!xml
  <?xml version="1.0" encoding="UTF-8"?>
  <graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://graphml.graphdrawing.org/xmlns/1.0/graphml.xsd">
    <graph id="G" edgedefault="undirected">
      <node id="n0"/>
      <node id="n1"/>
      <node id="n2"/>
      <node id="n3"/>
      <node id="n4"/>
      <node id="n5"/>
      <node id="n6"/>
      <edge id="e0" source="n0" target="n1"/>
      <edge id="e1" source="n1" target="n2"/>
      <edge id="e2" source="n2" target="n6"/>
      <edge id="e3" source="n3" target="n4"/>
      <edge id="e4" source="n4" target="n5"/>
      <edge id="e5" source="n4" target="n2"/>
      <edge id="e6" source="n5" target="n6"/>
      <edge id="e7" source="n6" target="n1"/>
    </graph>
  </graphml>
  }}}

  {{{
  #!html
  <div class="note">
  }}}
  ==== Which format to use? ====

  You can of course use either format, but in general graphml is preferred. It provides for a tighter definition of the graph, and since graph-tool understants the parse info attributes of the graph, you can speed up the loading of the file and reduce memory usage by using the following in your graph definition:

  {{{
  #!xml
  ...
   <graph id="G" edgedefault="directed" parse.nodeids="canonical" parse.edgeids="canonical" parse.order="nodesfirst">
  ...
  }}}

  This says that all vertices and edges are named "n0","n1", ..., "nN-1", and  "e0", "e1", ..., "eE-1", respectively. And also it says that the vertex list comes before the edge list. You're not forced to define your graph this way, but it does improve performace for large graphs.

  {{{
  #!html
  </div>
  }}}

  ----

  == Basic Statistics ==

  The two most basic properties of the graph are the number of vertex and edges, which is obtainable through the "{{{--number-of-vertices}}}" and "{{{--number-of-edges}}}" options. Suppose the first graph in [[ref(File Format Description)]] is saved under {{{example.xml}}}. We can then get the number of vertices and edges by typing:

  {{{
  $ graph-tool --load example.xml --number-of-vertices=- --number-of-edges=-
  number of vertices:     7
  number of edges:        8
  }}}

  The "-" parameter to the options is necessary to output the results in the terminal. Otherwise it writes it to the file given in the parameter.

  === Degree Histogram ===

  The degree histogram can be obtained by the "{{{--degree-histogram}}}" option. It requires two parameters, separated by "|": degree type and file name. Degree type can be any of "in-degree", "out-degree", "total-degree" and __any vertex scalar property__. The file name is the file the histogram is written to, or "-" to be written to the terminal. Files may be terminated with {{{.gz}}} or {{{.bz2}}} for compression. Example:

  {{{
  $ graph-tool --load example.xml --degree-histogram="total-degree|deg-dist"
  $ cat deg-dist
  1.0     2
  2.0     1
  3.0     4
  }}}

  For directed graphs, it is also possible to get the combined (in,out)-degree histogram with the "{{{--combined-degree-histogram}}}" option:

  {{{
  $ graph-tool --load example.xml --combined-degree-histogram="deg-dist"
  $ cat deg-dist
  0.0     1.0     2
  1.0     1.0     1
  1.0     2.0     1
  2.0     1.0     3
  }}}

  === Average Distance ===

  The average vertex-vertex distance can be obtained with the "{{{--average-distance}}}" option:

  {{{
  $ graph-tool --load example.xml --average-distance=-
  average distance:       0.714285714286
  }}}

  For directed and/or disconnected graphs, it may be better to use the average harmonic distance defined as:

  [[Equation(\[d_h = \left[\sum_{v,u}\frac{1}{d_{uv}}\right]^{-1}\])]], where [[Equation($d_{uv}$)]] is the regular graph distance between [[Equation($u$)]] and [[Equation($v$)]], which here is taken to be infinity when there's no path between those two vertices.

  Example:

  {{{
  $ graph-tool --load example.xml --average-harmonic-distance=-
  average harmonic distance:      4.1226993865
  }}}

  === Component Size Histogram === 

  Component size statistics can be obtained by the "{{{component-size-histogram}}}" option. Consider the following graph:

  {{{
  #!html
  <div style="text-align: center;">
  }}}
  {{{
  #!graphviz
  digraph G {
  1->2
  2->3
  3->1

  4->5

  6->7
  7->8
  8->9
  9->10
  10->11
  11->6
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  Defined by the following dot file (henceforth referred to as {{{multi-comp.dot}}}):
  {{{
  digraph G {
  1->2
  2->3
  3->1

  4->5

  6->7
  7->8
  8->9
  9->10
  10->11
  11->6
  }
  }}}

  When called with a directed graph, the program returns the '''strong component''' statistics:

  {{{
  $graph-tool --load multi-comp.dot --component-size-histogram="comp-hist"
  $ cat comp-hist
  1.0     2
  3.0     1
  6.0     1
  }}}

  To see the component statistics if the graph were undirected, we just have to treat it as such:

  {{{
  $ graph-tool --load multi-comp.dot --undirected --component-size-histogram="comp-hist"
  $ cat comp-hist
  2.0     1
  3.0     1
  6.0     1
  }}}


  == Filtering ==

      --directed                                                                treat graph as directed (default)
      --undirected                                                              treat graph as undirected
      --reverse                                                                 reverse edges
      --vertex-filter=FILTER RULE                                               set generic vertex filter
      --vertex-range-filter=PROPERTY|RANGE                                      choose vertex property and range to filter
      --reset-vertex-filter                                                     remove edge filter
      --edge-filter=FILTER RULE                                                 set generic edge filter
      --edge-range-filter=PROPERTY|RANGE                                        choose edge property and range to filter
      --reset-edge-filter                                                       remove edge filter


  == Graph Modifications ==

      --remove-vertex-property=PROPERTY                                         remove vertex property from graph
      --remove-edge-property=PROPERTY|RANGE                                     remove edge property from graph
      --insert-vertex-index-property=PROPERTY                                   insert vertex index as property
      --insert-edge-index-property=PROPERTY                                     insert edge index as property
      --remove-parallel-edges                                                   remove parallel edges from graph



  == Correlations ==
      --degree-correlation-histogram=DEGREE1|DEGREE2|FILE                       get the degree correlation histogram. Scalar properties are also accepted in
                                                                                place of DEGREE
      --average-nearest-neighbours-degree=NEIGHBOURS|ORIGIN-DEGREE|DEGREE|FILE  get the average nearest neighbours degree
      --edge-degree-correlation-histogram=DEGREE1|EDGE-PROP|DEGREE2|FILE        get the source degree vs. edge scalar vs. target degree correlation histogram.
                                                                                Scalar properties are also accepted in place of DEGREE-TYPE
      --vertex-scalar-correlation-histogram=DEGREE|VERTEX-PROP|FILE             get the degree vs. vertex scalar correlation histogram. Scalar properties are
                                                                                also accepted in place of DEGREE
      --assortativity-coefficient=NEIGHBOURS|DEGREE|DEGREE|FILE                 get the assortativity coefficient. Scalar properties are also accepted in place                                                                              of DEGREE (not yet)

  == Clustering ==

      --local-clustering-coefficient=FILE                                       get the local clustering coefficient
      --local-clustering-coefficient-histogram=DEGREE_TYPE|FILE                 get the local clustering coefficient histogram
      --set-local-clustering-to-property=PROPERTY                               set the local clustering coefficient to vertex property
      --global-clustering-coefficient=FILE                                      get the global clustering coefficient


  == Layout ==
      --compute-spring-block-layout=ITERATIONS[|SEED]                           compute the spring block layout
      --compute-gursoy-atun-layout=ITERATIONS[|SEED]                            compute the Gursoy-Atun layout


  == Random Graph Generation ==
      --correlated-configurational-model=OPTIONS                                generate graph using the configurational model with arbitrary degree
                                                                                correlations. Options are: N, pjk, pjk_ceil, pjk_m, inv_pjk_ceil, corr,
                                                                                corr_ceil, corr_m, inv_corr_ceil, undirected, directed, progress, seed. See
                                                                                documentation for details.

  == Graph History ==

      --history=INIT|CONDITION|STEP                                             compute graph history
      --history-rate=TIME  


name: GraphToolGuide
author: count0
ipnr: 201.52.69.185
text:
  = graph-tool Guide =

  [[PageOutline]]

  == Invoking ==

  graph-tool is invoked by typing {{{graph-tool}}} in the command line. For a quick summary of options type
  {{{
  graph-tool --help
  }}}


  == Loading and saving files ==

  Files can be loaded with the "{{{--load}}}" option. Graph tool supports both [http://graphml.graphdrawing.org/ graphml] and [http://www.graphviz.org/ dot] formats. The formats are identified by the file name extension: files ending in {{{.xml}}} are considered graphml files, and files ending in {{{.dot}}} are considered dot files. Files can also end in {{{.gz}}} or {{{.bz2}}} to indicate compression, such as {{{.xml.gz}}} or {{{.dot.bz2}}}. Files can be saved with the "{{{--save}}}" command, and the file name specifications are the same.

  === File format description ===

  Consider the following directed graph, with one floating point edge property (which will be called "weight"):
  {{{
  #!html
  <div style="text-align: center;">
  }}}
  {{{
  #!graphviz
  digraph G {
  start="12";
  1->2 [label = "  1.2  ", len=0.6];
  2->3 [label = "  0.8  ", len=0.6];
  3->7 [label = "  0.5", len=0.6];
  4->5 [label = "  0.2  ", len=0.6];
  5->6 [label = "  10.1  ", len=0.6];
  5->3 [label = "  5.5", len=0.6];
  6->7 [label = "  2.0", len=0.6];
  7->2 [label = "  0.1", len=0.6];
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  It can be defined in dot format as such:

  {{{
  digraph G {
  1->2 [weight = "1.2"];
  2->3 [weight = "0.8"];
  3->7 [weight = "0.5"];
  4->5 [weight = "0.2"];
  5->6 [weight = "10.1"];
  5->3 [weight = "5.5"];
  6->7 [weight = "2.0"];
  7->2 [weight = "0.1"];
  }
  }}}

  and in graphml format as such:

  {{{
  #!xml
  <?xml version="1.0" encoding="UTF-8"?>
  <graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://graphml.graphdrawing.org/xmlns/1.0/graphml.xsd">
    <key id="d1" for="edge" attr.name="weight" attr.type="double"/>
    <graph id="G" edgedefault="directed">
      <node id="n0"/>
      <node id="n1"/>
      <node id="n2"/>
      <node id="n3"/>
      <node id="n4"/>
      <node id="n5"/>
      <node id="n6"/>
      <edge id="e0" source="n0" target="n1">
        <data key="d1">1.2</data>
      </edge>
      <edge id="e1" source="n1" target="n2">
        <data key="d1">0.8</data>
      </edge>
      <edge id="e2" source="n2" target="n6">
        <data key="d1">0.5</data>
      </edge>
      <edge id="e3" source="n3" target="n4">
        <data key="d1">0.2</data>
      </edge>
      <edge id="e4" source="n4" target="n5">
        <data key="d1">10.1</data>
      </edge>
      <edge id="e5" source="n4" target="n2">
        <data key="d1">5.5</data>
      </edge>
      <edge id="e6" source="n5" target="n6">
        <data key="d1">2.0</data>
      </edge>
      <edge id="e7" source="n6" target="n1">
        <data key="d1">0.1</data>
      </edge>
    </graph>
  </graphml>
  }}}

  Vertex properties are done in an analogous manner. There's no limit on the number of properties the graph can have. 

  Graphs can also be undirected, and are loaded by specifiyng the option "{{{--undirected}}}" before "{{{--load}}}". Here's an example:

  {{{
  #!html
  <div style="text-align: center;">
  }}}
  {{{
  #!graphviz
  graph G {
  start="12";
  1--2 
  2--3 
  3--7 
  4--5 
  5--6 
  5--3 
  6--7 
  7--2 
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  In dot format:

  {{{
  graph G {
  1--2 
  2--3 
  3--7 
  4--5 
  5--6 
  5--3 
  6--7 
  7--2 
  }
  }}}

  and in graphml format:

  {{{
  #!xml
  <?xml version="1.0" encoding="UTF-8"?>
  <graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://graphml.graphdrawing.org/xmlns/1.0/graphml.xsd">
    <graph id="G" edgedefault="undirected">
      <node id="n0"/>
      <node id="n1"/>
      <node id="n2"/>
      <node id="n3"/>
      <node id="n4"/>
      <node id="n5"/>
      <node id="n6"/>
      <edge id="e0" source="n0" target="n1"/>
      <edge id="e1" source="n1" target="n2"/>
      <edge id="e2" source="n2" target="n6"/>
      <edge id="e3" source="n3" target="n4"/>
      <edge id="e4" source="n4" target="n5"/>
      <edge id="e5" source="n4" target="n2"/>
      <edge id="e6" source="n5" target="n6"/>
      <edge id="e7" source="n6" target="n1"/>
    </graph>
  </graphml>
  }}}

  {{{
  #!html
  <div class="note">
  }}}
  ==== Which format to use? ====

  You can of course use either format, but in general graphml is preferred. It provides for a tighter definition of the graph, and since graph-tool understants the parse info attributes of the graph, you can speed up the loading of the file and reduce memory usage by using the following in your graph definition:

  {{{
  #!xml
  ...
   <graph id="G" edgedefault="directed" parse.nodeids="canonical" parse.edgeids="canonical" parse.order="nodesfirst">
  ...
  }}}

  This says that all vertices and edges are named "n0","n1", ..., "nN-1", and  "e0", "e1", ..., "eE-1", respectively. And also it says that the vertex list comes before the edge list. You're not forced to define your graph this way, but it does improve performace for large graphs.

  {{{
  #!html
  </div>
  }}}

  ----

  == Basic Statistics ==

  The two most basic properties of the graph are the number of vertex and edges, which is obtainable through the "{{{--number-of-vertices}}}" and "{{{--number-of-edges}}}" options. Suppose the first graph in [[ref(File Format Description)]] is saved under {{{example.xml}}}. We can then get the number of vertices and edges by typing:

  {{{
  $ graph-tool --load example.xml --number-of-vertices=- --number-of-edges=-
  number of vertices:     7
  number of edges:        8
  }}}

  The "-" parameter to the options is necessary to output the results in the terminal. Otherwise it writes it to the file given in the parameter.

  === Degree Histogram ===

  The degree histogram can be obtained by the "{{{--degree-histogram}}}" option. It requires two parameters, separated by "|": degree type and file name. Degree type can be any of "in-degree", "out-degree", "total-degree" and __any vertex scalar property__. The file name is the file the histogram is written to, or "-" to be written to the terminal. Files may be terminated with {{{.gz}}} or {{{.bz2}}} for compression. Example:

  {{{
  $ graph-tool --load example.xml --degree-histogram="total-degree|deg-dist"
  $ cat deg-dist
  1.0     2
  2.0     1
  3.0     4
  }}}

  For directed graphs, it is also possible to get the combined (in,out)-degree histogram with the "{{{--combined-degree-histogram}}}" option:

  {{{
  $ graph-tool --load example.xml --combined-degree-histogram="deg-dist"
  $ cat deg-dist
  0.0     1.0     2
  1.0     1.0     1
  1.0     2.0     1
  2.0     1.0     3
  }}}

  === Average Distance ===

  The average vertex-vertex distance can be obtained with the "{{{--average-distance}}}" option:

  {{{
  $ graph-tool --load example.xml --average-distance=-
  average distance:       0.714285714286
  }}}

  For directed and/or disconnected graphs, it may be better to use the average harmonic distance defined as:

  [[Equation(\[d_h = \left[\sum_{v,u}\frac{1}{d_{uv}}\right]^{-1}\])]], where [[Equation($d_{uv}$)]] is the regular graph distance between [[Equation($u$)]] and [[Equation($v$)]], which here is taken to be infinity when there's no path between those two vertices.

  Example:

  {{{
  $ graph-tool --load example.xml --average-harmonic-distance=-
  average harmonic distance:      4.1226993865
  }}}

  === Component Size Histogram === 

  Component size statistics can be obtained by the "{{{component-size-histogram}}}" option. Consider the following graph:

  {{{
  #!html
  <div style="text-align: center;">
  }}}
  {{{
  #!graphviz
  digraph G {
  1->2
  2->3
  3->1

  4->5

  6->7
  7->8
  8->9
  9->10
  10->11
  11->6
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  Defined by the following dot file (henceforth referred to as {{{multi-comp.dot}}}):
  {{{
  digraph G {
  1->2
  2->3
  3->1

  4->5

  6->7
  7->8
  8->9
  9->10
  10->11
  11->6
  }
  }}}

  When called with a directed graph, the program returns the '''strong component''' statistics:

  {{{
  $graph-tool --load multi-comp.dot --component-size-histogram="comp-hist"
  $ cat comp-hist
  1.0     2
  3.0     1
  6.0     1
  }}}

  To see the component statistics if the graph were undirected, we just have to treat it as such:

  {{{
  $ graph-tool --load multi-comp.dot --undirected --component-size-histogram="comp-hist"
  $ cat comp-hist
  2.0     1
  3.0     1
  6.0     1
  }}}


  == Filtering ==

  Graphs can be filtered in several ways. None of them actually modify the internally kept graph, and are therefore of complexity O(1).

  === Directedness ===

  Internally, all graphs in graph-tool are directed graphs. But it is possible to treat them easily as directed with the "{{{--undirected}}}" option. All options after that will operate on a undirected filter of the internal directed graph. The "{{{--directed}}}" option reverts back to the default mode.

  === Edge direction ===

  Directed graphs can have the the edge direction reversed with the "{{{--reverse}}}" option. A second "{{{--reverse}}}" reverts back to the original state.

  === Filtering of vertices or edges ===

  ==== Range filtering ===
  Edges and vertices can be filtered out of the graph based on their properties. The most basic and fastest way of filtering is called "range filtering" and filters out vertices with a scalar property which lays outside a given range. The filtering is controlled with the "{{{--vertex-range-filter}}}" and "{{{--edge-range-filter}}}" options, which takes two parameters separated by "|": the property to be used as filter and the range (two values separated by space. Here's an example using the graph defined in [[ref(File Format Description)]]:

  {{{
  $ graph-tool --load test1.dot --number-of-edges=-
  number of edges:        8
  $ graph-tool --load test1.dot --edge-range-filter="weight|0.6 6.0" --number-of-edges=- --save filtered.dot
  number of edges:        4
  }}}

  The file {{{filtered.dot}}} contains (representation on the side):

  {{{
  #!html
  <div style="float: right;">
  }}}
  {{{
  #!graphviz
  digraph G {
  1;
  2;
  3;
  7;
  4;
  5;
  6;
  1->2  [label="1.2"];
  2->3  [label="0.8"];
  5->3  [label="5.5"];
  6->7  [label="2.0"];
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  {{{
  digraph G {
  1;
  2;
  3;
  7;
  4;
  5;
  6;
  1->2  [weight="1.2"];
  2->3  [weight="0.8"];
  5->3  [weight="5.5"];
  6->7  [weight="2"];
  }
  }}}

  === Generic Filtering ===


      --vertex-filter=FILTER RULE                                               set generic vertex filter
      --vertex-range-filter=PROPERTY|RANGE                                      choose vertex property and range to filter
      --reset-vertex-filter                                                     remove edge filter
      --edge-filter=FILTER RULE                                                 set generic edge filter
      --edge-range-filter=PROPERTY|RANGE                                        choose edge property and range to filter
      --reset-edge-filter                                                       remove edge filter


  == Graph Modifications ==

      --remove-vertex-property=PROPERTY                                         remove vertex property from graph
      --remove-edge-property=PROPERTY|RANGE                                     remove edge property from graph
      --insert-vertex-index-property=PROPERTY                                   insert vertex index as property
      --insert-edge-index-property=PROPERTY                                     insert edge index as property
      --remove-parallel-edges                                                   remove parallel edges from graph



  == Correlations ==
      --degree-correlation-histogram=DEGREE1|DEGREE2|FILE                       get the degree correlation histogram. Scalar properties are also accepted in
                                                                                place of DEGREE
      --average-nearest-neighbours-degree=NEIGHBOURS|ORIGIN-DEGREE|DEGREE|FILE  get the average nearest neighbours degree
      --edge-degree-correlation-histogram=DEGREE1|EDGE-PROP|DEGREE2|FILE        get the source degree vs. edge scalar vs. target degree correlation histogram.
                                                                                Scalar properties are also accepted in place of DEGREE-TYPE
      --vertex-scalar-correlation-histogram=DEGREE|VERTEX-PROP|FILE             get the degree vs. vertex scalar correlation histogram. Scalar properties are
                                                                                also accepted in place of DEGREE
      --assortativity-coefficient=NEIGHBOURS|DEGREE|DEGREE|FILE                 get the assortativity coefficient. Scalar properties are also accepted in place                                                                              of DEGREE (not yet)

  == Clustering ==

      --local-clustering-coefficient=FILE                                       get the local clustering coefficient
      --local-clustering-coefficient-histogram=DEGREE_TYPE|FILE                 get the local clustering coefficient histogram
      --set-local-clustering-to-property=PROPERTY                               set the local clustering coefficient to vertex property
      --global-clustering-coefficient=FILE                                      get the global clustering coefficient


  == Layout ==
      --compute-spring-block-layout=ITERATIONS[|SEED]                           compute the spring block layout
      --compute-gursoy-atun-layout=ITERATIONS[|SEED]                            compute the Gursoy-Atun layout


  == Random Graph Generation ==
      --correlated-configurational-model=OPTIONS                                generate graph using the configurational model with arbitrary degree
                                                                                correlations. Options are: N, pjk, pjk_ceil, pjk_m, inv_pjk_ceil, corr,
                                                                                corr_ceil, corr_m, inv_corr_ceil, undirected, directed, progress, seed. See
                                                                                documentation for details.

  == Graph History ==

      --history=INIT|CONDITION|STEP                                             compute graph history
      --history-rate=TIME  


name: GraphToolGuide
author: count0
ipnr: 201.52.69.185
text:
  = graph-tool Guide =

  [[PageOutline]]

  == Invoking ==

  graph-tool is invoked by typing {{{graph-tool}}} in the command line. For a quick summary of options type
  {{{
  graph-tool --help
  }}}


  == Loading and saving files ==

  Files can be loaded with the "{{{--load}}}" option. Graph tool supports both [http://graphml.graphdrawing.org/ graphml] and [http://www.graphviz.org/ dot] formats. The formats are identified by the file name extension: files ending in {{{.xml}}} are considered graphml files, and files ending in {{{.dot}}} are considered dot files. Files can also end in {{{.gz}}} or {{{.bz2}}} to indicate compression, such as {{{.xml.gz}}} or {{{.dot.bz2}}}. Files can be saved with the "{{{--save}}}" command, and the file name specifications are the same.

  === File format description ===

  Consider the following directed graph, with one floating point edge property (which will be called "weight"):
  {{{
  #!html
  <div style="text-align: center;">
  }}}
  {{{
  #!graphviz
  digraph G {
  start="12";
  1->2 [label = "  1.2  ", len=0.6];
  2->3 [label = "  0.8  ", len=0.6];
  3->7 [label = "  0.5", len=0.6];
  4->5 [label = "  0.2  ", len=0.6];
  5->6 [label = "  10.1  ", len=0.6];
  5->3 [label = "  5.5", len=0.6];
  6->7 [label = "  2.0", len=0.6];
  7->2 [label = "  0.1", len=0.6];
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  It can be defined in dot format as such:

  {{{
  digraph G {
  1->2 [weight = "1.2"];
  2->3 [weight = "0.8"];
  3->7 [weight = "0.5"];
  4->5 [weight = "0.2"];
  5->6 [weight = "10.1"];
  5->3 [weight = "5.5"];
  6->7 [weight = "2.0"];
  7->2 [weight = "0.1"];
  }
  }}}

  and in graphml format as such:

  {{{
  #!xml
  <?xml version="1.0" encoding="UTF-8"?>
  <graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://graphml.graphdrawing.org/xmlns/1.0/graphml.xsd">
    <key id="d1" for="edge" attr.name="weight" attr.type="double"/>
    <graph id="G" edgedefault="directed">
      <node id="n0"/>
      <node id="n1"/>
      <node id="n2"/>
      <node id="n3"/>
      <node id="n4"/>
      <node id="n5"/>
      <node id="n6"/>
      <edge id="e0" source="n0" target="n1">
        <data key="d1">1.2</data>
      </edge>
      <edge id="e1" source="n1" target="n2">
        <data key="d1">0.8</data>
      </edge>
      <edge id="e2" source="n2" target="n6">
        <data key="d1">0.5</data>
      </edge>
      <edge id="e3" source="n3" target="n4">
        <data key="d1">0.2</data>
      </edge>
      <edge id="e4" source="n4" target="n5">
        <data key="d1">10.1</data>
      </edge>
      <edge id="e5" source="n4" target="n2">
        <data key="d1">5.5</data>
      </edge>
      <edge id="e6" source="n5" target="n6">
        <data key="d1">2.0</data>
      </edge>
      <edge id="e7" source="n6" target="n1">
        <data key="d1">0.1</data>
      </edge>
    </graph>
  </graphml>
  }}}

  Vertex properties are done in an analogous manner. There's no limit on the number of properties the graph can have. 

  Graphs can also be undirected, and are loaded by specifiyng the option "{{{--undirected}}}" before "{{{--load}}}". Here's an example:

  {{{
  #!html
  <div style="text-align: center;">
  }}}
  {{{
  #!graphviz
  graph G {
  start="12";
  1--2 
  2--3 
  3--7 
  4--5 
  5--6 
  5--3 
  6--7 
  7--2 
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  In dot format:

  {{{
  graph G {
  1--2 
  2--3 
  3--7 
  4--5 
  5--6 
  5--3 
  6--7 
  7--2 
  }
  }}}

  and in graphml format:

  {{{
  #!xml
  <?xml version="1.0" encoding="UTF-8"?>
  <graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://graphml.graphdrawing.org/xmlns/1.0/graphml.xsd">
    <graph id="G" edgedefault="undirected">
      <node id="n0"/>
      <node id="n1"/>
      <node id="n2"/>
      <node id="n3"/>
      <node id="n4"/>
      <node id="n5"/>
      <node id="n6"/>
      <edge id="e0" source="n0" target="n1"/>
      <edge id="e1" source="n1" target="n2"/>
      <edge id="e2" source="n2" target="n6"/>
      <edge id="e3" source="n3" target="n4"/>
      <edge id="e4" source="n4" target="n5"/>
      <edge id="e5" source="n4" target="n2"/>
      <edge id="e6" source="n5" target="n6"/>
      <edge id="e7" source="n6" target="n1"/>
    </graph>
  </graphml>
  }}}

  {{{
  #!html
  <div class="note">
  }}}
  ==== Which format to use? ====

  You can of course use either format, but in general graphml is preferred. It provides for a tighter definition of the graph, and since graph-tool understants the parse info attributes of the graph, you can speed up the loading of the file and reduce memory usage by using the following in your graph definition:

  {{{
  #!xml
  ...
   <graph id="G" edgedefault="directed" parse.nodeids="canonical" parse.edgeids="canonical" parse.order="nodesfirst">
  ...
  }}}

  This says that all vertices and edges are named "n0","n1", ..., "nN-1", and  "e0", "e1", ..., "eE-1", respectively. And also it says that the vertex list comes before the edge list. You're not forced to define your graph this way, but it does improve performace for large graphs.

  {{{
  #!html
  </div>
  }}}

  ----

  == Basic Statistics ==

  The two most basic properties of the graph are the number of vertex and edges, which is obtainable through the "{{{--number-of-vertices}}}" and "{{{--number-of-edges}}}" options. Suppose the first graph in [[ref(File Format Description)]] is saved under {{{example.xml}}}. We can then get the number of vertices and edges by typing:

  {{{
  $ graph-tool --load example.xml --number-of-vertices=- --number-of-edges=-
  number of vertices:     7
  number of edges:        8
  }}}

  The "-" parameter to the options is necessary to output the results in the terminal. Otherwise it writes it to the file given in the parameter.

  === Degree Histogram ===

  The degree histogram can be obtained by the "{{{--degree-histogram}}}" option. It requires two parameters, separated by "|": degree type and file name. Degree type can be any of "in-degree", "out-degree", "total-degree" and __any vertex scalar property__. The file name is the file the histogram is written to, or "-" to be written to the terminal. Files may be terminated with {{{.gz}}} or {{{.bz2}}} for compression. Example:

  {{{
  $ graph-tool --load example.xml --degree-histogram="total-degree|deg-dist"
  $ cat deg-dist
  1.0     2
  2.0     1
  3.0     4
  }}}

  For directed graphs, it is also possible to get the combined (in,out)-degree histogram with the "{{{--combined-degree-histogram}}}" option:

  {{{
  $ graph-tool --load example.xml --combined-degree-histogram="deg-dist"
  $ cat deg-dist
  0.0     1.0     2
  1.0     1.0     1
  1.0     2.0     1
  2.0     1.0     3
  }}}

  === Average Distance ===

  The average vertex-vertex distance can be obtained with the "{{{--average-distance}}}" option:

  {{{
  $ graph-tool --load example.xml --average-distance=-
  average distance:       0.714285714286
  }}}

  For directed and/or disconnected graphs, it may be better to use the average harmonic distance defined as:

  [[Equation(\[d_h = \left[\sum_{v,u}\frac{1}{d_{uv}}\right]^{-1}\])]], where [[Equation($d_{uv}$)]] is the regular graph distance between [[Equation($u$)]] and [[Equation($v$)]], which here is taken to be infinity when there's no path between those two vertices.

  Example:

  {{{
  $ graph-tool --load example.xml --average-harmonic-distance=-
  average harmonic distance:      4.1226993865
  }}}

  === Component Size Histogram === 

  Component size statistics can be obtained by the "{{{component-size-histogram}}}" option. Consider the following graph:

  {{{
  #!html
  <div style="text-align: center;">
  }}}
  {{{
  #!graphviz
  digraph G {
  1->2
  2->3
  3->1

  4->5

  6->7
  7->8
  8->9
  9->10
  10->11
  11->6
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  Defined by the following dot file (henceforth referred to as {{{multi-comp.dot}}}):
  {{{
  digraph G {
  1->2
  2->3
  3->1

  4->5

  6->7
  7->8
  8->9
  9->10
  10->11
  11->6
  }
  }}}

  When called with a directed graph, the program returns the '''strong component''' statistics:

  {{{
  $graph-tool --load multi-comp.dot --component-size-histogram="comp-hist"
  $ cat comp-hist
  1.0     2
  3.0     1
  6.0     1
  }}}

  To see the component statistics if the graph were undirected, we just have to treat it as such:

  {{{
  $ graph-tool --load multi-comp.dot --undirected --component-size-histogram="comp-hist"
  $ cat comp-hist
  2.0     1
  3.0     1
  6.0     1
  }}}


  == Filtering ==

  Graphs can be filtered in several ways. None of them actually modify the internally kept graph, and are therefore of complexity O(1).

  === Directedness ===

  Internally, all graphs in graph-tool are directed graphs. But it is possible to treat them easily as directed with the "{{{--undirected}}}" option. All options after that will operate on a undirected filter of the internal directed graph. The "{{{--directed}}}" option reverts back to the default mode.

  === Edge direction ===

  Directed graphs can have the the edge direction reversed with the "{{{--reverse}}}" option. A second "{{{--reverse}}}" reverts back to the original state.

  === Filtering of vertices or edges ===

  ==== Range filtering ====

  Edges and vertices can be filtered out of the graph based on their properties. The most basic and fastest way of filtering is called "range filtering" and filters out vertices with a scalar property which lays outside a given range. The filtering is controlled with the "{{{--vertex-range-filter}}}" and "{{{--edge-range-filter}}}" options, which takes two parameters separated by "|": the property to be used as filter and the range (two values separated by space. Here's an example using the graph defined in [[ref(File Format Description)]]:

  {{{
  $ graph-tool --load example.xml --number-of-edges=-
  number of edges:        8
  $ graph-tool --load example.xml --edge-range-filter="weight|0.6 6.0" --number-of-edges=- --save filtered.dot
  number of edges:        4
  }}}

  The file {{{filtered.dot}}} contains (representation on the side):

  {{{
  #!html
  <div style="float: right;">
  }}}
  {{{
  #!graphviz
  digraph G {
  1;
  2;
  3;
  7;
  4;
  5;
  6;
  1->2  [label="1.2"];
  2->3  [label="0.8"];
  5->3  [label="5.5"];
  6->7  [label="2.0"];
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  {{{
  digraph G {
  1;
  2;
  3;
  7;
  4;
  5;
  6;
  1->2  [weight="1.2"];
  2->3  [weight="0.8"];
  5->3  [weight="5.5"];
  6->7  [weight="2"];
  }
  }}}

  ==== Generic Filtering ====

  Graphs can be filtered in a more versatile way than above (at a performance cost). This is done through the "{{{--vertex-filter}}}" and "{{{--edge-filter}}}" options, which take a generic [[http://www.python.org python]] expression as a parameter, and if it evaluates to {{{True}}} the vertex or edge is removed.

  Example:

  {{{
  #!html
  <div style="float: right;">
  }}}
  {{{
  #!graphviz
  digraph G {
  0;
  1;
  2;
  3;
  4;
  1->4  [label="0.5"];
  2->3  [label="10.1"];
  2->1  [label="5.5"];
  3->4  [label="2"];
  4->0  [label="0.1"];
  }
  }}}
  {{{
  #!html
  </div>
  }}}
  {{{
  $ graph-tool --load example.xml --edge-filter="weight==0.8" --vertex-filter="in_degree==0" --save filtered.dot
  $ cat filtered.dot
  digraph G {
  0;
  1;
  2;
  3;
  4;
  1->4  [weight="0.5"];
  2->3  [weight="10.1"];
  2->1  [weight="5.5"];
  3->4  [weight="2"];
  4->0  [weight="0.1"];
  }
  }}}

  {{{
  #!html
  <div class="note">
  }}}
  ===== Performace note =====
  When generic filtering is turned on, algorithms in general will run much slower, since the python interpreter will be involved in the computations. Therefore, if some expensive computation is being considered, it is in general better to save the graph to a file after the filtering, and load it as unfiltered to perform the computation.
  {{{
  #!html
  </div>
  }}}

  ==== Removing filtering ====

  The graph can be returned to its unfiltered state by calling "{{{--reset-vertex-filter}}}" and "{{{--reset-edge-filter}}}".

  == Graph Modifications ==

  There's a couple of options which change the internally kept graph.

  === Removing Properties ===

  Vertex and edge properties can be removed from the graph with the options "{{{--remove-vertex-property}}}" and "{{{--remove-edge-property}}}", which take the name of the property to be removed as parameter.

  === Vertex and Edge Indices ====

  Vertices and Edges are identified internally by indices. Those can be inserted as properties with the options "{{{--insert-vertex-index-property}}}" and "{{{--insert-edge-index-property}}}", which take as argument the name by which the property will be called.

  === Removal of Parallel Edges ===

  Parallel edges (i.e. edges that share the same source and target) can be removed from the graph with the option "{{{--remove-parallel-edges}}}", so that only one of the parallel edges ramain (it is undefined which one).


  == Correlations ==
      --degree-correlation-histogram=DEGREE1|DEGREE2|FILE                       get the degree correlation histogram. Scalar properties are also accepted in
                                                                                place of DEGREE
      --average-nearest-neighbours-degree=NEIGHBOURS|ORIGIN-DEGREE|DEGREE|FILE  get the average nearest neighbours degree
      --edge-degree-correlation-histogram=DEGREE1|EDGE-PROP|DEGREE2|FILE        get the source degree vs. edge scalar vs. target degree correlation histogram.
                                                                                Scalar properties are also accepted in place of DEGREE-TYPE
      --vertex-scalar-correlation-histogram=DEGREE|VERTEX-PROP|FILE             get the degree vs. vertex scalar correlation histogram. Scalar properties are
                                                                                also accepted in place of DEGREE
      --assortativity-coefficient=NEIGHBOURS|DEGREE|DEGREE|FILE                 get the assortativity coefficient. Scalar properties are also accepted in place                                                                              of DEGREE (not yet)

  == Clustering ==

      --local-clustering-coefficient=FILE                                       get the local clustering coefficient
      --local-clustering-coefficient-histogram=DEGREE_TYPE|FILE                 get the local clustering coefficient histogram
      --set-local-clustering-to-property=PROPERTY                               set the local clustering coefficient to vertex property
      --global-clustering-coefficient=FILE                                      get the global clustering coefficient


  == Layout ==
      --compute-spring-block-layout=ITERATIONS[|SEED]                           compute the spring block layout
      --compute-gursoy-atun-layout=ITERATIONS[|SEED]                            compute the Gursoy-Atun layout


  == Random Graph Generation ==
      --correlated-configurational-model=OPTIONS                                generate graph using the configurational model with arbitrary degree
                                                                                correlations. Options are: N, pjk, pjk_ceil, pjk_m, inv_pjk_ceil, corr,
                                                                                corr_ceil, corr_m, inv_corr_ceil, undirected, directed, progress, seed. See
                                                                                documentation for details.

  == Graph History ==

      --history=INIT|CONDITION|STEP                                             compute graph history
      --history-rate=TIME  


name: GraphToolGuide
author: count0
ipnr: 201.52.69.185
text:
  = graph-tool Guide =

  [[PageOutline]]

  == Invoking ==

  graph-tool is invoked by typing {{{graph-tool}}} in the command line. For a quick summary of options type
  {{{
  graph-tool --help
  }}}


  == Loading and saving files ==

  Files can be loaded with the "{{{--load}}}" option. Graph tool supports both [http://graphml.graphdrawing.org/ graphml] and [http://www.graphviz.org/ dot] formats. The formats are identified by the file name extension: files ending in {{{.xml}}} are considered graphml files, and files ending in {{{.dot}}} are considered dot files. Files can also end in {{{.gz}}} or {{{.bz2}}} to indicate compression, such as {{{.xml.gz}}} or {{{.dot.bz2}}}. Files can be saved with the "{{{--save}}}" command, and the file name specifications are the same.

  === File format description ===

  Consider the following directed graph, with one floating point edge property (which will be called "weight"):
  {{{
  #!html
  <div style="text-align: center;">
  }}}
  {{{
  #!graphviz
  digraph G {
  start="12";
  1->2 [label = "  1.2  ", len=0.6];
  2->3 [label = "  0.8  ", len=0.6];
  3->7 [label = "  0.5", len=0.6];
  4->5 [label = "  0.2  ", len=0.6];
  5->6 [label = "  10.1  ", len=0.6];
  5->3 [label = "  5.5", len=0.6];
  6->7 [label = "  2.0", len=0.6];
  7->2 [label = "  0.1", len=0.6];
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  It can be defined in dot format as such:

  {{{
  digraph G {
  1->2 [weight = "1.2"];
  2->3 [weight = "0.8"];
  3->7 [weight = "0.5"];
  4->5 [weight = "0.2"];
  5->6 [weight = "10.1"];
  5->3 [weight = "5.5"];
  6->7 [weight = "2.0"];
  7->2 [weight = "0.1"];
  }
  }}}

  and in graphml format as such:

  {{{
  #!xml
  <?xml version="1.0" encoding="UTF-8"?>
  <graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://graphml.graphdrawing.org/xmlns/1.0/graphml.xsd">
    <key id="d1" for="edge" attr.name="weight" attr.type="double"/>
    <graph id="G" edgedefault="directed">
      <node id="n0"/>
      <node id="n1"/>
      <node id="n2"/>
      <node id="n3"/>
      <node id="n4"/>
      <node id="n5"/>
      <node id="n6"/>
      <edge id="e0" source="n0" target="n1">
        <data key="d1">1.2</data>
      </edge>
      <edge id="e1" source="n1" target="n2">
        <data key="d1">0.8</data>
      </edge>
      <edge id="e2" source="n2" target="n6">
        <data key="d1">0.5</data>
      </edge>
      <edge id="e3" source="n3" target="n4">
        <data key="d1">0.2</data>
      </edge>
      <edge id="e4" source="n4" target="n5">
        <data key="d1">10.1</data>
      </edge>
      <edge id="e5" source="n4" target="n2">
        <data key="d1">5.5</data>
      </edge>
      <edge id="e6" source="n5" target="n6">
        <data key="d1">2.0</data>
      </edge>
      <edge id="e7" source="n6" target="n1">
        <data key="d1">0.1</data>
      </edge>
    </graph>
  </graphml>
  }}}

  Vertex properties are done in an analogous manner. There's no limit on the number of properties the graph can have. 

  Graphs can also be undirected, and are loaded by specifiyng the option "{{{--undirected}}}" before "{{{--load}}}". Here's an example:

  {{{
  #!html
  <div style="text-align: center;">
  }}}
  {{{
  #!graphviz
  graph G {
  start="12";
  1--2 
  2--3 
  3--7 
  4--5 
  5--6 
  5--3 
  6--7 
  7--2 
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  In dot format:

  {{{
  graph G {
  1--2 
  2--3 
  3--7 
  4--5 
  5--6 
  5--3 
  6--7 
  7--2 
  }
  }}}

  and in graphml format:

  {{{
  #!xml
  <?xml version="1.0" encoding="UTF-8"?>
  <graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://graphml.graphdrawing.org/xmlns/1.0/graphml.xsd">
    <graph id="G" edgedefault="undirected">
      <node id="n0"/>
      <node id="n1"/>
      <node id="n2"/>
      <node id="n3"/>
      <node id="n4"/>
      <node id="n5"/>
      <node id="n6"/>
      <edge id="e0" source="n0" target="n1"/>
      <edge id="e1" source="n1" target="n2"/>
      <edge id="e2" source="n2" target="n6"/>
      <edge id="e3" source="n3" target="n4"/>
      <edge id="e4" source="n4" target="n5"/>
      <edge id="e5" source="n4" target="n2"/>
      <edge id="e6" source="n5" target="n6"/>
      <edge id="e7" source="n6" target="n1"/>
    </graph>
  </graphml>
  }}}

  {{{
  #!html
  <div class="note">
  }}}
  ==== Which format to use? ====

  You can of course use either format, but in general graphml is preferred. It provides for a tighter definition of the graph, and since graph-tool understants the parse info attributes of the graph, you can speed up the loading of the file and reduce memory usage by using the following in your graph definition:

  {{{
  #!xml
  ...
   <graph id="G" edgedefault="directed" parse.nodeids="canonical" parse.edgeids="canonical" parse.order="nodesfirst">
  ...
  }}}

  This says that all vertices and edges are named "n0","n1", ..., "nN-1", and  "e0", "e1", ..., "eE-1", respectively. And also it says that the vertex list comes before the edge list. You're not forced to define your graph this way, but it does improve performace for large graphs.

  {{{
  #!html
  </div>
  }}}

  ----

  == Basic Statistics ==

  The two most basic properties of the graph are the number of vertex and edges, which is obtainable through the "{{{--number-of-vertices}}}" and "{{{--number-of-edges}}}" options. Suppose the first graph in [[ref(File Format Description)]] is saved under {{{example.xml}}}. We can then get the number of vertices and edges by typing:

  {{{
  $ graph-tool --load example.xml --number-of-vertices=- --number-of-edges=-
  number of vertices:     7
  number of edges:        8
  }}}

  The "-" parameter to the options is necessary to output the results in the terminal. Otherwise it writes it to the file given in the parameter.

  === Degree Histogram ===

  The degree histogram can be obtained by the "{{{--degree-histogram}}}" option. It requires two parameters, separated by "|": degree type and file name. Degree type can be any of "in-degree", "out-degree", "total-degree" and __any vertex scalar property__. The file name is the file the histogram is written to, or "-" to be written to the terminal. Files may be terminated with {{{.gz}}} or {{{.bz2}}} for compression. Example:

  {{{
  $ graph-tool --load example.xml --degree-histogram="total-degree|deg-dist"
  $ cat deg-dist
  1.0     2
  2.0     1
  3.0     4
  }}}

  For directed graphs, it is also possible to get the combined (in,out)-degree histogram with the "{{{--combined-degree-histogram}}}" option:

  {{{
  $ graph-tool --load example.xml --combined-degree-histogram="deg-dist"
  $ cat deg-dist
  0.0     1.0     2
  1.0     1.0     1
  1.0     2.0     1
  2.0     1.0     3
  }}}

  === Average Distance ===

  The average vertex-vertex distance can be obtained with the "{{{--average-distance}}}" option:

  {{{
  $ graph-tool --load example.xml --average-distance=-
  average distance:       0.714285714286
  }}}

  For directed and/or disconnected graphs, it may be better to use the average harmonic distance defined as:

  [[Equation(\[d_h = \left[\sum_{v,u}\frac{1}{d_{uv}}\right]^{-1}\])]], where [[Equation($d_{uv}$)]] is the regular graph distance between [[Equation($u$)]] and [[Equation($v$)]], which here is taken to be infinity when there's no path between those two vertices.

  Example:

  {{{
  $ graph-tool --load example.xml --average-harmonic-distance=-
  average harmonic distance:      4.1226993865
  }}}

  === Component Size Histogram === 

  Component size statistics can be obtained by the "{{{component-size-histogram}}}" option. Consider the following graph:

  {{{
  #!html
  <div style="text-align: center;">
  }}}
  {{{
  #!graphviz
  digraph G {
  1->2
  2->3
  3->1

  4->5

  6->7
  7->8
  8->9
  9->10
  10->11
  11->6
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  Defined by the following dot file (henceforth referred to as {{{multi-comp.dot}}}):
  {{{
  digraph G {
  1->2
  2->3
  3->1

  4->5

  6->7
  7->8
  8->9
  9->10
  10->11
  11->6
  }
  }}}

  When called with a directed graph, the program returns the '''strong component''' statistics:

  {{{
  $graph-tool --load multi-comp.dot --component-size-histogram="comp-hist"
  $ cat comp-hist
  1.0     2
  3.0     1
  6.0     1
  }}}

  To see the component statistics if the graph were undirected, we just have to treat it as such:

  {{{
  $ graph-tool --load multi-comp.dot --undirected --component-size-histogram="comp-hist"
  $ cat comp-hist
  2.0     1
  3.0     1
  6.0     1
  }}}


  == Filtering ==

  Graphs can be filtered in several ways. None of them actually modify the internally kept graph, and are therefore of complexity O(1).

  === Directedness ===

  Internally, all graphs in graph-tool are directed graphs. But it is possible to treat them easily as directed with the "{{{--undirected}}}" option. All options after that will operate on a undirected filter of the internal directed graph. The "{{{--directed}}}" option reverts back to the default mode.

  === Edge direction ===

  Directed graphs can have the the edge direction reversed with the "{{{--reverse}}}" option. A second "{{{--reverse}}}" reverts back to the original state.

  === Filtering of vertices or edges ===

  ==== Range filtering ====

  Edges and vertices can be filtered out of the graph based on their properties. The most basic and fastest way of filtering is called "range filtering" and filters out vertices with a scalar property which lays outside a given range. The filtering is controlled with the "{{{--vertex-range-filter}}}" and "{{{--edge-range-filter}}}" options, which takes two parameters separated by "|": the property to be used as filter and the range (two values separated by space. Here's an example using the graph defined in [[ref(File Format Description)]]:

  {{{
  $ graph-tool --load example.xml --number-of-edges=-
  number of edges:        8
  $ graph-tool --load example.xml --edge-range-filter="weight|0.6 6.0" --number-of-edges=- --save filtered.dot
  number of edges:        4
  }}}

  The file {{{filtered.dot}}} contains (representation on the side):

  {{{
  #!html
  <div style="float: right;">
  }}}
  {{{
  #!graphviz
  digraph G {
  1;
  2;
  3;
  7;
  4;
  5;
  6;
  1->2  [label="1.2"];
  2->3  [label="0.8"];
  5->3  [label="5.5"];
  6->7  [label="2.0"];
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  {{{
  digraph G {
  1;
  2;
  3;
  7;
  4;
  5;
  6;
  1->2  [weight="1.2"];
  2->3  [weight="0.8"];
  5->3  [weight="5.5"];
  6->7  [weight="2"];
  }
  }}}

  ==== Generic Filtering ====

  Graphs can be filtered in a more versatile way than above (at a performance cost). This is done through the "{{{--vertex-filter}}}" and "{{{--edge-filter}}}" options, which take a generic [http://www.python.org python] expression as a parameter, and if it evaluates to {{{True}}} the vertex or edge is removed.

  Example:

  {{{
  #!html
  <div style="float: right;">
  }}}
  {{{
  #!graphviz
  digraph G {
  0;
  1;
  2;
  3;
  4;
  1->4  [label="0.5"];
  2->3  [label="10.1"];
  2->1  [label="5.5"];
  3->4  [label="2"];
  4->0  [label="0.1"];
  }
  }}}
  {{{
  #!html
  </div>
  }}}
  {{{
  $ graph-tool --load example.xml --edge-filter="weight==0.8" --vertex-filter="in_degree==0" --save filtered.dot
  $ cat filtered.dot
  digraph G {
  0;
  1;
  2;
  3;
  4;
  1->4  [weight="0.5"];
  2->3  [weight="10.1"];
  2->1  [weight="5.5"];
  3->4  [weight="2"];
  4->0  [weight="0.1"];
  }
  }}}

  {{{
  #!html
  <div class="note">
  }}}
  ===== Performace note =====
  When generic filtering is turned on, algorithms in general will run much slower, since the python interpreter will be involved in the computations. Therefore, if some expensive computation is being considered, it is in general better to save the graph to a file after the filtering, and load it as unfiltered to perform the computation.
  {{{
  #!html
  </div>
  }}}

  ==== Removing filtering ====

  The graph can be returned to its unfiltered state by calling "{{{--reset-vertex-filter}}}" and "{{{--reset-edge-filter}}}".

  == Graph Modifications ==

  There's a couple of options which change the internally kept graph.

  === Removing Properties ===

  Vertex and edge properties can be removed from the graph with the options "{{{--remove-vertex-property}}}" and "{{{--remove-edge-property}}}", which take the name of the property to be removed as parameter.

  === Vertex and Edge Indices ===

  Vertices and Edges are identified internally by indices. Those can be inserted as properties with the options "{{{--insert-vertex-index-property}}}" and "{{{--insert-edge-index-property}}}", which take as argument the name by which the property will be called.

  === Removal of Parallel Edges ===

  Parallel edges (i.e. edges that share the same source and target) can be removed from the graph with the option "{{{--remove-parallel-edges}}}", so that only one of the parallel edges ramain (it is undefined which one).


  == Correlations ==

  === Degree Correlation ===

  The degree correlation histogram is a bidimensional histogram defined as

  [[Equation(\[C(k,k')=\sum_{u,v}A_{uv}[k_u=k][k_v=k']\])]], where [[Equation($\mathbf{A}$)]] is the adjacenty matrix. It is obtainable with the "{{{--degree-correlation-histogram}}}" option, which takes three parameters separated by "|": First degree type ([[Equation($k_u$)]]), second degree type ([[Equation($k_v$)]]) and a filename. The degree types can be `in-degree`, `out-degree` and `total-degree`. It can also be the name of any vertex scalar property available.

  Example:

  {{{
  $ graph-tool --load example.xml --degree-correlation="in-degree|out-degree|deg-corr"
  $ cat deg-corr
  0.0     1.0     1
  0.0     2.0     1
  1.0     1.0     3
  2.0     1.0     3
  }}}

  It is also possible to obtain the correlation in an aternative fashion, which a lot of times is more convenient, and that is the average nearest neighbours degree, given by

  [[Equation(\[ \bar{k}(k)=\frac{\sum_{u,v}A_{uv}k_v[k_u=k]}{\sum_{u,v}A_{u,v}[k_u=k]}\])]].

  It is obtainable with the "`--average-nearest-neighbours-degree`" option, which takes four parameters separated by "|": type of neighbours, degree type of the origin vertex, degree type of the neighbours and a filename. Neighbour types can be "`all`", "`in`" and "`out`", for all, in and out-neighbours respectively. Origin and neighbour degree type can be "`in-degree`", "`out-degree`" and "`total-degree`", as well as the name of any vertex scalar property available.

  Example:

  {{{
  $ graph-tool --load example.xml --average-nearest-neighbours-degree="all|total-degree|in-degree|deg-corr"
  $ cat deg-corr
  1.0     1.5     0.5
  2.0     1.5     0.5
  3.0     1.41666666667   0.228908256511
  }}}

  The third column above is the standard deviation of the average in the second column.

  === Edge Correlation ===

  When edges have scalar properties, it is possible to generate a 3-dimensional correlation histogram defined as:

  [[Equation(\[ P(k,e_p,k')=\sum_{e}[k_{s(e)}=k][k_{t(e)}=k'][p(e)=e_p]}\])]], where ([[Equation($e$)]]) are the edges of the graph, ([[Equation($s(e)$)]]) and ([[Equation($t(e)$)]]) are the source and target vertex of edge ([[Equation($e$)]]), and ([[Equation($p(e)$)]]) is some property of the edge.

  This can be obtained with the "`--edge-degree-correlation-histogram`" option which takes four arguments separated by "|": Source degree type, edge property and target degree type. The source and target degree types can be "`in-degree`", "`out-degree`" and "`total-degree`", as well as the name of any vertex scalar property available.

  Example:
  {{{
  $ graph-tool --load example.xml --edge-degree-correlation-histogram="in-degree|weight|out-degree|edge-corr"
  $ cat edge-corr
  0.0     0.2     2.0     1
  0.0     1.2     1.0     1
  1.0     2.0     1.0     1
  1.0     5.5     1.0     1
  1.0     10.1    1.0     1
  2.0     0.1     1.0     1
  2.0     0.5     1.0     1
  2.0     0.8     1.0     1
  }}}

  === Vertex-Scalar Correlation ===

  If vertices have scalar properties, it is possible to correlate them with the degree or amongst themselves. Consider the following graph

      --vertex-scalar-correlation-histogram=DEGREE|VERTEX-PROP|FILE             get the degree vs. vertex scalar correlation histogram. Scalar properties are
                                                                                also accepted in place of DEGREE
      --assortativity-coefficient=NEIGHBOURS|DEGREE|DEGREE|FILE                 get the assortativity coefficient. Scalar properties are also accepted in place                                                                              of DEGREE (not yet)

  == Clustering ==

      --local-clustering-coefficient=FILE                                       get the local clustering coefficient
      --local-clustering-coefficient-histogram=DEGREE_TYPE|FILE                 get the local clustering coefficient histogram
      --set-local-clustering-to-property=PROPERTY                               set the local clustering coefficient to vertex property
      --global-clustering-coefficient=FILE                                      get the global clustering coefficient


  == Layout ==
      --compute-spring-block-layout=ITERATIONS[|SEED]                           compute the spring block layout
      --compute-gursoy-atun-layout=ITERATIONS[|SEED]                            compute the Gursoy-Atun layout


  == Random Graph Generation ==
      --correlated-configurational-model=OPTIONS                                generate graph using the configurational model with arbitrary degree
                                                                                correlations. Options are: N, pjk, pjk_ceil, pjk_m, inv_pjk_ceil, corr,
                                                                                corr_ceil, corr_m, inv_corr_ceil, undirected, directed, progress, seed. See
                                                                                documentation for details.

  == Graph History ==

      --history=INIT|CONDITION|STEP                                             compute graph history
      --history-rate=TIME  


name: GraphToolGuide
author: count0
ipnr: 201.52.69.185
text:
  = graph-tool Guide =

  [[PageOutline]]

  == Invoking ==

  graph-tool is invoked by typing {{{graph-tool}}} in the command line. For a quick summary of options type
  {{{
  graph-tool --help
  }}}


  == Loading and saving files ==

  Files can be loaded with the "{{{--load}}}" option. Graph tool supports both [http://graphml.graphdrawing.org/ graphml] and [http://www.graphviz.org/ dot] formats. The formats are identified by the file name extension: files ending in {{{.xml}}} are considered graphml files, and files ending in {{{.dot}}} are considered dot files. Files can also end in {{{.gz}}} or {{{.bz2}}} to indicate compression, such as {{{.xml.gz}}} or {{{.dot.bz2}}}. Files can be saved with the "{{{--save}}}" command, and the file name specifications are the same.

  === File format description ===

  Consider the following directed graph, with one floating point edge property (which will be called "weight"):
  {{{
  #!html
  <div style="text-align: center;">
  }}}
  {{{
  #!graphviz
  digraph G {
  start="12";
  1->2 [label = "  1.2  ", len=0.6];
  2->3 [label = "  0.8  ", len=0.6];
  3->7 [label = "  0.5", len=0.6];
  4->5 [label = "  0.2  ", len=0.6];
  5->6 [label = "  10.1  ", len=0.6];
  5->3 [label = "  5.5", len=0.6];
  6->7 [label = "  2.0", len=0.6];
  7->2 [label = "  0.1", len=0.6];
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  It can be defined in dot format as such:

  {{{
  digraph G {
  1->2 [weight = "1.2"];
  2->3 [weight = "0.8"];
  3->7 [weight = "0.5"];
  4->5 [weight = "0.2"];
  5->6 [weight = "10.1"];
  5->3 [weight = "5.5"];
  6->7 [weight = "2.0"];
  7->2 [weight = "0.1"];
  }
  }}}

  and in graphml format as such:

  {{{
  #!xml
  <?xml version="1.0" encoding="UTF-8"?>
  <graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://graphml.graphdrawing.org/xmlns/1.0/graphml.xsd">
    <key id="d1" for="edge" attr.name="weight" attr.type="double"/>
    <graph id="G" edgedefault="directed">
      <node id="n0"/>
      <node id="n1"/>
      <node id="n2"/>
      <node id="n3"/>
      <node id="n4"/>
      <node id="n5"/>
      <node id="n6"/>
      <edge id="e0" source="n0" target="n1">
        <data key="d1">1.2</data>
      </edge>
      <edge id="e1" source="n1" target="n2">
        <data key="d1">0.8</data>
      </edge>
      <edge id="e2" source="n2" target="n6">
        <data key="d1">0.5</data>
      </edge>
      <edge id="e3" source="n3" target="n4">
        <data key="d1">0.2</data>
      </edge>
      <edge id="e4" source="n4" target="n5">
        <data key="d1">10.1</data>
      </edge>
      <edge id="e5" source="n4" target="n2">
        <data key="d1">5.5</data>
      </edge>
      <edge id="e6" source="n5" target="n6">
        <data key="d1">2.0</data>
      </edge>
      <edge id="e7" source="n6" target="n1">
        <data key="d1">0.1</data>
      </edge>
    </graph>
  </graphml>
  }}}

  Vertex properties are done in an analogous manner. There's no limit on the number of properties the graph can have. 

  Graphs can also be undirected, and are loaded by specifiyng the option "{{{--undirected}}}" before "{{{--load}}}". Here's an example:

  {{{
  #!html
  <div style="text-align: center;">
  }}}
  {{{
  #!graphviz
  graph G {
  start="12";
  1--2 
  2--3 
  3--7 
  4--5 
  5--6 
  5--3 
  6--7 
  7--2 
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  In dot format:

  {{{
  graph G {
  1--2 
  2--3 
  3--7 
  4--5 
  5--6 
  5--3 
  6--7 
  7--2 
  }
  }}}

  and in graphml format:

  {{{
  #!xml
  <?xml version="1.0" encoding="UTF-8"?>
  <graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://graphml.graphdrawing.org/xmlns/1.0/graphml.xsd">
    <graph id="G" edgedefault="undirected">
      <node id="n0"/>
      <node id="n1"/>
      <node id="n2"/>
      <node id="n3"/>
      <node id="n4"/>
      <node id="n5"/>
      <node id="n6"/>
      <edge id="e0" source="n0" target="n1"/>
      <edge id="e1" source="n1" target="n2"/>
      <edge id="e2" source="n2" target="n6"/>
      <edge id="e3" source="n3" target="n4"/>
      <edge id="e4" source="n4" target="n5"/>
      <edge id="e5" source="n4" target="n2"/>
      <edge id="e6" source="n5" target="n6"/>
      <edge id="e7" source="n6" target="n1"/>
    </graph>
  </graphml>
  }}}

  {{{
  #!html
  <div class="note">
  }}}
  ==== Which format to use? ====

  You can of course use either format, but in general graphml is preferred. It provides for a tighter definition of the graph, and since graph-tool understants the parse info attributes of the graph, you can speed up the loading of the file and reduce memory usage by using the following in your graph definition:

  {{{
  #!xml
  ...
   <graph id="G" edgedefault="directed" parse.nodeids="canonical" parse.edgeids="canonical" parse.order="nodesfirst">
  ...
  }}}

  This says that all vertices and edges are named "n0","n1", ..., "nN-1", and  "e0", "e1", ..., "eE-1", respectively. And also it says that the vertex list comes before the edge list. You're not forced to define your graph this way, but it does improve performace for large graphs.

  {{{
  #!html
  </div>
  }}}

  ----

  == Basic Statistics ==

  The two most basic properties of the graph are the number of vertex and edges, which is obtainable through the "{{{--number-of-vertices}}}" and "{{{--number-of-edges}}}" options. Suppose the first graph in [[ref(File Format Description)]] is saved under {{{example.xml}}}. We can then get the number of vertices and edges by typing:

  {{{
  $ graph-tool --load example.xml --number-of-vertices=- --number-of-edges=-
  number of vertices:     7
  number of edges:        8
  }}}

  The "-" parameter to the options is necessary to output the results in the terminal. Otherwise it writes it to the file given in the parameter.

  === Degree Histogram ===

  The degree histogram can be obtained by the "{{{--degree-histogram}}}" option. It requires two parameters, separated by "|": degree type and file name. Degree type can be any of "in-degree", "out-degree", "total-degree" and __any vertex scalar property__. The file name is the file the histogram is written to, or "-" to be written to the terminal. Files may be terminated with {{{.gz}}} or {{{.bz2}}} for compression. Example:

  {{{
  $ graph-tool --load example.xml --degree-histogram="total-degree|deg-dist"
  $ cat deg-dist
  1.0     2
  2.0     1
  3.0     4
  }}}

  For directed graphs, it is also possible to get the combined (in,out)-degree histogram with the "{{{--combined-degree-histogram}}}" option:

  {{{
  $ graph-tool --load example.xml --combined-degree-histogram="deg-dist"
  $ cat deg-dist
  0.0     1.0     2
  1.0     1.0     1
  1.0     2.0     1
  2.0     1.0     3
  }}}

  === Average Distance ===

  The average vertex-vertex distance can be obtained with the "{{{--average-distance}}}" option:

  {{{
  $ graph-tool --load example.xml --average-distance=-
  average distance:       0.714285714286
  }}}

  For directed and/or disconnected graphs, it may be better to use the average harmonic distance defined as:

  [[Equation(\[d_h = \left[\sum_{v,u}\frac{1}{d_{uv}}\right]^{-1}\])]], where [[Equation($d_{uv}$)]] is the regular graph distance between [[Equation($u$)]] and [[Equation($v$)]], which here is taken to be infinity when there's no path between those two vertices.

  Example:

  {{{
  $ graph-tool --load example.xml --average-harmonic-distance=-
  average harmonic distance:      4.1226993865
  }}}

  === Component Size Histogram === 

  Component size statistics can be obtained by the "{{{component-size-histogram}}}" option. Consider the following graph:

  {{{
  #!html
  <div style="text-align: center;">
  }}}
  {{{
  #!graphviz
  digraph G {
  1->2
  2->3
  3->1

  4->5

  6->7
  7->8
  8->9
  9->10
  10->11
  11->6
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  Defined by the following dot file (henceforth referred to as {{{multi-comp.dot}}}):
  {{{
  digraph G {
  1->2
  2->3
  3->1

  4->5

  6->7
  7->8
  8->9
  9->10
  10->11
  11->6
  }
  }}}

  When called with a directed graph, the program returns the '''strong component''' statistics:

  {{{
  $graph-tool --load multi-comp.dot --component-size-histogram="comp-hist"
  $ cat comp-hist
  1.0     2
  3.0     1
  6.0     1
  }}}

  To see the component statistics if the graph were undirected, we just have to treat it as such:

  {{{
  $ graph-tool --load multi-comp.dot --undirected --component-size-histogram="comp-hist"
  $ cat comp-hist
  2.0     1
  3.0     1
  6.0     1
  }}}


  == Filtering ==

  Graphs can be filtered in several ways. None of them actually modify the internally kept graph, and are therefore of complexity O(1).

  === Directedness ===

  Internally, all graphs in graph-tool are directed graphs. But it is possible to treat them easily as directed with the "{{{--undirected}}}" option. All options after that will operate on a undirected filter of the internal directed graph. The "{{{--directed}}}" option reverts back to the default mode.

  === Edge direction ===

  Directed graphs can have the the edge direction reversed with the "{{{--reverse}}}" option. A second "{{{--reverse}}}" reverts back to the original state.

  === Filtering of vertices or edges ===

  ==== Range filtering ====

  Edges and vertices can be filtered out of the graph based on their properties. The most basic and fastest way of filtering is called "range filtering" and filters out vertices with a scalar property which lays outside a given range. The filtering is controlled with the "{{{--vertex-range-filter}}}" and "{{{--edge-range-filter}}}" options, which takes two parameters separated by "|": the property to be used as filter and the range (two values separated by space. Here's an example using the graph defined in [[ref(File Format Description)]]:

  {{{
  $ graph-tool --load example.xml --number-of-edges=-
  number of edges:        8
  $ graph-tool --load example.xml --edge-range-filter="weight|0.6 6.0" --number-of-edges=- --save filtered.dot
  number of edges:        4
  }}}

  The file {{{filtered.dot}}} contains (representation on the side):

  {{{
  #!html
  <div style="float: right;">
  }}}
  {{{
  #!graphviz
  digraph G {
  1;
  2;
  3;
  7;
  4;
  5;
  6;
  1->2  [label="1.2"];
  2->3  [label="0.8"];
  5->3  [label="5.5"];
  6->7  [label="2.0"];
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  {{{
  digraph G {
  1;
  2;
  3;
  7;
  4;
  5;
  6;
  1->2  [weight="1.2"];
  2->3  [weight="0.8"];
  5->3  [weight="5.5"];
  6->7  [weight="2"];
  }
  }}}

  ==== Generic Filtering ====

  Graphs can be filtered in a more versatile way than above (at a performance cost). This is done through the "{{{--vertex-filter}}}" and "{{{--edge-filter}}}" options, which take a generic [http://www.python.org python] expression as a parameter, and if it evaluates to {{{True}}} the vertex or edge is removed.

  Example:

  {{{
  #!html
  <div style="float: right;">
  }}}
  {{{
  #!graphviz
  digraph G {
  0;
  1;
  2;
  3;
  4;
  1->4  [label="0.5"];
  2->3  [label="10.1"];
  2->1  [label="5.5"];
  3->4  [label="2"];
  4->0  [label="0.1"];
  }
  }}}
  {{{
  #!html
  </div>
  }}}
  {{{
  $ graph-tool --load example.xml --edge-filter="weight==0.8" --vertex-filter="in_degree==0" --save filtered.dot
  $ cat filtered.dot
  digraph G {
  0;
  1;
  2;
  3;
  4;
  1->4  [weight="0.5"];
  2->3  [weight="10.1"];
  2->1  [weight="5.5"];
  3->4  [weight="2"];
  4->0  [weight="0.1"];
  }
  }}}

  {{{
  #!html
  <div class="note">
  }}}
  ===== Performace note =====
  When generic filtering is turned on, algorithms in general will run much slower, since the python interpreter will be involved in the computations. Therefore, if some expensive computation is being considered, it is in general better to save the graph to a file after the filtering, and load it as unfiltered to perform the computation.
  {{{
  #!html
  </div>
  }}}

  ==== Removing filtering ====

  The graph can be returned to its unfiltered state by calling "{{{--reset-vertex-filter}}}" and "{{{--reset-edge-filter}}}".

  == Graph Modifications ==

  There's a couple of options which change the internally kept graph.

  === Removing Properties ===

  Vertex and edge properties can be removed from the graph with the options "{{{--remove-vertex-property}}}" and "{{{--remove-edge-property}}}", which take the name of the property to be removed as parameter.

  === Vertex and Edge Indices ===

  Vertices and Edges are identified internally by indices. Those can be inserted as properties with the options "{{{--insert-vertex-index-property}}}" and "{{{--insert-edge-index-property}}}", which take as argument the name by which the property will be called.

  === Removal of Parallel Edges ===

  Parallel edges (i.e. edges that share the same source and target) can be removed from the graph with the option "{{{--remove-parallel-edges}}}", so that only one of the parallel edges ramain (it is undefined which one).


  == Correlations ==

  === Degree Correlation ===

  The degree correlation histogram is a bidimensional histogram defined as

  [[Equation(\[C(k,k')=\sum_{u,v}A_{uv}[k_u=k][k_v=k']\])]], where [[Equation($\mathbf{A}$)]] is the adjacenty matrix. It is obtainable with the "{{{--degree-correlation-histogram}}}" option, which takes three parameters separated by "|": First degree type ([[Equation($k_u$)]]), second degree type ([[Equation($k_v$)]]) and a filename. The degree types can be `in-degree`, `out-degree` and `total-degree`. It can also be the name of any vertex scalar property available.

  Example:

  {{{
  $ graph-tool --load example.xml --degree-correlation="in-degree|out-degree|deg-corr"
  $ cat deg-corr
  0.0     1.0     1
  0.0     2.0     1
  1.0     1.0     3
  2.0     1.0     3
  }}}

  It is also possible to obtain the correlation in an aternative fashion, which a lot of times is more convenient, and that is the average nearest neighbours degree, given by

  [[Equation(\[ \bar{k}(k)=\frac{\sum_{u,v}A_{uv}k_v[k_u=k]}{\sum_{u,v}A_{u,v}[k_u=k]}\])]].

  It is obtainable with the "`--average-nearest-neighbours-degree`" option, which takes four parameters separated by "|": type of neighbours, degree type of the origin vertex, degree type of the neighbours and a filename. Neighbour types can be "`all`", "`in`" and "`out`", for all, in and out-neighbours respectively. Origin and neighbour degree type can be "`in-degree`", "`out-degree`" and "`total-degree`", as well as the name of any vertex scalar property available.

  Example:

  {{{
  $ graph-tool --load example.xml --average-nearest-neighbours-degree="all|total-degree|in-degree|deg-corr"
  $ cat deg-corr
  1.0     1.5     0.5
  2.0     1.5     0.5
  3.0     1.41666666667   0.228908256511
  }}}

  The third column above is the standard deviation of the average in the second column.

  === Edge Correlation ===

  When edges have scalar properties, it is possible to generate a 3-dimensional correlation histogram defined as:

  [[Equation(\[ P(k,m,k')=\sum_{e}[k_{s(e)}=k][k_{t(e)}=k'][p(e)=m]}\])]], where ([[Equation($e$)]]) are the edges of the graph, ([[Equation($s(e) $)]]) and ([[Equation($t(e) $)]]) are the source and target vertex of edge ([[Equation($e$)]]), and ([[Equation($p(e) $)]]) is some property of the edge.

  This can be obtained with the "`--edge-degree-correlation-histogram`" option which takes four arguments separated by "|": Source degree type, edge property and target degree type. The source and target degree types can be "`in-degree`", "`out-degree`" and "`total-degree`", as well as the name of any vertex scalar property available.

  Example:
  {{{
  $ graph-tool --load example.xml --edge-degree-correlation-histogram="in-degree|weight|out-degree|edge-corr"
  $ cat edge-corr
  0.0     0.2     2.0     1
  0.0     1.2     1.0     1
  1.0     2.0     1.0     1
  1.0     5.5     1.0     1
  1.0     10.1    1.0     1
  2.0     0.1     1.0     1
  2.0     0.5     1.0     1
  2.0     0.8     1.0     1
  }}}

  === Vertex-Scalar Correlation ===

  If vertices have scalar properties, it is possible to correlate them with the degree or amongst themselves. Consider the following graph

      --vertex-scalar-correlation-histogram=DEGREE|VERTEX-PROP|FILE             get the degree vs. vertex scalar correlation histogram. Scalar properties are
                                                                                also accepted in place of DEGREE
      --assortativity-coefficient=NEIGHBOURS|DEGREE|DEGREE|FILE                 get the assortativity coefficient. Scalar properties are also accepted in place                                                                              of DEGREE (not yet)

  == Clustering ==

      --local-clustering-coefficient=FILE                                       get the local clustering coefficient
      --local-clustering-coefficient-histogram=DEGREE_TYPE|FILE                 get the local clustering coefficient histogram
      --set-local-clustering-to-property=PROPERTY                               set the local clustering coefficient to vertex property
      --global-clustering-coefficient=FILE                                      get the global clustering coefficient


  == Layout ==
      --compute-spring-block-layout=ITERATIONS[|SEED]                           compute the spring block layout
      --compute-gursoy-atun-layout=ITERATIONS[|SEED]                            compute the Gursoy-Atun layout


  == Random Graph Generation ==
      --correlated-configurational-model=OPTIONS                                generate graph using the configurational model with arbitrary degree
                                                                                correlations. Options are: N, pjk, pjk_ceil, pjk_m, inv_pjk_ceil, corr,
                                                                                corr_ceil, corr_m, inv_corr_ceil, undirected, directed, progress, seed. See
                                                                                documentation for details.

  == Graph History ==

      --history=INIT|CONDITION|STEP                                             compute graph history
      --history-rate=TIME  


name: GraphToolGuide
author: count0
ipnr: 201.52.69.185
text:
  = graph-tool Guide =

  [[PageOutline]]

  == Invoking ==

  graph-tool is invoked by typing {{{graph-tool}}} in the command line. For a quick summary of options type
  {{{
  graph-tool --help
  }}}


  == Loading and saving files ==

  Files can be loaded with the "{{{--load}}}" option. Graph tool supports both [http://graphml.graphdrawing.org/ graphml] and [http://www.graphviz.org/ dot] formats. The formats are identified by the file name extension: files ending in {{{.xml}}} are considered graphml files, and files ending in {{{.dot}}} are considered dot files. Files can also end in {{{.gz}}} or {{{.bz2}}} to indicate compression, such as {{{.xml.gz}}} or {{{.dot.bz2}}}. Files can be saved with the "{{{--save}}}" command, and the file name specifications are the same.

  === File format description ===

  Consider the following directed graph, with one floating point edge property (which will be called "weight"):
  {{{
  #!html
  <div style="text-align: center;">
  }}}
  {{{
  #!graphviz
  digraph G {
  start="12";
  1->2 [label = "  1.2  ", len=0.6];
  2->3 [label = "  0.8  ", len=0.6];
  3->7 [label = "  0.5", len=0.6];
  4->5 [label = "  0.2  ", len=0.6];
  5->6 [label = "  10.1  ", len=0.6];
  5->3 [label = "  5.5", len=0.6];
  6->7 [label = "  2.0", len=0.6];
  7->2 [label = "  0.1", len=0.6];
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  It can be defined in dot format as such:

  {{{
  digraph G {
  1->2 [weight = "1.2"];
  2->3 [weight = "0.8"];
  3->7 [weight = "0.5"];
  4->5 [weight = "0.2"];
  5->6 [weight = "10.1"];
  5->3 [weight = "5.5"];
  6->7 [weight = "2.0"];
  7->2 [weight = "0.1"];
  }
  }}}

  and in graphml format as such:

  {{{
  #!xml
  <?xml version="1.0" encoding="UTF-8"?>
  <graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://graphml.graphdrawing.org/xmlns/1.0/graphml.xsd">
    <key id="d1" for="edge" attr.name="weight" attr.type="double"/>
    <graph id="G" edgedefault="directed">
      <node id="n0"/>
      <node id="n1"/>
      <node id="n2"/>
      <node id="n3"/>
      <node id="n4"/>
      <node id="n5"/>
      <node id="n6"/>
      <edge id="e0" source="n0" target="n1">
        <data key="d1">1.2</data>
      </edge>
      <edge id="e1" source="n1" target="n2">
        <data key="d1">0.8</data>
      </edge>
      <edge id="e2" source="n2" target="n6">
        <data key="d1">0.5</data>
      </edge>
      <edge id="e3" source="n3" target="n4">
        <data key="d1">0.2</data>
      </edge>
      <edge id="e4" source="n4" target="n5">
        <data key="d1">10.1</data>
      </edge>
      <edge id="e5" source="n4" target="n2">
        <data key="d1">5.5</data>
      </edge>
      <edge id="e6" source="n5" target="n6">
        <data key="d1">2.0</data>
      </edge>
      <edge id="e7" source="n6" target="n1">
        <data key="d1">0.1</data>
      </edge>
    </graph>
  </graphml>
  }}}

  Vertex properties are done in an analogous manner. There's no limit on the number of properties the graph can have. 

  Graphs can also be undirected, and are loaded by specifiyng the option "{{{--undirected}}}" before "{{{--load}}}". Here's an example:

  {{{
  #!html
  <div style="text-align: center;">
  }}}
  {{{
  #!graphviz
  graph G {
  start="12";
  1--2 
  2--3 
  3--7 
  4--5 
  5--6 
  5--3 
  6--7 
  7--2 
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  In dot format:

  {{{
  graph G {
  1--2 
  2--3 
  3--7 
  4--5 
  5--6 
  5--3 
  6--7 
  7--2 
  }
  }}}

  and in graphml format:

  {{{
  #!xml
  <?xml version="1.0" encoding="UTF-8"?>
  <graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://graphml.graphdrawing.org/xmlns/1.0/graphml.xsd">
    <graph id="G" edgedefault="undirected">
      <node id="n0"/>
      <node id="n1"/>
      <node id="n2"/>
      <node id="n3"/>
      <node id="n4"/>
      <node id="n5"/>
      <node id="n6"/>
      <edge id="e0" source="n0" target="n1"/>
      <edge id="e1" source="n1" target="n2"/>
      <edge id="e2" source="n2" target="n6"/>
      <edge id="e3" source="n3" target="n4"/>
      <edge id="e4" source="n4" target="n5"/>
      <edge id="e5" source="n4" target="n2"/>
      <edge id="e6" source="n5" target="n6"/>
      <edge id="e7" source="n6" target="n1"/>
    </graph>
  </graphml>
  }}}

  {{{
  #!html
  <div class="note">
  }}}
  ==== Which format to use? ====

  You can of course use either format, but in general graphml is preferred. It provides for a tighter definition of the graph, and since graph-tool understants the parse info attributes of the graph, you can speed up the loading of the file and reduce memory usage by using the following in your graph definition:

  {{{
  #!xml
  ...
   <graph id="G" edgedefault="directed" parse.nodeids="canonical" parse.edgeids="canonical" parse.order="nodesfirst">
  ...
  }}}

  This says that all vertices and edges are named "n0","n1", ..., "nN-1", and  "e0", "e1", ..., "eE-1", respectively. And also it says that the vertex list comes before the edge list. You're not forced to define your graph this way, but it does improve performace for large graphs.

  {{{
  #!html
  </div>
  }}}

  ----

  == Basic Statistics ==

  The two most basic properties of the graph are the number of vertex and edges, which is obtainable through the "{{{--number-of-vertices}}}" and "{{{--number-of-edges}}}" options. Suppose the first graph in [[ref(File Format Description)]] is saved under {{{example.xml}}}. We can then get the number of vertices and edges by typing:

  {{{
  $ graph-tool --load example.xml --number-of-vertices=- --number-of-edges=-
  number of vertices:     7
  number of edges:        8
  }}}

  The "-" parameter to the options is necessary to output the results in the terminal. Otherwise it writes it to the file given in the parameter.

  === Degree Histogram ===

  The degree histogram can be obtained by the "{{{--degree-histogram}}}" option. It requires two parameters, separated by "|": degree type and file name. Degree type can be any of "in-degree", "out-degree", "total-degree" and __any vertex scalar property__. The file name is the file the histogram is written to, or "-" to be written to the terminal. Files may be terminated with {{{.gz}}} or {{{.bz2}}} for compression. Example:

  {{{
  $ graph-tool --load example.xml --degree-histogram="total-degree|deg-dist"
  $ cat deg-dist
  1.0     2
  2.0     1
  3.0     4
  }}}

  For directed graphs, it is also possible to get the combined (in,out)-degree histogram with the "{{{--combined-degree-histogram}}}" option:

  {{{
  $ graph-tool --load example.xml --combined-degree-histogram="deg-dist"
  $ cat deg-dist
  0.0     1.0     2
  1.0     1.0     1
  1.0     2.0     1
  2.0     1.0     3
  }}}

  === Average Distance ===

  The average vertex-vertex distance can be obtained with the "{{{--average-distance}}}" option:

  {{{
  $ graph-tool --load example.xml --average-distance=-
  average distance:       0.714285714286
  }}}

  For directed and/or disconnected graphs, it may be better to use the average harmonic distance defined as:

  [[Equation(\[d_h = \left[\sum_{v,u}\frac{1}{d_{uv}}\right]^{-1}\])]], where [[Equation($d_{uv}$)]] is the regular graph distance between [[Equation($u$)]] and [[Equation($v$)]], which here is taken to be infinity when there's no path between those two vertices.

  Example:

  {{{
  $ graph-tool --load example.xml --average-harmonic-distance=-
  average harmonic distance:      4.1226993865
  }}}

  === Component Size Histogram === 

  Component size statistics can be obtained by the "{{{component-size-histogram}}}" option. Consider the following graph:

  {{{
  #!html
  <div style="text-align: center;">
  }}}
  {{{
  #!graphviz
  digraph G {
  1->2
  2->3
  3->1

  4->5

  6->7
  7->8
  8->9
  9->10
  10->11
  11->6
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  Defined by the following dot file (henceforth referred to as {{{multi-comp.dot}}}):
  {{{
  digraph G {
  1->2
  2->3
  3->1

  4->5

  6->7
  7->8
  8->9
  9->10
  10->11
  11->6
  }
  }}}

  When called with a directed graph, the program returns the '''strong component''' statistics:

  {{{
  $graph-tool --load multi-comp.dot --component-size-histogram="comp-hist"
  $ cat comp-hist
  1.0     2
  3.0     1
  6.0     1
  }}}

  To see the component statistics if the graph were undirected, we just have to treat it as such:

  {{{
  $ graph-tool --load multi-comp.dot --undirected --component-size-histogram="comp-hist"
  $ cat comp-hist
  2.0     1
  3.0     1
  6.0     1
  }}}


  == Filtering ==

  Graphs can be filtered in several ways. None of them actually modify the internally kept graph, and are therefore of complexity O(1).

  === Directedness ===

  Internally, all graphs in graph-tool are directed graphs. But it is possible to treat them easily as directed with the "{{{--undirected}}}" option. All options after that will operate on a undirected filter of the internal directed graph. The "{{{--directed}}}" option reverts back to the default mode.

  === Edge direction ===

  Directed graphs can have the the edge direction reversed with the "{{{--reverse}}}" option. A second "{{{--reverse}}}" reverts back to the original state.

  === Filtering of vertices or edges ===

  ==== Range filtering ====

  Edges and vertices can be filtered out of the graph based on their properties. The most basic and fastest way of filtering is called "range filtering" and filters out vertices with a scalar property which lays outside a given range. The filtering is controlled with the "{{{--vertex-range-filter}}}" and "{{{--edge-range-filter}}}" options, which takes two parameters separated by "|": the property to be used as filter and the range (two values separated by space. Here's an example using the graph defined in [[ref(File Format Description)]]:

  {{{
  $ graph-tool --load example.xml --number-of-edges=-
  number of edges:        8
  $ graph-tool --load example.xml --edge-range-filter="weight|0.6 6.0" --number-of-edges=- --save filtered.dot
  number of edges:        4
  }}}

  The file {{{filtered.dot}}} contains (representation on the side):

  {{{
  #!html
  <div style="float: right;">
  }}}
  {{{
  #!graphviz
  digraph G {
  1;
  2;
  3;
  7;
  4;
  5;
  6;
  1->2  [label="1.2"];
  2->3  [label="0.8"];
  5->3  [label="5.5"];
  6->7  [label="2.0"];
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  {{{
  digraph G {
  1;
  2;
  3;
  7;
  4;
  5;
  6;
  1->2  [weight="1.2"];
  2->3  [weight="0.8"];
  5->3  [weight="5.5"];
  6->7  [weight="2"];
  }
  }}}

  ==== Generic Filtering ====

  Graphs can be filtered in a more versatile way than above (at a performance cost). This is done through the "{{{--vertex-filter}}}" and "{{{--edge-filter}}}" options, which take a generic [http://www.python.org python] expression as a parameter, and if it evaluates to {{{True}}} the vertex or edge is removed.

  Example:

  {{{
  #!html
  <div style="float: right;">
  }}}
  {{{
  #!graphviz
  digraph G {
  0;
  1;
  2;
  3;
  4;
  1->4  [label="0.5"];
  2->3  [label="10.1"];
  2->1  [label="5.5"];
  3->4  [label="2"];
  4->0  [label="0.1"];
  }
  }}}
  {{{
  #!html
  </div>
  }}}
  {{{
  $ graph-tool --load example.xml --edge-filter="weight==0.8" --vertex-filter="in_degree==0" --save filtered.dot
  $ cat filtered.dot
  digraph G {
  0;
  1;
  2;
  3;
  4;
  1->4  [weight="0.5"];
  2->3  [weight="10.1"];
  2->1  [weight="5.5"];
  3->4  [weight="2"];
  4->0  [weight="0.1"];
  }
  }}}

  {{{
  #!html
  <div class="note">
  }}}
  ===== Performace note =====
  When generic filtering is turned on, algorithms in general will run much slower, since the python interpreter will be involved in the computations. Therefore, if some expensive computation is being considered, it is in general better to save the graph to a file after the filtering, and load it as unfiltered to perform the computation.
  {{{
  #!html
  </div>
  }}}

  ==== Removing filtering ====

  The graph can be returned to its unfiltered state by calling "{{{--reset-vertex-filter}}}" and "{{{--reset-edge-filter}}}".

  == Graph Modifications ==

  There's a couple of options which change the internally kept graph.

  === Removing Properties ===

  Vertex and edge properties can be removed from the graph with the options "{{{--remove-vertex-property}}}" and "{{{--remove-edge-property}}}", which take the name of the property to be removed as parameter.

  === Vertex and Edge Indices ===

  Vertices and Edges are identified internally by indices. Those can be inserted as properties with the options "{{{--insert-vertex-index-property}}}" and "{{{--insert-edge-index-property}}}", which take as argument the name by which the property will be called.

  === Removal of Parallel Edges ===

  Parallel edges (i.e. edges that share the same source and target) can be removed from the graph with the option "{{{--remove-parallel-edges}}}", so that only one of the parallel edges ramain (it is undefined which one).


  == Correlations ==

  === Degree Correlation ===

  The degree correlation histogram is a bidimensional histogram defined as

  [[Equation(\[C(k,k')=\sum_{u,v}A_{uv}[k_u=k][k_v=k']\])]], where [[Equation($\mathbf{A}$)]] is the adjacenty matrix. It is obtainable with the "{{{--degree-correlation-histogram}}}" option, which takes three parameters separated by "|": First degree type ([[Equation($k_u$)]]), second degree type ([[Equation($k_v$)]]) and a filename. The degree types can be `in-degree`, `out-degree` and `total-degree`. It can also be the name of any vertex scalar property available.

  Example:

  {{{
  $ graph-tool --load example.xml --degree-correlation="in-degree|out-degree|deg-corr"
  $ cat deg-corr
  0.0     1.0     1
  0.0     2.0     1
  1.0     1.0     3
  2.0     1.0     3
  }}}

  It is also possible to obtain the correlation in an aternative fashion, which a lot of times is more convenient, and that is the average nearest neighbours degree, given by

  [[Equation(\[ \bar{k}(k)=\frac{\sum_{u,v}A_{uv}k_v[k_u=k]}{\sum_{u,v}A_{uv}[k_u=k]}\])]].

  It is obtainable with the "`--average-nearest-neighbours-degree`" option, which takes four parameters separated by "|": type of neighbours, degree type of the origin vertex, degree type of the neighbours and a filename. Neighbour types can be "`all`", "`in`" and "`out`", for all, in and out-neighbours respectively. Origin and neighbour degree type can be "`in-degree`", "`out-degree`" and "`total-degree`", as well as the name of any vertex scalar property available.

  Example:

  {{{
  $ graph-tool --load example.xml --average-nearest-neighbours-degree="all|total-degree|in-degree|deg-corr"
  $ cat deg-corr
  1.0     1.5     0.5
  2.0     1.5     0.5
  3.0     1.41666666667   0.228908256511
  }}}

  The third column above is the standard deviation of the average in the second column.

  === Edge Correlation ===

  When edges have scalar properties, it is possible to generate a 3-dimensional correlation histogram defined as:

  [[Equation(\[ P(k,m,k')=\sum_{e}[k_{s(e)}=k][k_{t(e)}=k'][p(e)=m]}\])]], where [[Equation($e$)]] are the edges of the graph, [[Equation(\[s(e)\])]] and [[Equation(\[t(e)\])]] are the source and target vertex of edge [[Equation($e$)]], and [[Equation(\[p(e)\])]] is some property of the edge.

  This can be obtained with the "`--edge-degree-correlation-histogram`" option which takes four arguments separated by "|": Source degree type, edge property and target degree type. The source and target degree types can be "`in-degree`", "`out-degree`" and "`total-degree`", as well as the name of any vertex scalar property available.

  Example:
  {{{
  $ graph-tool --load example.xml --edge-degree-correlation-histogram="in-degree|weight|out-degree|edge-corr"
  $ cat edge-corr
  0.0     0.2     2.0     1
  0.0     1.2     1.0     1
  1.0     2.0     1.0     1
  1.0     5.5     1.0     1
  1.0     10.1    1.0     1
  2.0     0.1     1.0     1
  2.0     0.5     1.0     1
  2.0     0.8     1.0     1
  }}}

  === Assortativity Coefficient ===

  The assortativity coefficient tells in a concise fashion how vertices of different types are preferencially connected amongst themselves, and is defined by

  [[Equation(\[r = \frac{\sum_i e_{ii} - \sum_i a_i b_i}{1-\sum_i a_i b_i}\])]] where [[Equation(\[a_i=\sum_je_{ij}\])]] and [[Equation(\[b_j=\sum_ie_{ij}\])]], and [[Equation($e_{ij}$)]] is the fraction of edges from a vertex of type $i$ to a vertex of type $j$.

  It is obtained by the option "`--assortativity-coefficient`", which takes four arguments: The type of neighbour to be considered for the matrix [[Equation($mathbf{e}$)]], the=NEIGHBOURS|DEGREE|DEGREE|FILE                 get the assortativity coefficient. Scalar properties are also accepted in place                                                                              of DEGREE (not yet)

  == Clustering ==

      --local-clustering-coefficient=FILE                                       get the local clustering coefficient
      --local-clustering-coefficient-histogram=DEGREE_TYPE|FILE                 get the local clustering coefficient histogram
      --set-local-clustering-to-property=PROPERTY                               set the local clustering coefficient to vertex property
      --global-clustering-coefficient=FILE                                      get the global clustering coefficient


  == Layout ==
      --compute-spring-block-layout=ITERATIONS[|SEED]                           compute the spring block layout
      --compute-gursoy-atun-layout=ITERATIONS[|SEED]                            compute the Gursoy-Atun layout


  == Random Graph Generation ==
      --correlated-configurational-model=OPTIONS                                generate graph using the configurational model with arbitrary degree
                                                                                correlations. Options are: N, pjk, pjk_ceil, pjk_m, inv_pjk_ceil, corr,
                                                                                corr_ceil, corr_m, inv_corr_ceil, undirected, directed, progress, seed. See
                                                                                documentation for details.

  == Graph History ==

      --history=INIT|CONDITION|STEP                                             compute graph history
      --history-rate=TIME  


name: GraphToolGuide
author: count0
ipnr: 201.52.69.185
text:
  = graph-tool Guide =

  [[PageOutline]]

  == Invoking ==

  graph-tool is invoked by typing {{{graph-tool}}} in the command line. For a quick summary of options type
  {{{
  graph-tool --help
  }}}


  == Loading and saving files ==

  Files can be loaded with the "{{{--load}}}" option. Graph tool supports both [http://graphml.graphdrawing.org/ graphml] and [http://www.graphviz.org/ dot] formats. The formats are identified by the file name extension: files ending in {{{.xml}}} are considered graphml files, and files ending in {{{.dot}}} are considered dot files. Files can also end in {{{.gz}}} or {{{.bz2}}} to indicate compression, such as {{{.xml.gz}}} or {{{.dot.bz2}}}. Files can be saved with the "{{{--save}}}" command, and the file name specifications are the same.

  === File format description ===

  Consider the following directed graph, with one floating point edge property (which will be called "weight"):
  {{{
  #!html
  <div style="text-align: center;">
  }}}
  {{{
  #!graphviz
  digraph G {
  start="12";
  1->2 [label = "  1.2  ", len=0.6];
  2->3 [label = "  0.8  ", len=0.6];
  3->7 [label = "  0.5", len=0.6];
  4->5 [label = "  0.2  ", len=0.6];
  5->6 [label = "  10.1  ", len=0.6];
  5->3 [label = "  5.5", len=0.6];
  6->7 [label = "  2.0", len=0.6];
  7->2 [label = "  0.1", len=0.6];
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  It can be defined in dot format as such:

  {{{
  digraph G {
  1->2 [weight = "1.2"];
  2->3 [weight = "0.8"];
  3->7 [weight = "0.5"];
  4->5 [weight = "0.2"];
  5->6 [weight = "10.1"];
  5->3 [weight = "5.5"];
  6->7 [weight = "2.0"];
  7->2 [weight = "0.1"];
  }
  }}}

  and in graphml format as such:

  {{{
  #!xml
  <?xml version="1.0" encoding="UTF-8"?>
  <graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://graphml.graphdrawing.org/xmlns/1.0/graphml.xsd">
    <key id="d1" for="edge" attr.name="weight" attr.type="double"/>
    <graph id="G" edgedefault="directed">
      <node id="n0"/>
      <node id="n1"/>
      <node id="n2"/>
      <node id="n3"/>
      <node id="n4"/>
      <node id="n5"/>
      <node id="n6"/>
      <edge id="e0" source="n0" target="n1">
        <data key="d1">1.2</data>
      </edge>
      <edge id="e1" source="n1" target="n2">
        <data key="d1">0.8</data>
      </edge>
      <edge id="e2" source="n2" target="n6">
        <data key="d1">0.5</data>
      </edge>
      <edge id="e3" source="n3" target="n4">
        <data key="d1">0.2</data>
      </edge>
      <edge id="e4" source="n4" target="n5">
        <data key="d1">10.1</data>
      </edge>
      <edge id="e5" source="n4" target="n2">
        <data key="d1">5.5</data>
      </edge>
      <edge id="e6" source="n5" target="n6">
        <data key="d1">2.0</data>
      </edge>
      <edge id="e7" source="n6" target="n1">
        <data key="d1">0.1</data>
      </edge>
    </graph>
  </graphml>
  }}}

  Vertex properties are done in an analogous manner. There's no limit on the number of properties the graph can have. 

  Graphs can also be undirected, and are loaded by specifiyng the option "{{{--undirected}}}" before "{{{--load}}}". Here's an example:

  {{{
  #!html
  <div style="text-align: center;">
  }}}
  {{{
  #!graphviz
  graph G {
  start="12";
  1--2 
  2--3 
  3--7 
  4--5 
  5--6 
  5--3 
  6--7 
  7--2 
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  In dot format:

  {{{
  graph G {
  1--2 
  2--3 
  3--7 
  4--5 
  5--6 
  5--3 
  6--7 
  7--2 
  }
  }}}

  and in graphml format:

  {{{
  #!xml
  <?xml version="1.0" encoding="UTF-8"?>
  <graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://graphml.graphdrawing.org/xmlns/1.0/graphml.xsd">
    <graph id="G" edgedefault="undirected">
      <node id="n0"/>
      <node id="n1"/>
      <node id="n2"/>
      <node id="n3"/>
      <node id="n4"/>
      <node id="n5"/>
      <node id="n6"/>
      <edge id="e0" source="n0" target="n1"/>
      <edge id="e1" source="n1" target="n2"/>
      <edge id="e2" source="n2" target="n6"/>
      <edge id="e3" source="n3" target="n4"/>
      <edge id="e4" source="n4" target="n5"/>
      <edge id="e5" source="n4" target="n2"/>
      <edge id="e6" source="n5" target="n6"/>
      <edge id="e7" source="n6" target="n1"/>
    </graph>
  </graphml>
  }}}

  {{{
  #!html
  <div class="note">
  }}}
  ==== Which format to use? ====

  You can of course use either format, but in general graphml is preferred. It provides for a tighter definition of the graph, and since graph-tool understants the parse info attributes of the graph, you can speed up the loading of the file and reduce memory usage by using the following in your graph definition:

  {{{
  #!xml
  ...
   <graph id="G" edgedefault="directed" parse.nodeids="canonical" parse.edgeids="canonical" parse.order="nodesfirst">
  ...
  }}}

  This says that all vertices and edges are named "n0","n1", ..., "nN-1", and  "e0", "e1", ..., "eE-1", respectively. And also it says that the vertex list comes before the edge list. You're not forced to define your graph this way, but it does improve performace for large graphs.

  {{{
  #!html
  </div>
  }}}

  ----

  == Basic Statistics ==

  The two most basic properties of the graph are the number of vertex and edges, which is obtainable through the "{{{--number-of-vertices}}}" and "{{{--number-of-edges}}}" options. Suppose the first graph in [[ref(File Format Description)]] is saved under {{{example.xml}}}. We can then get the number of vertices and edges by typing:

  {{{
  $ graph-tool --load example.xml --number-of-vertices=- --number-of-edges=-
  number of vertices:     7
  number of edges:        8
  }}}

  The "-" parameter to the options is necessary to output the results in the terminal. Otherwise it writes it to the file given in the parameter.

  === Degree Histogram ===

  The degree histogram can be obtained by the "{{{--degree-histogram}}}" option. It requires two parameters, separated by "|": degree type and file name. Degree type can be any of "in-degree", "out-degree", "total-degree" and __any vertex scalar property__. The file name is the file the histogram is written to, or "-" to be written to the terminal. Files may be terminated with {{{.gz}}} or {{{.bz2}}} for compression. Example:

  {{{
  $ graph-tool --load example.xml --degree-histogram="total-degree|deg-dist"
  $ cat deg-dist
  1.0     2
  2.0     1
  3.0     4
  }}}

  For directed graphs, it is also possible to get the combined (in,out)-degree histogram with the "{{{--combined-degree-histogram}}}" option:

  {{{
  $ graph-tool --load example.xml --combined-degree-histogram="deg-dist"
  $ cat deg-dist
  0.0     1.0     2
  1.0     1.0     1
  1.0     2.0     1
  2.0     1.0     3
  }}}

  === Average Distance ===

  The average vertex-vertex distance can be obtained with the "{{{--average-distance}}}" option:

  {{{
  $ graph-tool --load example.xml --average-distance=-
  average distance:       0.714285714286
  }}}

  For directed and/or disconnected graphs, it may be better to use the average harmonic distance defined as:

  [[Equation(\[d_h = \left[\sum_{v,u}\frac{1}{d_{uv}}\right]^{-1}\])]], where [[Equation($d_{uv}$)]] is the regular graph distance between [[Equation($u$)]] and [[Equation($v$)]], which here is taken to be infinity when there's no path between those two vertices.

  Example:

  {{{
  $ graph-tool --load example.xml --average-harmonic-distance=-
  average harmonic distance:      4.1226993865
  }}}

  === Component Size Histogram === 

  Component size statistics can be obtained by the "{{{component-size-histogram}}}" option. Consider the following graph:

  {{{
  #!html
  <div style="text-align: center;">
  }}}
  {{{
  #!graphviz
  digraph G {
  1->2
  2->3
  3->1

  4->5

  6->7
  7->8
  8->9
  9->10
  10->11
  11->6
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  Defined by the following dot file (henceforth referred to as {{{multi-comp.dot}}}):
  {{{
  digraph G {
  1->2
  2->3
  3->1

  4->5

  6->7
  7->8
  8->9
  9->10
  10->11
  11->6
  }
  }}}

  When called with a directed graph, the program returns the '''strong component''' statistics:

  {{{
  $graph-tool --load multi-comp.dot --component-size-histogram="comp-hist"
  $ cat comp-hist
  1.0     2
  3.0     1
  6.0     1
  }}}

  To see the component statistics if the graph were undirected, we just have to treat it as such:

  {{{
  $ graph-tool --load multi-comp.dot --undirected --component-size-histogram="comp-hist"
  $ cat comp-hist
  2.0     1
  3.0     1
  6.0     1
  }}}


  == Filtering ==

  Graphs can be filtered in several ways. None of them actually modify the internally kept graph, and are therefore of complexity O(1).

  === Directedness ===

  Internally, all graphs in graph-tool are directed graphs. But it is possible to treat them easily as directed with the "{{{--undirected}}}" option. All options after that will operate on a undirected filter of the internal directed graph. The "{{{--directed}}}" option reverts back to the default mode.

  === Edge direction ===

  Directed graphs can have the the edge direction reversed with the "{{{--reverse}}}" option. A second "{{{--reverse}}}" reverts back to the original state.

  === Filtering of vertices or edges ===

  ==== Range filtering ====

  Edges and vertices can be filtered out of the graph based on their properties. The most basic and fastest way of filtering is called "range filtering" and filters out vertices with a scalar property which lays outside a given range. The filtering is controlled with the "{{{--vertex-range-filter}}}" and "{{{--edge-range-filter}}}" options, which takes two parameters separated by "|": the property to be used as filter and the range (two values separated by space. Here's an example using the graph defined in [[ref(File Format Description)]]:

  {{{
  $ graph-tool --load example.xml --number-of-edges=-
  number of edges:        8
  $ graph-tool --load example.xml --edge-range-filter="weight|0.6 6.0" --number-of-edges=- --save filtered.dot
  number of edges:        4
  }}}

  The file {{{filtered.dot}}} contains (representation on the side):

  {{{
  #!html
  <div style="float: right;">
  }}}
  {{{
  #!graphviz
  digraph G {
  1;
  2;
  3;
  7;
  4;
  5;
  6;
  1->2  [label="1.2"];
  2->3  [label="0.8"];
  5->3  [label="5.5"];
  6->7  [label="2.0"];
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  {{{
  digraph G {
  1;
  2;
  3;
  7;
  4;
  5;
  6;
  1->2  [weight="1.2"];
  2->3  [weight="0.8"];
  5->3  [weight="5.5"];
  6->7  [weight="2"];
  }
  }}}

  ==== Generic Filtering ====

  Graphs can be filtered in a more versatile way than above (at a performance cost). This is done through the "{{{--vertex-filter}}}" and "{{{--edge-filter}}}" options, which take a generic [http://www.python.org python] expression as a parameter, and if it evaluates to {{{True}}} the vertex or edge is removed.

  Example:

  {{{
  #!html
  <div style="float: right;">
  }}}
  {{{
  #!graphviz
  digraph G {
  0;
  1;
  2;
  3;
  4;
  1->4  [label="0.5"];
  2->3  [label="10.1"];
  2->1  [label="5.5"];
  3->4  [label="2"];
  4->0  [label="0.1"];
  }
  }}}
  {{{
  #!html
  </div>
  }}}
  {{{
  $ graph-tool --load example.xml --edge-filter="weight==0.8" --vertex-filter="in_degree==0" --save filtered.dot
  $ cat filtered.dot
  digraph G {
  0;
  1;
  2;
  3;
  4;
  1->4  [weight="0.5"];
  2->3  [weight="10.1"];
  2->1  [weight="5.5"];
  3->4  [weight="2"];
  4->0  [weight="0.1"];
  }
  }}}

  {{{
  #!html
  <div class="note">
  }}}
  ===== Performace note =====
  When generic filtering is turned on, algorithms in general will run much slower, since the python interpreter will be involved in the computations. Therefore, if some expensive computation is being considered, it is in general better to save the graph to a file after the filtering, and load it as unfiltered to perform the computation.
  {{{
  #!html
  </div>
  }}}

  ==== Removing filtering ====

  The graph can be returned to its unfiltered state by calling "{{{--reset-vertex-filter}}}" and "{{{--reset-edge-filter}}}".

  == Graph Modifications ==

  There's a couple of options which change the internally kept graph.

  === Removing Properties ===

  Vertex and edge properties can be removed from the graph with the options "{{{--remove-vertex-property}}}" and "{{{--remove-edge-property}}}", which take the name of the property to be removed as parameter.

  === Vertex and Edge Indices ===

  Vertices and Edges are identified internally by indices. Those can be inserted as properties with the options "{{{--insert-vertex-index-property}}}" and "{{{--insert-edge-index-property}}}", which take as argument the name by which the property will be called.

  === Removal of Parallel Edges ===

  Parallel edges (i.e. edges that share the same source and target) can be removed from the graph with the option "{{{--remove-parallel-edges}}}", so that only one of the parallel edges ramain (it is undefined which one).


  == Correlations ==

  === Degree Correlation ===

  The degree correlation histogram is a bidimensional histogram defined as

  [[Equation(\[C(k,k')=\sum_{u,v}A_{uv}[k_u=k][k_v=k']\])]], where [[Equation($\mathbf{A}$)]] is the adjacenty matrix. It is obtainable with the "{{{--degree-correlation-histogram}}}" option, which takes three parameters separated by "|": First degree type ([[Equation($k_u$)]]), second degree type ([[Equation($k_v$)]]) and a filename. The degree types can be `in-degree`, `out-degree` and `total-degree`. It can also be the name of any vertex scalar property available.

  Example:

  {{{
  $ graph-tool --load example.xml --degree-correlation="in-degree|out-degree|deg-corr"
  $ cat deg-corr
  0.0     1.0     1
  0.0     2.0     1
  1.0     1.0     3
  2.0     1.0     3
  }}}

  It is also possible to obtain the correlation in an aternative fashion, which a lot of times is more convenient, and that is the average nearest neighbours degree, given by

  [[Equation(\[ \bar{k}(k)=\frac{\sum_{u,v}A_{uv}k_v[k_u=k]}{\sum_{u,v}A_{uv}[k_u=k]}\])]].

  It is obtainable with the "`--average-nearest-neighbours-degree`" option, which takes four parameters separated by "|": type of neighbours, degree type of the origin vertex, degree type of the neighbours and a filename. Neighbour types can be "`all`", "`in`" and "`out`", for all, in and out-neighbours respectively. Origin and neighbour degree type can be "`in-degree`", "`out-degree`" and "`total-degree`", as well as the name of any vertex scalar property available.

  Example:

  {{{
  $ graph-tool --load example.xml --average-nearest-neighbours-degree="all|total-degree|in-degree|deg-corr"
  $ cat deg-corr
  1.0     1.5     0.5
  2.0     1.5     0.5
  3.0     1.41666666667   0.228908256511
  }}}

  The third column above is the standard deviation of the average in the second column.

  === Edge Correlation ===

  When edges have scalar properties, it is possible to generate a 3-dimensional correlation histogram defined as:

  [[Equation(\[ P(k,m,k')=\sum_{e}[k_{s(e)}=k][k_{t(e)}=k'][p(e)=m]}\])]], where [[Equation($e$)]] are the edges of the graph, [[Equation(\[s(e)\])]] and [[Equation(\[t(e)\])]] are the source and target vertex of edge [[Equation($e$)]], and [[Equation(\[p(e)\])]] is some property of the edge.

  This can be obtained with the "`--edge-degree-correlation-histogram`" option which takes four arguments separated by "|": Source degree type, edge property and target degree type. The source and target degree types can be "`in-degree`", "`out-degree`" and "`total-degree`", as well as the name of any vertex scalar property available.

  Example:
  {{{
  $ graph-tool --load example.xml --edge-degree-correlation-histogram="in-degree|weight|out-degree|edge-corr"
  $ cat edge-corr
  0.0     0.2     2.0     1
  0.0     1.2     1.0     1
  1.0     2.0     1.0     1
  1.0     5.5     1.0     1
  1.0     10.1    1.0     1
  2.0     0.1     1.0     1
  2.0     0.5     1.0     1
  2.0     0.8     1.0     1
  }}}

  === Assortativity Coefficient ===

  The assortativity coefficient tells in a concise fashion how vertices of different types are preferencially connected amongst themselves, and is defined by

  [[Equation(\[r = \frac{\sum_i e_{ii} - \sum_i a_i b_i}{1-\sum_i a_i b_i}\])]] where [[Equation(\[a_i=\sum_je_{ij}\])]] and [[Equation(\[b_j=\sum_ie_{ij}\])]], and [[Equation($e_{ij}$)]] is the fraction of edges from a vertex of type $i$ to a vertex of type $j$.

  It is obtained by the option "`--assortativity-coefficient`", which takes two arguments: the property used to identify different types and a file name, separated by "|". The property may be any scalar vertex property in the graph, as well a "`in-degree`", "`out-degree`" and "`total-degree`".

  Example:

  {{{
  $ graph-tool --load example.xml --assortativity-coefficient="total-degree|-"
  assortativity coefficient:      -0.230769230769
  }}}

  == Clustering ==

      --local-clustering-coefficient=FILE                                       get the local clustering coefficient
      --local-clustering-coefficient-histogram=DEGREE_TYPE|FILE                 get the local clustering coefficient histogram
      --set-local-clustering-to-property=PROPERTY                               set the local clustering coefficient to vertex property
      --global-clustering-coefficient=FILE                                      get the global clustering coefficient


  == Layout ==
      --compute-spring-block-layout=ITERATIONS[|SEED]                           compute the spring block layout
      --compute-gursoy-atun-layout=ITERATIONS[|SEED]                            compute the Gursoy-Atun layout


  == Random Graph Generation ==
      --correlated-configurational-model=OPTIONS                                generate graph using the configurational model with arbitrary degree
                                                                                correlations. Options are: N, pjk, pjk_ceil, pjk_m, inv_pjk_ceil, corr,
                                                                                corr_ceil, corr_m, inv_corr_ceil, undirected, directed, progress, seed. See
                                                                                documentation for details.

  == Graph History ==

      --history=INIT|CONDITION|STEP                                             compute graph history
      --history-rate=TIME  


name: WikiStart
author: count0
ipnr: 201.51.130.17
text:
  = What is graph-tool? =
  [[Image(WikiStartAttachments:small.png, class=floatright, nolink)]] 

  graph-tool is a program to help with statistical analysis of [http://en.wikipedia.org/wiki/Graph_%28mathematics%29 graphs]. Its feature set includes:

   * support for directed and undirected graphs
   * support for arbitrary vertex or edge properties
   * generic filtering of edges and vertices
   * several statistical measurements:
     * degree (or scalar property) histogram
     * vertex-vertex degree (or scalar property) correlation
     * average nearest neighbours degree (or scalar property)
     * vertex-edge-vertex correlation
     * clustering coefficients
     * assortativity coefficient
     * average distance
     * component statistics
   * generation of random graphs with arbitrary degree distribution and degree correlation
   * support for [http://graphml.graphdrawing.org/ graphml] and [http://www.graphviz.org/ dot] file formats

  The core algorithms are written in C++, making use of the [http://www.boost.org/libs/graph/doc/ Boost Graph Library], and [http://en.wikipedia.org/wiki/Template_metaprogramming template metaprogramming] techniques, with performace in mind. The command line interface and other outlying code are written in [http://www.python.org python].

  See GraphToolGuide for instructions and examples of how to use the program.

  graph-tool was written by [https://forked.de/bin/view/Main/TiagoPeixoto Tiago de Paula Peixoto] and is [http://www.gnu.org/philosophy/free-sw.html free software], released under the [http://www.gnu.org/copyleft/gpl.html GPL].


name: GraphToolGuide
author: anonymous
ipnr: 201.51.130.17
text:
  = graph-tool Guide =

  [[PageOutline]]

  == Invoking ==

  graph-tool is invoked by typing {{{graph-tool}}} in the command line. For a quick summary of options type
  {{{
  graph-tool --help
  }}}


  == Loading and saving files ==

  Files can be loaded with the "{{{--load}}}" option. Graph tool supports both [http://graphml.graphdrawing.org/ graphml] and [http://www.graphviz.org/ dot] formats. The formats are identified by the file name extension: files ending in {{{.xml}}} are considered graphml files, and files ending in {{{.dot}}} are considered dot files. Files can also end in {{{.gz}}} or {{{.bz2}}} to indicate compression, such as {{{.xml.gz}}} or {{{.dot.bz2}}}. Files can be saved with the "{{{--save}}}" command, and the file name specifications are the same.

  === File format description ===

  Consider the following directed graph, with one floating point edge property (which will be called "weight"):
  {{{
  #!html
  <div style="text-align: center;">
  }}}
  {{{
  #!graphviz
  digraph G {
  start="12";
  1->2 [label = "  1.2  ", len=0.6];
  2->3 [label = "  0.8  ", len=0.6];
  3->7 [label = "  0.5", len=0.6];
  4->5 [label = "  0.2  ", len=0.6];
  5->6 [label = "  10.1  ", len=0.6];
  5->3 [label = "  5.5", len=0.6];
  6->7 [label = "  2.0", len=0.6];
  7->2 [label = "  0.1", len=0.6];
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  It can be defined in dot format as such:

  {{{
  digraph G {
  1->2 [weight = "1.2"];
  2->3 [weight = "0.8"];
  3->7 [weight = "0.5"];
  4->5 [weight = "0.2"];
  5->6 [weight = "10.1"];
  5->3 [weight = "5.5"];
  6->7 [weight = "2.0"];
  7->2 [weight = "0.1"];
  }
  }}}

  and in graphml format as such:

  {{{
  #!xml
  <?xml version="1.0" encoding="UTF-8"?>
  <graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://graphml.graphdrawing.org/xmlns/1.0/graphml.xsd">
    <key id="d1" for="edge" attr.name="weight" attr.type="double"/>
    <graph id="G" edgedefault="directed">
      <node id="n0"/>
      <node id="n1"/>
      <node id="n2"/>
      <node id="n3"/>
      <node id="n4"/>
      <node id="n5"/>
      <node id="n6"/>
      <edge id="e0" source="n0" target="n1">
        <data key="d1">1.2</data>
      </edge>
      <edge id="e1" source="n1" target="n2">
        <data key="d1">0.8</data>
      </edge>
      <edge id="e2" source="n2" target="n6">
        <data key="d1">0.5</data>
      </edge>
      <edge id="e3" source="n3" target="n4">
        <data key="d1">0.2</data>
      </edge>
      <edge id="e4" source="n4" target="n5">
        <data key="d1">10.1</data>
      </edge>
      <edge id="e5" source="n4" target="n2">
        <data key="d1">5.5</data>
      </edge>
      <edge id="e6" source="n5" target="n6">
        <data key="d1">2.0</data>
      </edge>
      <edge id="e7" source="n6" target="n1">
        <data key="d1">0.1</data>
      </edge>
    </graph>
  </graphml>
  }}}

  Vertex properties are done in an analogous manner. There's no limit on the number of properties the graph can have. 

  Graphs can also be undirected, and are loaded by specifiyng the option "{{{--undirected}}}" before "{{{--load}}}". Here's an example:

  {{{
  #!html
  <div style="text-align: center;">
  }}}
  {{{
  #!graphviz
  graph G {
  start="12";
  1--2 
  2--3 
  3--7 
  4--5 
  5--6 
  5--3 
  6--7 
  7--2 
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  In dot format:

  {{{
  graph G {
  1--2 
  2--3 
  3--7 
  4--5 
  5--6 
  5--3 
  6--7 
  7--2 
  }
  }}}

  and in graphml format:

  {{{
  #!xml
  <?xml version="1.0" encoding="UTF-8"?>
  <graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://graphml.graphdrawing.org/xmlns/1.0/graphml.xsd">
    <graph id="G" edgedefault="undirected">
      <node id="n0"/>
      <node id="n1"/>
      <node id="n2"/>
      <node id="n3"/>
      <node id="n4"/>
      <node id="n5"/>
      <node id="n6"/>
      <edge id="e0" source="n0" target="n1"/>
      <edge id="e1" source="n1" target="n2"/>
      <edge id="e2" source="n2" target="n6"/>
      <edge id="e3" source="n3" target="n4"/>
      <edge id="e4" source="n4" target="n5"/>
      <edge id="e5" source="n4" target="n2"/>
      <edge id="e6" source="n5" target="n6"/>
      <edge id="e7" source="n6" target="n1"/>
    </graph>
  </graphml>
  }}}

  {{{
  #!html
  <div class="note">
  }}}
  ==== Which format to use? ====

  You can of course use either format, but in general graphml is preferred. It provides for a tighter definition of the graph, and since graph-tool understants the parse info attributes of the graph, you can speed up the loading of the file and reduce memory usage by using the following in your graph definition:

  {{{
  #!xml
  ...
   <graph id="G" edgedefault="directed" parse.nodeids="canonical" parse.edgeids="canonical" parse.order="nodesfirst">
  ...
  }}}

  This says that all vertices and edges are named "n0","n1", ..., "nN-1", and  "e0", "e1", ..., "eE-1", respectively. And also it says that the vertex list comes before the edge list. You're not forced to define your graph this way, but it does improve performace for large graphs.

  {{{
  #!html
  </div>
  }}}

  ----

  == Basic Statistics ==

  The two most basic properties of the graph are the number of vertex and edges, which is obtainable through the "{{{--number-of-vertices}}}" and "{{{--number-of-edges}}}" options. Suppose the first graph in [[ref(File Format Description)]] is saved under {{{example.xml}}}. We can then get the number of vertices and edges by typing:

  {{{
  $ graph-tool --load example.xml --number-of-vertices=- --number-of-edges=-
  number of vertices:     7
  number of edges:        8
  }}}

  The "-" parameter to the options is necessary to output the results in the terminal. Otherwise it writes it to the file given in the parameter.

  === Degree Histogram ===

  The degree histogram can be obtained by the "{{{--degree-histogram}}}" option. It requires two parameters, separated by "|": degree type and file name. Degree type can be any of "in-degree", "out-degree", "total-degree" and __any vertex scalar property__. The file name is the file the histogram is written to, or "-" to be written to the terminal. Files may be terminated with {{{.gz}}} or {{{.bz2}}} for compression. Example:

  {{{
  $ graph-tool --load example.xml --degree-histogram="total-degree|deg-dist"
  $ cat deg-dist
  1.0     2
  2.0     1
  3.0     4
  }}}

  For directed graphs, it is also possible to get the combined (in,out)-degree histogram with the "{{{--combined-degree-histogram}}}" option:

  {{{
  $ graph-tool --load example.xml --combined-degree-histogram="deg-dist"
  $ cat deg-dist
  0.0     1.0     2
  1.0     1.0     1
  1.0     2.0     1
  2.0     1.0     3
  }}}

  === Average Distance ===

  The average vertex-vertex distance can be obtained with the "{{{--average-distance}}}" option:

  {{{
  $ graph-tool --load example.xml --average-distance=-
  average distance:       0.714285714286
  }}}

  For directed and/or disconnected graphs, it may be better to use the average harmonic distance defined as:

  [[Equation(\[d_h = \left[\sum_{v,u}\frac{1}{d_{uv}}\right]^{-1}\])]], where [[Equation($d_{uv}$)]] is the regular graph distance between [[Equation($u$)]] and [[Equation($v$)]], which here is taken to be infinity when there's no path between those two vertices.

  Example:

  {{{
  $ graph-tool --load example.xml --average-harmonic-distance=-
  average harmonic distance:      4.1226993865
  }}}

  === Component Size Histogram === 

  Component size statistics can be obtained by the "{{{component-size-histogram}}}" option. Consider the following graph:

  {{{
  #!html
  <div style="text-align: center;">
  }}}
  {{{
  #!graphviz
  digraph G {
  1->2
  2->3
  3->1

  4->5

  6->7
  7->8
  8->9
  9->10
  10->11
  11->6
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  Defined by the following dot file (henceforth referred to as {{{multi-comp.dot}}}):
  {{{
  digraph G {
  1->2
  2->3
  3->1

  4->5

  6->7
  7->8
  8->9
  9->10
  10->11
  11->6
  }
  }}}

  When called with a directed graph, the program returns the '''strong component''' statistics:

  {{{
  $graph-tool --load multi-comp.dot --component-size-histogram="comp-hist"
  $ cat comp-hist
  1.0     2
  3.0     1
  6.0     1
  }}}

  To see the component statistics if the graph were undirected, we just have to treat it as such:

  {{{
  $ graph-tool --load multi-comp.dot --undirected --component-size-histogram="comp-hist"
  $ cat comp-hist
  2.0     1
  3.0     1
  6.0     1
  }}}


  == Filtering ==

  Graphs can be filtered in several ways. None of them actually modify the internally kept graph, and are therefore of complexity O(1).

  === Directedness ===

  Internally, all graphs in graph-tool are directed graphs. But it is possible to treat them easily as directed with the "{{{--undirected}}}" option. All options after that will operate on a undirected filter of the internal directed graph. The "{{{--directed}}}" option reverts back to the default mode.

  === Edge direction ===

  Directed graphs can have the the edge direction reversed with the "{{{--reverse}}}" option. A second "{{{--reverse}}}" reverts back to the original state.

  === Filtering of vertices or edges ===

  ==== Range filtering ====

  Edges and vertices can be filtered out of the graph based on their properties. The most basic and fastest way of filtering is called "range filtering" and filters out vertices with a scalar property which lays outside a given range. The filtering is controlled with the "{{{--vertex-range-filter}}}" and "{{{--edge-range-filter}}}" options, which takes two parameters separated by "|": the property to be used as filter and the range (two values separated by space. Here's an example using the graph defined in [[ref(File Format Description)]]:

  {{{
  $ graph-tool --load example.xml --number-of-edges=-
  number of edges:        8
  $ graph-tool --load example.xml --edge-range-filter="weight|0.6 6.0" --number-of-edges=- --save filtered.dot
  number of edges:        4
  }}}

  The file {{{filtered.dot}}} contains (representation on the side):

  {{{
  #!html
  <div style="float: right;">
  }}}
  {{{
  #!graphviz
  digraph G {
  1;
  2;
  3;
  7;
  4;
  5;
  6;
  1->2  [label="1.2"];
  2->3  [label="0.8"];
  5->3  [label="5.5"];
  6->7  [label="2.0"];
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  {{{
  digraph G {
  1;
  2;
  3;
  7;
  4;
  5;
  6;
  1->2  [weight="1.2"];
  2->3  [weight="0.8"];
  5->3  [weight="5.5"];
  6->7  [weight="2"];
  }
  }}}

  ==== Generic Filtering ====

  Graphs can be filtered in a more versatile way than above (at a performance cost). This is done through the "{{{--vertex-filter}}}" and "{{{--edge-filter}}}" options, which take a generic [http://www.python.org python] expression as a parameter, and if it evaluates to {{{True}}} the vertex or edge is removed.

  Example:

  {{{
  #!html
  <div style="float: right;">
  }}}
  {{{
  #!graphviz
  digraph G {
  0;
  1;
  2;
  3;
  4;
  1->4  [label="0.5"];
  2->3  [label="10.1"];
  2->1  [label="5.5"];
  3->4  [label="2"];
  4->0  [label="0.1"];
  }
  }}}
  {{{
  #!html
  </div>
  }}}
  {{{
  $ graph-tool --load example.xml --edge-filter="weight==0.8" --vertex-filter="in_degree==0" --save filtered.dot
  $ cat filtered.dot
  digraph G {
  0;
  1;
  2;
  3;
  4;
  1->4  [weight="0.5"];
  2->3  [weight="10.1"];
  2->1  [weight="5.5"];
  3->4  [weight="2"];
  4->0  [weight="0.1"];
  }
  }}}

  {{{
  #!html
  <div class="note">
  }}}
  ===== Performace note =====
  When generic filtering is turned on, algorithms in general will run much slower, since the python interpreter will be involved in the computations. Therefore, if some expensive computation is being considered, it is in general better to save the graph to a file after the filtering, and load it as unfiltered to perform the computation.
  {{{
  #!html
  </div>
  }}}

  ==== Removing filtering ====

  The graph can be returned to its unfiltered state by calling "{{{--reset-vertex-filter}}}" and "{{{--reset-edge-filter}}}".

  == Graph Modifications ==

  There's a couple of options which change the internally kept graph.

  === Removing Properties ===

  Vertex and edge properties can be removed from the graph with the options "{{{--remove-vertex-property}}}" and "{{{--remove-edge-property}}}", which take the name of the property to be removed as parameter.

  === Vertex and Edge Indices ===

  Vertices and Edges are identified internally by indices. Those can be inserted as properties with the options "{{{--insert-vertex-index-property}}}" and "{{{--insert-edge-index-property}}}", which take as argument the name by which the property will be called.

  === Removal of Parallel Edges ===

  Parallel edges (i.e. edges that share the same source and target) can be removed from the graph with the option "{{{--remove-parallel-edges}}}", so that only one of the parallel edges ramain (it is undefined which one).


  == Correlations ==

  === Degree Correlation ===

  The degree correlation histogram is a bidimensional histogram defined as

  [[Equation(\[C(k,k')=\sum_{u,v}A_{uv}[k_u=k][k_v=k']\])]], where [[Equation($\mathbf{A}$)]] is the adjacenty matrix. It is obtainable with the "{{{--degree-correlation-histogram}}}" option, which takes three parameters separated by "|": First degree type ([[Equation($k_u$)]]), second degree type ([[Equation($k_v$)]]) and a filename. The degree types can be `in-degree`, `out-degree` and `total-degree`. It can also be the name of any vertex scalar property available.

  Example:

  {{{
  $ graph-tool --load example.xml --degree-correlation="in-degree|out-degree|deg-corr"
  $ cat deg-corr
  0.0     1.0     1
  0.0     2.0     1
  1.0     1.0     3
  2.0     1.0     3
  }}}

  It is also possible to obtain the correlation in an aternative fashion, which a lot of times is more convenient, and that is the average nearest neighbours degree, given by

  [[Equation(\[ \bar{k}(k)=\frac{\sum_{u,v}A_{uv}k_v[k_u=k]}{\sum_{u,v}A_{uv}[k_u=k]}\])]].

  It is obtainable with the "`--average-nearest-neighbours-degree`" option, which takes four parameters separated by "|": type of neighbours, degree type of the origin vertex, degree type of the neighbours and a filename. Neighbour types can be "`all`", "`in`" and "`out`", for all, in and out-neighbours respectively. Origin and neighbour degree type can be "`in-degree`", "`out-degree`" and "`total-degree`", as well as the name of any vertex scalar property available.

  Example:

  {{{
  $ graph-tool --load example.xml --average-nearest-neighbours-degree="all|total-degree|in-degree|deg-corr"
  $ cat deg-corr
  1.0     1.5     0.5
  2.0     1.5     0.5
  3.0     1.41666666667   0.228908256511
  }}}

  The third column above is the standard deviation of the average in the second column.

  === Edge Correlation ===

  When edges have scalar properties, it is possible to generate a 3-dimensional correlation histogram defined as:

  [[Equation(\[ P(k,m,k')=\sum_{e}[k_{s(e)}=k][k_{t(e)}=k'][p(e)=m]}\])]], where [[Equation($e$)]] are the edges of the graph, [[Equation(\[s(e)\])]] and [[Equation(\[t(e)\])]] are the source and target vertex of edge [[Equation($e$)]], and [[Equation(\[p(e)\])]] is some property of the edge.

  This can be obtained with the "`--edge-degree-correlation-histogram`" option which takes four arguments separated by "|": Source degree type, edge property and target degree type. The source and target degree types can be "`in-degree`", "`out-degree`" and "`total-degree`", as well as the name of any vertex scalar property available.

  Example:
  {{{
  $ graph-tool --load example.xml --edge-degree-correlation-histogram="in-degree|weight|out-degree|edge-corr"
  $ cat edge-corr
  0.0     0.2     2.0     1
  0.0     1.2     1.0     1
  1.0     2.0     1.0     1
  1.0     5.5     1.0     1
  1.0     10.1    1.0     1
  2.0     0.1     1.0     1
  2.0     0.5     1.0     1
  2.0     0.8     1.0     1
  }}}

  === Assortativity Coefficient ===

  The assortativity coefficient tells in a concise fashion how vertices of different types are preferencially connected amongst themselves, and is defined by

  [[Equation(\[r = \frac{\sum_i e_{ii} - \sum_i a_i b_i}{1-\sum_i a_i b_i}\])]] where [[Equation(\[a_i=\sum_je_{ij}\])]] and [[Equation(\[b_j=\sum_ie_{ij}\])]], and [[Equation($e_{ij}$)]] is the fraction of edges from a vertex of type [[Equation($i$)]] to a vertex of type [[Equation($j$)]].

  It is obtained by the option "`--assortativity-coefficient`", which takes two arguments: the property used to identify different types and a file name, separated by "|". The property may be any scalar vertex property in the graph, as well a "`in-degree`", "`out-degree`" and "`total-degree`".

  Example:

  {{{
  $ graph-tool --load example.xml --assortativity-coefficient="total-degree|-"
  assortativity coefficient:      -0.230769230769
  }}}

  == Clustering ==

  === local clustering ===

  The local (vertex) clustering coefficient is defined on an undirected graph as 

  [[Equation(\[C^{(1)}_v = \frac{k}{N_c}\])]], where [[Equation($k$)]] is the degree of the vertex, and 
      --local-clustering-coefficient=FILE                                       get the local clustering coefficient
      --local-clustering-coefficient-histogram=DEGREE_TYPE|FILE                 get the local clustering coefficient histogram
      --set-local-clustering-to-property=PROPERTY                               set the local clustering coefficient to vertex property
      --global-clustering-coefficient=FILE                                      get the global clustering coefficient


  == Layout ==
      --compute-spring-block-layout=ITERATIONS[|SEED]                           compute the spring block layout
      --compute-gursoy-atun-layout=ITERATIONS[|SEED]                            compute the Gursoy-Atun layout


  == Random Graph Generation ==
      --correlated-configurational-model=OPTIONS                                generate graph using the configurational model with arbitrary degree
                                                                                correlations. Options are: N, pjk, pjk_ceil, pjk_m, inv_pjk_ceil, corr,
                                                                                corr_ceil, corr_m, inv_corr_ceil, undirected, directed, progress, seed. See
                                                                                documentation for details.

  == Graph History ==

      --history=INIT|CONDITION|STEP                                             compute graph history
      --history-rate=TIME  


name: GraphToolGuide
author: count0
ipnr: 201.51.130.17
text:
  = graph-tool Guide =

  [[PageOutline]]

  == Invoking ==

  graph-tool is invoked by typing {{{graph-tool}}} in the command line. For a quick summary of options type
  {{{
  graph-tool --help
  }}}


  == Loading and saving files ==

  Files can be loaded with the "{{{--load}}}" option. Graph tool supports both [http://graphml.graphdrawing.org/ graphml] and [http://www.graphviz.org/ dot] formats. The formats are identified by the file name extension: files ending in {{{.xml}}} are considered graphml files, and files ending in {{{.dot}}} are considered dot files. Files can also end in {{{.gz}}} or {{{.bz2}}} to indicate compression, such as {{{.xml.gz}}} or {{{.dot.bz2}}}. Files can be saved with the "{{{--save}}}" command, and the file name specifications are the same.

  === File format description ===

  Consider the following directed graph, with one floating point edge property (which will be called "weight"):
  {{{
  #!html
  <div style="text-align: center;">
  }}}
  {{{
  #!graphviz
  digraph G {
  start="12";
  1->2 [label = "  1.2  ", len=0.6];
  2->3 [label = "  0.8  ", len=0.6];
  3->7 [label = "  0.5", len=0.6];
  4->5 [label = "  0.2  ", len=0.6];
  5->6 [label = "  10.1  ", len=0.6];
  5->3 [label = "  5.5", len=0.6];
  6->7 [label = "  2.0", len=0.6];
  7->2 [label = "  0.1", len=0.6];
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  It can be defined in dot format as such:

  {{{
  digraph G {
  1->2 [weight = "1.2"];
  2->3 [weight = "0.8"];
  3->7 [weight = "0.5"];
  4->5 [weight = "0.2"];
  5->6 [weight = "10.1"];
  5->3 [weight = "5.5"];
  6->7 [weight = "2.0"];
  7->2 [weight = "0.1"];
  }
  }}}

  and in graphml format as such:

  {{{
  #!xml
  <?xml version="1.0" encoding="UTF-8"?>
  <graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://graphml.graphdrawing.org/xmlns/1.0/graphml.xsd">
    <key id="d1" for="edge" attr.name="weight" attr.type="double"/>
    <graph id="G" edgedefault="directed">
      <node id="n0"/>
      <node id="n1"/>
      <node id="n2"/>
      <node id="n3"/>
      <node id="n4"/>
      <node id="n5"/>
      <node id="n6"/>
      <edge id="e0" source="n0" target="n1">
        <data key="d1">1.2</data>
      </edge>
      <edge id="e1" source="n1" target="n2">
        <data key="d1">0.8</data>
      </edge>
      <edge id="e2" source="n2" target="n6">
        <data key="d1">0.5</data>
      </edge>
      <edge id="e3" source="n3" target="n4">
        <data key="d1">0.2</data>
      </edge>
      <edge id="e4" source="n4" target="n5">
        <data key="d1">10.1</data>
      </edge>
      <edge id="e5" source="n4" target="n2">
        <data key="d1">5.5</data>
      </edge>
      <edge id="e6" source="n5" target="n6">
        <data key="d1">2.0</data>
      </edge>
      <edge id="e7" source="n6" target="n1">
        <data key="d1">0.1</data>
      </edge>
    </graph>
  </graphml>
  }}}

  Vertex properties are done in an analogous manner. There's no limit on the number of properties the graph can have. 

  Graphs can also be undirected, and are loaded by specifiyng the option "{{{--undirected}}}" before "{{{--load}}}". Here's an example:

  {{{
  #!html
  <div style="text-align: center;">
  }}}
  {{{
  #!graphviz
  graph G {
  start="12";
  1--2 
  2--3 
  3--7 
  4--5 
  5--6 
  5--3 
  6--7 
  7--2 
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  In dot format:

  {{{
  graph G {
  1--2 
  2--3 
  3--7 
  4--5 
  5--6 
  5--3 
  6--7 
  7--2 
  }
  }}}

  and in graphml format:

  {{{
  #!xml
  <?xml version="1.0" encoding="UTF-8"?>
  <graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://graphml.graphdrawing.org/xmlns/1.0/graphml.xsd">
    <graph id="G" edgedefault="undirected">
      <node id="n0"/>
      <node id="n1"/>
      <node id="n2"/>
      <node id="n3"/>
      <node id="n4"/>
      <node id="n5"/>
      <node id="n6"/>
      <edge id="e0" source="n0" target="n1"/>
      <edge id="e1" source="n1" target="n2"/>
      <edge id="e2" source="n2" target="n6"/>
      <edge id="e3" source="n3" target="n4"/>
      <edge id="e4" source="n4" target="n5"/>
      <edge id="e5" source="n4" target="n2"/>
      <edge id="e6" source="n5" target="n6"/>
      <edge id="e7" source="n6" target="n1"/>
    </graph>
  </graphml>
  }}}

  {{{
  #!html
  <div class="note">
  }}}
  ==== Which format to use? ====

  You can of course use either format, but in general graphml is preferred. It provides for a tighter definition of the graph, and since graph-tool understants the parse info attributes of the graph, you can speed up the loading of the file and reduce memory usage by using the following in your graph definition:

  {{{
  #!xml
  ...
   <graph id="G" edgedefault="directed" parse.nodeids="canonical" parse.edgeids="canonical" parse.order="nodesfirst">
  ...
  }}}

  This says that all vertices and edges are named "n0","n1", ..., "nN-1", and  "e0", "e1", ..., "eE-1", respectively. And also it says that the vertex list comes before the edge list. You're not forced to define your graph this way, but it does improve performace for large graphs.

  {{{
  #!html
  </div>
  }}}

  ----

  == Basic Statistics ==

  The two most basic properties of the graph are the number of vertex and edges, which is obtainable through the "{{{--number-of-vertices}}}" and "{{{--number-of-edges}}}" options. Suppose the first graph in [[ref(File Format Description)]] is saved under {{{example.xml}}}. We can then get the number of vertices and edges by typing:

  {{{
  $ graph-tool --load example.xml --number-of-vertices=- --number-of-edges=-
  number of vertices:     7
  number of edges:        8
  }}}

  The "-" parameter to the options is necessary to output the results in the terminal. Otherwise it writes it to the file given in the parameter.

  === Degree Histogram ===

  The degree histogram can be obtained by the "{{{--degree-histogram}}}" option. It requires two parameters, separated by "|": degree type and file name. Degree type can be any of "in-degree", "out-degree", "total-degree" and __any vertex scalar property__. The file name is the file the histogram is written to, or "-" to be written to the terminal. Files may be terminated with {{{.gz}}} or {{{.bz2}}} for compression. Example:

  {{{
  $ graph-tool --load example.xml --degree-histogram="total-degree|deg-dist"
  $ cat deg-dist
  1.0     2
  2.0     1
  3.0     4
  }}}

  For directed graphs, it is also possible to get the combined (in,out)-degree histogram with the "{{{--combined-degree-histogram}}}" option:

  {{{
  $ graph-tool --load example.xml --combined-degree-histogram="deg-dist"
  $ cat deg-dist
  0.0     1.0     2
  1.0     1.0     1
  1.0     2.0     1
  2.0     1.0     3
  }}}

  === Average Distance ===

  The average vertex-vertex distance can be obtained with the "{{{--average-distance}}}" option:

  {{{
  $ graph-tool --load example.xml --average-distance=-
  average distance:       0.714285714286
  }}}

  For directed and/or disconnected graphs, it may be better to use the average harmonic distance defined as:

  [[Equation(\[d_h = \left[\sum_{v,u}\frac{1}{d_{uv}}\right]^{-1}\])]], where [[Equation($d_{uv}$)]] is the regular graph distance between [[Equation($u$)]] and [[Equation($v$)]], which here is taken to be infinity when there's no path between those two vertices.

  Example:

  {{{
  $ graph-tool --load example.xml --average-harmonic-distance=-
  average harmonic distance:      4.1226993865
  }}}

  === Component Size Histogram === 

  Component size statistics can be obtained by the "{{{component-size-histogram}}}" option. Consider the following graph:

  {{{
  #!html
  <div style="text-align: center;">
  }}}
  {{{
  #!graphviz
  digraph G {
  1->2
  2->3
  3->1

  4->5

  6->7
  7->8
  8->9
  9->10
  10->11
  11->6
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  Defined by the following dot file (henceforth referred to as {{{multi-comp.dot}}}):
  {{{
  digraph G {
  1->2
  2->3
  3->1

  4->5

  6->7
  7->8
  8->9
  9->10
  10->11
  11->6
  }
  }}}

  When called with a directed graph, the program returns the '''strong component''' statistics:

  {{{
  $graph-tool --load multi-comp.dot --component-size-histogram="comp-hist"
  $ cat comp-hist
  1.0     2
  3.0     1
  6.0     1
  }}}

  To see the component statistics if the graph were undirected, we just have to treat it as such:

  {{{
  $ graph-tool --load multi-comp.dot --undirected --component-size-histogram="comp-hist"
  $ cat comp-hist
  2.0     1
  3.0     1
  6.0     1
  }}}


  == Filtering ==

  Graphs can be filtered in several ways. None of them actually modify the internally kept graph, and are therefore of complexity O(1).

  === Directedness ===

  Internally, all graphs in graph-tool are directed graphs. But it is possible to treat them easily as directed with the "{{{--undirected}}}" option. All options after that will operate on a undirected filter of the internal directed graph. The "{{{--directed}}}" option reverts back to the default mode.

  === Edge direction ===

  Directed graphs can have the the edge direction reversed with the "{{{--reverse}}}" option. A second "{{{--reverse}}}" reverts back to the original state.

  === Filtering of vertices or edges ===

  ==== Range filtering ====

  Edges and vertices can be filtered out of the graph based on their properties. The most basic and fastest way of filtering is called "range filtering" and filters out vertices with a scalar property which lays outside a given range. The filtering is controlled with the "{{{--vertex-range-filter}}}" and "{{{--edge-range-filter}}}" options, which takes two parameters separated by "|": the property to be used as filter and the range (two values separated by space. Here's an example using the graph defined in [[ref(File Format Description)]]:

  {{{
  $ graph-tool --load example.xml --number-of-edges=-
  number of edges:        8
  $ graph-tool --load example.xml --edge-range-filter="weight|0.6 6.0" --number-of-edges=- --save filtered.dot
  number of edges:        4
  }}}

  The file {{{filtered.dot}}} contains (representation on the side):

  {{{
  #!html
  <div style="float: right;">
  }}}
  {{{
  #!graphviz
  digraph G {
  1;
  2;
  3;
  7;
  4;
  5;
  6;
  1->2  [label="1.2"];
  2->3  [label="0.8"];
  5->3  [label="5.5"];
  6->7  [label="2.0"];
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  {{{
  digraph G {
  1;
  2;
  3;
  7;
  4;
  5;
  6;
  1->2  [weight="1.2"];
  2->3  [weight="0.8"];
  5->3  [weight="5.5"];
  6->7  [weight="2"];
  }
  }}}

  ==== Generic Filtering ====

  Graphs can be filtered in a more versatile way than above (at a performance cost). This is done through the "{{{--vertex-filter}}}" and "{{{--edge-filter}}}" options, which take a generic [http://www.python.org python] expression as a parameter, and if it evaluates to {{{True}}} the vertex or edge is removed.

  Example:

  {{{
  #!html
  <div style="float: right;">
  }}}
  {{{
  #!graphviz
  digraph G {
  0;
  1;
  2;
  3;
  4;
  1->4  [label="0.5"];
  2->3  [label="10.1"];
  2->1  [label="5.5"];
  3->4  [label="2"];
  4->0  [label="0.1"];
  }
  }}}
  {{{
  #!html
  </div>
  }}}
  {{{
  $ graph-tool --load example.xml --edge-filter="weight==0.8" --vertex-filter="in_degree==0" --save filtered.dot
  $ cat filtered.dot
  digraph G {
  0;
  1;
  2;
  3;
  4;
  1->4  [weight="0.5"];
  2->3  [weight="10.1"];
  2->1  [weight="5.5"];
  3->4  [weight="2"];
  4->0  [weight="0.1"];
  }
  }}}

  {{{
  #!html
  <div class="note">
  }}}
  ===== Performace note =====
  When generic filtering is turned on, algorithms in general will run much slower, since the python interpreter will be involved in the computations. Therefore, if some expensive computation is being considered, it is in general better to save the graph to a file after the filtering, and load it as unfiltered to perform the computation.
  {{{
  #!html
  </div>
  }}}

  ==== Removing filtering ====

  The graph can be returned to its unfiltered state by calling "{{{--reset-vertex-filter}}}" and "{{{--reset-edge-filter}}}".

  == Graph Modifications ==

  There's a couple of options which change the internally kept graph.

  === Removing Properties ===

  Vertex and edge properties can be removed from the graph with the options "{{{--remove-vertex-property}}}" and "{{{--remove-edge-property}}}", which take the name of the property to be removed as parameter.

  === Vertex and Edge Indices ===

  Vertices and Edges are identified internally by indices. Those can be inserted as properties with the options "{{{--insert-vertex-index-property}}}" and "{{{--insert-edge-index-property}}}", which take as argument the name by which the property will be called.

  === Removal of Parallel Edges ===

  Parallel edges (i.e. edges that share the same source and target) can be removed from the graph with the option "{{{--remove-parallel-edges}}}", so that only one of the parallel edges ramain (it is undefined which one).


  == Correlations ==

  === Degree Correlation ===

  The degree correlation histogram is a bidimensional histogram defined as

  [[Equation(\[C(k,k')=\sum_{u,v}A_{uv}[k_u=k][k_v=k']\])]], where [[Equation($\mathbf{A}$)]] is the adjacenty matrix. It is obtainable with the "{{{--degree-correlation-histogram}}}" option, which takes three parameters separated by "|": First degree type ([[Equation($k_u$)]]), second degree type ([[Equation($k_v$)]]) and a filename. The degree types can be `in-degree`, `out-degree` and `total-degree`. It can also be the name of any vertex scalar property available.

  Example:

  {{{
  $ graph-tool --load example.xml --degree-correlation="in-degree|out-degree|deg-corr"
  $ cat deg-corr
  0.0     1.0     1
  0.0     2.0     1
  1.0     1.0     3
  2.0     1.0     3
  }}}

  It is also possible to obtain the correlation in an aternative fashion, which a lot of times is more convenient, and that is the average nearest neighbours degree, given by

  [[Equation(\[ \bar{k}(k)=\frac{\sum_{u,v}A_{uv}k_v[k_u=k]}{\sum_{u,v}A_{uv}[k_u=k]}\])]].

  It is obtainable with the "`--average-nearest-neighbours-degree`" option, which takes four parameters separated by "|": type of neighbours, degree type of the origin vertex, degree type of the neighbours and a filename. Neighbour types can be "`all`", "`in`" and "`out`", for all, in and out-neighbours respectively. Origin and neighbour degree type can be "`in-degree`", "`out-degree`" and "`total-degree`", as well as the name of any vertex scalar property available.

  Example:

  {{{
  $ graph-tool --load example.xml --average-nearest-neighbours-degree="all|total-degree|in-degree|deg-corr"
  $ cat deg-corr
  1.0     1.5     0.5
  2.0     1.5     0.5
  3.0     1.41666666667   0.228908256511
  }}}

  The third column above is the standard deviation of the average in the second column.

  === Edge Correlation ===

  When edges have scalar properties, it is possible to generate a 3-dimensional correlation histogram defined as:

  [[Equation(\[ P(k,m,k')=\sum_{e}[k_{s(e)}=k][k_{t(e)}=k'][p(e)=m]}\])]], where [[Equation($e$)]] are the edges of the graph, [[Equation(\[s(e)\])]] and [[Equation(\[t(e)\])]] are the source and target vertex of edge [[Equation($e$)]], and [[Equation(\[p(e)\])]] is some property of the edge.

  This can be obtained with the "`--edge-degree-correlation-histogram`" option which takes four arguments separated by "|": Source degree type, edge property and target degree type. The source and target degree types can be "`in-degree`", "`out-degree`" and "`total-degree`", as well as the name of any vertex scalar property available.

  Example:
  {{{
  $ graph-tool --load example.xml --edge-degree-correlation-histogram="in-degree|weight|out-degree|edge-corr"
  $ cat edge-corr
  0.0     0.2     2.0     1
  0.0     1.2     1.0     1
  1.0     2.0     1.0     1
  1.0     5.5     1.0     1
  1.0     10.1    1.0     1
  2.0     0.1     1.0     1
  2.0     0.5     1.0     1
  2.0     0.8     1.0     1
  }}}

  === Assortativity Coefficient ===

  The assortativity coefficient tells in a concise fashion how vertices of different types are preferencially connected amongst themselves, and is defined by

  [[Equation(\[r = \frac{\sum_i e_{ii} - \sum_i a_i b_i}{1-\sum_i a_i b_i}\])]] where [[Equation(\[a_i=\sum_je_{ij}\])]] and [[Equation(\[b_j=\sum_ie_{ij}\])]], and [[Equation($e_{ij}$)]] is the fraction of edges from a vertex of type [[Equation($i$)]] to a vertex of type [[Equation($j$)]].

  It is obtained by the option "`--assortativity-coefficient`", which takes two arguments: the property used to identify different types and a file name, separated by "|". The property may be any scalar vertex property in the graph, as well a "`in-degree`", "`out-degree`" and "`total-degree`".

  Example:

  {{{
  $ graph-tool --load example.xml --assortativity-coefficient="total-degree|-"
  assortativity coefficient:      -0.230769230769
  }}}

  == Clustering ==

  === local clustering ===

  The local (vertex) clustering coefficient is defined on an undirected graph as 

  [[Equation(\[C^{(1)}_v = \frac{k(k-1)}{2N_c}\])]], where [[Equation($k$)]] is the degree of the vertex, and $N_c$ is the number of edges between the neighbours of the vertex. This value can be calculated and set to a vertex property with the command "`--set-local-clustering-to-property`", which takes the property name as paramenter. Example:

  {{{
  $ graph-tool --load example.xml --set-local-clustering-to-property=clustering --degree-histogram="clustering|clust"
  $ cat clust
  0.0     4
  0.333333333333  3
  }}}

  As a convenience, graph-tool also calculates the global average of the clustering coefficient [[Equation($\frac{\sum_vC^{(1)})_v}{N}$]], with the option "--local-clustering-coefficient", which takes a file name as a parameter (or "`-`" for standard output). Example:

      --local-clustering-coefficient=FILE                                       get the local clustering coefficient
      --local-clustering-coefficient-histogram=DEGREE_TYPE|FILE                 get the local clustering coefficient histogram
      --set-local-clustering-to-property=PROPERTY                               set the local clustering coefficient to vertex property
      --global-clustering-coefficient=FILE                                      get the global clustering coefficient


  == Layout ==
      --compute-spring-block-layout=ITERATIONS[|SEED]                           compute the spring block layout
      --compute-gursoy-atun-layout=ITERATIONS[|SEED]                            compute the Gursoy-Atun layout


  == Random Graph Generation ==
      --correlated-configurational-model=OPTIONS                                generate graph using the configurational model with arbitrary degree
                                                                                correlations. Options are: N, pjk, pjk_ceil, pjk_m, inv_pjk_ceil, corr,
                                                                                corr_ceil, corr_m, inv_corr_ceil, undirected, directed, progress, seed. See
                                                                                documentation for details.

  == Graph History ==

      --history=INIT|CONDITION|STEP                                             compute graph history
      --history-rate=TIME  


name: GraphToolGuide
author: count0
ipnr: 201.51.252.25
text:
  = graph-tool Guide =

  [[PageOutline]]

  == Invoking ==

  graph-tool is invoked by typing {{{graph-tool}}} in the command line. For a quick summary of options type
  {{{
  graph-tool --help
  }}}


  == Loading and saving files ==

  Files can be loaded with the "{{{--load}}}" option. Graph tool supports both [http://graphml.graphdrawing.org/ graphml] and [http://www.graphviz.org/ dot] formats. The formats are identified by the file name extension: files ending in {{{.xml}}} are considered graphml files, and files ending in {{{.dot}}} are considered dot files. Files can also end in {{{.gz}}} or {{{.bz2}}} to indicate compression, such as {{{.xml.gz}}} or {{{.dot.bz2}}}. Files can be saved with the "{{{--save}}}" command, and the file name specifications are the same.

  === File format description ===

  Consider the following directed graph, with one floating point edge property (which will be called "weight"):
  {{{
  #!html
  <div style="text-align: center;">
  }}}
  {{{
  #!graphviz
  digraph G {
  start="12";
  1->2 [label = "  1.2  ", len=0.6];
  2->3 [label = "  0.8  ", len=0.6];
  3->7 [label = "  0.5", len=0.6];
  4->5 [label = "  0.2  ", len=0.6];
  5->6 [label = "  10.1  ", len=0.6];
  5->3 [label = "  5.5", len=0.6];
  6->7 [label = "  2.0", len=0.6];
  7->2 [label = "  0.1", len=0.6];
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  It can be defined in dot format as such:

  {{{
  digraph G {
  1->2 [weight = "1.2"];
  2->3 [weight = "0.8"];
  3->7 [weight = "0.5"];
  4->5 [weight = "0.2"];
  5->6 [weight = "10.1"];
  5->3 [weight = "5.5"];
  6->7 [weight = "2.0"];
  7->2 [weight = "0.1"];
  }
  }}}

  and in graphml format as such:

  {{{
  #!xml
  <?xml version="1.0" encoding="UTF-8"?>
  <graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://graphml.graphdrawing.org/xmlns/1.0/graphml.xsd">
    <key id="d1" for="edge" attr.name="weight" attr.type="double"/>
    <graph id="G" edgedefault="directed">
      <node id="n0"/>
      <node id="n1"/>
      <node id="n2"/>
      <node id="n3"/>
      <node id="n4"/>
      <node id="n5"/>
      <node id="n6"/>
      <edge id="e0" source="n0" target="n1">
        <data key="d1">1.2</data>
      </edge>
      <edge id="e1" source="n1" target="n2">
        <data key="d1">0.8</data>
      </edge>
      <edge id="e2" source="n2" target="n6">
        <data key="d1">0.5</data>
      </edge>
      <edge id="e3" source="n3" target="n4">
        <data key="d1">0.2</data>
      </edge>
      <edge id="e4" source="n4" target="n5">
        <data key="d1">10.1</data>
      </edge>
      <edge id="e5" source="n4" target="n2">
        <data key="d1">5.5</data>
      </edge>
      <edge id="e6" source="n5" target="n6">
        <data key="d1">2.0</data>
      </edge>
      <edge id="e7" source="n6" target="n1">
        <data key="d1">0.1</data>
      </edge>
    </graph>
  </graphml>
  }}}

  Vertex properties are done in an analogous manner. There's no limit on the number of properties the graph can have. 

  Graphs can also be undirected, and are loaded by specifiyng the option "{{{--undirected}}}" before "{{{--load}}}". Here's an example:

  {{{
  #!html
  <div style="text-align: center;">
  }}}
  {{{
  #!graphviz
  graph G {
  start="12";
  1--2 
  2--3 
  3--7 
  4--5 
  5--6 
  5--3 
  6--7 
  7--2 
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  In dot format:

  {{{
  graph G {
  1--2 
  2--3 
  3--7 
  4--5 
  5--6 
  5--3 
  6--7 
  7--2 
  }
  }}}

  and in graphml format:

  {{{
  #!xml
  <?xml version="1.0" encoding="UTF-8"?>
  <graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://graphml.graphdrawing.org/xmlns/1.0/graphml.xsd">
    <graph id="G" edgedefault="undirected">
      <node id="n0"/>
      <node id="n1"/>
      <node id="n2"/>
      <node id="n3"/>
      <node id="n4"/>
      <node id="n5"/>
      <node id="n6"/>
      <edge id="e0" source="n0" target="n1"/>
      <edge id="e1" source="n1" target="n2"/>
      <edge id="e2" source="n2" target="n6"/>
      <edge id="e3" source="n3" target="n4"/>
      <edge id="e4" source="n4" target="n5"/>
      <edge id="e5" source="n4" target="n2"/>
      <edge id="e6" source="n5" target="n6"/>
      <edge id="e7" source="n6" target="n1"/>
    </graph>
  </graphml>
  }}}

  {{{
  #!html
  <div class="note">
  }}}
  ==== Which format to use? ====

  You can of course use either format, but in general graphml is preferred. It provides for a tighter definition of the graph, and since graph-tool understants the parse info attributes of the graph, you can speed up the loading of the file and reduce memory usage by using the following in your graph definition:

  {{{
  #!xml
  ...
   <graph id="G" edgedefault="directed" parse.nodeids="canonical" parse.edgeids="canonical" parse.order="nodesfirst">
  ...
  }}}

  This says that all vertices and edges are named "n0","n1", ..., "nN-1", and  "e0", "e1", ..., "eE-1", respectively. And also it says that the vertex list comes before the edge list. You're not forced to define your graph this way, but it does improve performace for large graphs.

  {{{
  #!html
  </div>
  }}}

  ----

  == Basic Statistics ==

  The two most basic properties of the graph are the number of vertex and edges, which is obtainable through the "{{{--number-of-vertices}}}" and "{{{--number-of-edges}}}" options. Suppose the first graph in [[ref(File Format Description)]] is saved under {{{example.xml}}}. We can then get the number of vertices and edges by typing:

  {{{
  $ graph-tool --load example.xml --number-of-vertices=- --number-of-edges=-
  number of vertices:     7
  number of edges:        8
  }}}

  The "-" parameter to the options is necessary to output the results in the terminal. Otherwise it writes it to the file given in the parameter.

  === Vertex Histogram ===

  The histogram of vertex properties (such as degree) can be obtained by the "{{{--vertex-histogram}}}" option. It requires two parameters, separated by "|": degree type and file name. Degree type can be any of "in-degree", "out-degree", "total-degree" and __any vertex scalar property__. The file name is the file the histogram is written to, or "-" to be written to the terminal. Files may be terminated with {{{.gz}}} or {{{.bz2}}} for compression. Example:

  {{{
  $ graph-tool --load example.xml --vertex-histogram="total-degree|deg-dist"
  $ cat deg-dist
  1.0     2
  2.0     1
  3.0     4
  }}}

  For directed graphs, it is also possible to get the combined (in,out)-degree histogram with the "{{{--combined-degree-histogram}}}" option:

  {{{
  $ graph-tool --load example.xml --combined-degree-histogram="deg-dist"
  $ cat deg-dist
  0.0     1.0     2
  1.0     1.0     1
  1.0     2.0     1
  2.0     1.0     3
  }}}

  === Edge Histogram ===

  The histogram of edge properties can be obtained in an analogous fashion with the "`--edge-histogram`" 
  option. Example:

  {{{
  $ graph-tool --load example.xml --edge-histogram="weight|weight-dist"                 
  $ cat weight-dist 
  0.1     1
  0.2     1
  0.5     1
  0.8     1
  1.2     1
  2.0     1
  5.5     1
  10.1    1
  }}}

  === Average Distance ===

  The average vertex-vertex distance can be obtained with the "{{{--average-distance}}}" option:

  {{{
  $ graph-tool --load example.xml --average-distance=-
  average distance:       0.714285714286
  }}}

  For directed and/or disconnected graphs, it may be better to use the average harmonic distance defined as:

  [[Equation(\[d_h = \left[\sum_{v,u}\frac{1}{d_{uv}}\right]^{-1}\])]], where [[Equation($d_{uv}$)]] is the regular graph distance between [[Equation($u$)]] and [[Equation($v$)]], which here is taken to be infinity when there's no path between those two vertices.

  Example:

  {{{
  $ graph-tool --load example.xml --average-harmonic-distance=-
  average harmonic distance:      4.1226993865
  }}}

  === Component Size Histogram === 

  Component size statistics can be obtained by the "{{{component-size-histogram}}}" option. Consider the following graph:

  {{{
  #!html
  <div style="text-align: center;">
  }}}
  {{{
  #!graphviz
  digraph G {
  1->2
  2->3
  3->1

  4->5

  6->7
  7->8
  8->9
  9->10
  10->11
  11->6
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  Defined by the following dot file (henceforth referred to as {{{multi-comp.dot}}}):
  {{{
  digraph G {
  1->2
  2->3
  3->1

  4->5

  6->7
  7->8
  8->9
  9->10
  10->11
  11->6
  }
  }}}

  When called with a directed graph, the program returns the '''strong component''' statistics:

  {{{
  $graph-tool --load multi-comp.dot --component-size-histogram="comp-hist"
  $ cat comp-hist
  1.0     2
  3.0     1
  6.0     1
  }}}

  To see the component statistics if the graph were undirected, we just have to treat it as such:

  {{{
  $ graph-tool --load multi-comp.dot --undirected --component-size-histogram="comp-hist"
  $ cat comp-hist
  2.0     1
  3.0     1
  6.0     1
  }}}


  == Filtering ==

  Graphs can be filtered in several ways. None of them actually modify the internally kept graph, and are therefore of complexity O(1).

  === Directedness ===

  Internally, all graphs in graph-tool are directed graphs. But it is possible to treat them easily as directed with the "{{{--undirected}}}" option. All options after that will operate on a undirected filter of the internal directed graph. The "{{{--directed}}}" option reverts back to the default mode.

  === Edge direction ===

  Directed graphs can have the the edge direction reversed with the "{{{--reverse}}}" option. A second "{{{--reverse}}}" reverts back to the original state.

  === Filtering of vertices or edges ===

  ==== Range filtering ====

  Edges and vertices can be filtered out of the graph based on their properties. The most basic and fastest way of filtering is called "range filtering" and filters out vertices with a scalar property which lays outside a given range. The filtering is controlled with the "{{{--vertex-range-filter}}}" and "{{{--edge-range-filter}}}" options, which takes two parameters separated by "|": the property to be used as filter and the range (two values separated by space. Here's an example using the graph defined in [[ref(File Format Description)]]:

  {{{
  $ graph-tool --load example.xml --number-of-edges=-
  number of edges:        8
  $ graph-tool --load example.xml --edge-range-filter="weight|0.6 6.0" --number-of-edges=- --save filtered.dot
  number of edges:        4
  }}}

  The file {{{filtered.dot}}} contains (representation on the side):

  {{{
  #!html
  <div style="float: right;">
  }}}
  {{{
  #!graphviz
  digraph G {
  1;
  2;
  3;
  7;
  4;
  5;
  6;
  1->2  [label="1.2"];
  2->3  [label="0.8"];
  5->3  [label="5.5"];
  6->7  [label="2.0"];
  }
  }}}
  {{{
  #!html
  </div>
  }}}

  {{{
  digraph G {
  1;
  2;
  3;
  7;
  4;
  5;
  6;
  1->2  [weight="1.2"];
  2->3  [weight="0.8"];
  5->3  [weight="5.5"];
  6->7  [weight="2"];
  }
  }}}

  ==== Generic Filtering ====

  Graphs can be filtered in a more versatile way than above (at a performance cost). This is done through the "{{{--vertex-filter}}}" and "{{{--edge-filter}}}" options, which take a generic [http://www.python.org python] expression as a parameter, and if it evaluates to {{{True}}} the vertex or edge is removed.

  Example:

  {{{
  #!html
  <div style="float: right;">
  }}}
  {{{
  #!graphviz
  digraph G {
  0;
  1;
  2;
  3;
  4;
  1->4  [label="0.5"];
  2->3  [label="10.1"];
  2->1  [label="5.5"];
  3->4  [label="2"];
  4->0  [label="0.1"];
  }
  }}}
  {{{
  #!html
  </div>
  }}}
  {{{
  $ graph-tool --load example.xml --edge-filter="weight==0.8" --vertex-filter="in_degree==0" --save filtered.dot
  $ cat filtered.dot
  digraph G {
  0;
  1;
  2;
  3;
  4;
  1->4  [weight="0.5"];
  2->3  [weight="10.1"];
  2->1  [weight="5.5"];
  3->4  [weight="2"];
  4->0  [weight="0.1"];
  }
  }}}

  {{{
  #!html
  <div class="note">
  }}}
  ===== Performace note =====
  When generic filtering is turned on, algorithms in general will run much slower, since the python interpreter will be involved in the computations. Therefore, if some expensive computation is being considered, it is in general better to save the graph to a file after the filtering, and load it as unfiltered to perform the computation.
  {{{
  #!html
  </div>
  }}}

  ==== Removing filtering ====

  The graph can be returned to its unfiltered state by calling "{{{--reset-vertex-filter}}}" and "{{{--reset-edge-filter}}}".

  == Graph Modifications ==

  There's a couple of options which change the internally kept graph.

  === Removing Properties ===

  Vertex and edge properties can be removed from the graph with the options "{{{--remove-vertex-property}}}" and "{{{--remove-edge-property}}}", which take the name of the property to be removed as parameter.

  === Vertex and Edge Indices ===

  Vertices and Edges are identified internally by indices. Those can be inserted as properties with the options "{{{--insert-vertex-index-property}}}" and "{{{--insert-edge-index-property}}}", which take as argument the name by which the property will be called.

  === Removal of Parallel Edges ===

  Parallel edges (i.e. edges that share the same source and target) can be removed from the graph with the option "{{{--remove-parallel-edges}}}", so that only one of the parallel edges ramain (it is undefined which one).


  == Correlations ==

  === Vertex Correlation ===

  The vertex correlation histogram is a bidimensional histogram defined as

  [[Equation(\[C(k,k')=\sum_{u,v}A_{uv}[k_u=k][k_v=k']\])]], where [[Equation($\mathbf{A}$)]] is the adjacenty matrix. It is obtainable with the "{{{--vertex-correlation-histogram}}}" option, which takes three parameters separated by "|": First degree type ([[Equation($k_u$)]]), second degree type ([[Equation($k_v$)]]) and a filename. The degree types can be `in-degree`, `out-degree` and `total-degree`. It can also be the name of any vertex scalar property available.

  Example:

  {{{
  $ graph-tool --load example.xml --degree-correlation="in-degree|out-degree|deg-corr"
  $ cat deg-corr
  0.0     1.0     1
  0.0     2.0     1
  1.0     1.0     3
  2.0     1.0     3
  }}}

  It is also possible to obtain the correlation in an aternative fashion, which a lot of times is more convenient, and that is the average nearest neighbours degree, given by

  [[Equation(\[ \bar{k}(k)=\frac{\sum_{u,v}A_{uv}k_v[k_u=k]}{\sum_{u,v}A_{uv}[k_u=k]}\])]].

  It is obtainable with the "`--average-nearest-neighbours-degree`" option, which takes four parameters separated by "|": type of neighbours, degree type of the origin vertex, degree type of the neighbours and a filename. Neighbour types can be "`all`", "`in`" and "`out`", for all, in and out-neighbours respectively. Origin and neighbour degree type can be "`in-degree`", "`out-degree`" and "`total-degree`", as well as the name of any vertex scalar property available.

  Example:

  {{{
  $ graph-tool --load example.xml --average-nearest-neighbours-degree="all|total-degree|in-degree|deg-corr"
  $ cat deg-corr
  1.0     1.5     0.5
  2.0     1.5     0.5
  3.0     1.41666666667   0.228908256511
  }}}

  The third column above is the standard deviation of the average in the second column.

  === Edge Correlation ===

  When edges have scalar properties, it is possible to generate a 3-dimensional correlation histogram defined as:

  [[Equation(\[ P(k,m,k')=\sum_{e}[k_{s(e)}=k][k_{t(e)}=k'][p(e)=m]}\])]], where [[Equation($e$)]] are the edges of the graph, [[Equation(\[s(e)\])]] and [[Equation(\[t(e)\])]] are the source and target vertex of edge [[Equation($e$)]], and [[Equation(\[p(e)\])]] is some property of the edge.

  This can be obtained with the "`--edge-degree-correlation-histogram`" option which takes four arguments separated by "|": Source degree type, edge property and target degree type. The source and target degree types can be "`in-degree`", "`out-degree`" and "`total-degree`", as well as the name of any vertex scalar property available.

  Example:
  {{{
  $ graph-tool --load example.xml --edge-degree-correlation-histogram="in-degree|weight|out-degree|edge-corr"
  $ cat edge-corr
  0.0     0.2     2.0     1
  0.0     1.2     1.0     1
  1.0     2.0     1.0     1
  1.0     5.5     1.0     1
  1.0     10.1    1.0     1
  2.0     0.1     1.0     1
  2.0     0.5     1.0     1
  2.0     0.8     1.0     1
  }}}

  === Assortativity Coefficient ===

  The assortativity coefficient tells in a concise fashion how vertices of different types are preferencially connected amongst themselves, and is defined by

  [[Equation(\[r = \frac{\sum_i e_{ii} - \sum_i a_i b_i}{1-\sum_i a_i b_i}\])]] where [[Equation(\[a_i=\sum_je_{ij}\])]] and [[Equation(\[b_j=\sum_ie_{ij}\])]], and [[Equation($e_{ij}$)]] is the fraction of edges from a vertex of type [[Equation($i$)]] to a vertex of type [[Equation($j$)]].

  It is obtained by the option "`--assortativity-coefficient`", which takes two arguments: the property used to identify different types and a file name, separated by "|". The property may be any scalar vertex property in the graph, as well a "`in-degree`", "`out-degree`" and "`total-degree`".

  Example:

  {{{
  $ graph-tool --load example.xml --assortativity-coefficient="total-degree|-"
  assortativity coefficient:      -0.230769230769
  }}}

  == Clustering ==

  === local clustering ===

  The local (vertex) clustering coefficient is defined on an undirected graph as 

  [[Equation(\[C^{(1)}_v = \frac{k(k-1)}{2N_c}\])]], where [[Equation($k$)]] is the degree of the vertex, and $N_c$ is the number of edges between the neighbours of the vertex. This value can be calculated and set to a vertex property with the command "`--set-local-clustering-to-property`", which takes the property name as paramenter. Example:

  {{{
  $ graph-tool --load example.xml --set-local-clustering-to-property=clustering --degree-histogram="clustering|clust"
  $ cat clust
  0.0     4
  0.333333333333  3
  }}}

  As a convenience, graph-tool also calculates the global average of the clustering coefficient [[Equation($\frac{\sum_vC^{(1)})_v}{N}$]], with the option "--local-clustering-coefficient", which takes a file name as a parameter (or "`-`" for standard output). Example:

      --local-clustering-coefficient=FILE                                       get the local clustering coefficient
      --local-clustering-coefficient-histogram=DEGREE_TYPE|FILE                 get the local clustering coefficient histogram
      --set-local-clustering-to-property=PROPERTY                               set the local clustering coefficient to vertex property
      --global-clustering-coefficient=FILE                                      get the global clustering coefficient


  == Layout ==
      --compute-spring-block-layout=ITERATIONS[|SEED]                           compute the spring block layout
      --compute-gursoy-atun-layout=ITERATIONS[|SEED]                            compute the Gursoy-Atun layout


  == Random Graph Generation ==
      --correlated-configurational-model=OPTIONS                                generate graph using the configurational model with arbitrary degree
                                                                                correlations. Options are: N, pjk, pjk_ceil, pjk_m, inv_pjk_ceil, corr,
                                                                                corr_ceil, corr_m, inv_corr_ceil, undirected, directed, progress, seed. See
                                                                                documentation for details.

  == Graph History ==

      --history=INIT|CONDITION|STEP                                             compute graph history
      --history-rate=TIME  


