__init__.py 72.6 KB
Newer Older
1
#! /usr/bin/env python
2
# -*- coding: utf-8 -*-
3
#
4 5
# graph_tool -- a general graph manipulation python module
#
Tiago Peixoto's avatar
Tiago Peixoto committed
6
# Copyright (C) 2007-2012 Tiago de Paula Peixoto <tiago@skewed.de>
7 8 9 10 11 12 13 14 15 16 17 18 19 20
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <http://www.gnu.org/licenses/>.

21
"""
Tiago Peixoto's avatar
Tiago Peixoto committed
22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42
graph_tool - efficient graph analysis and manipulation
======================================================

Summary
-------

.. autosummary::
   :nosignatures:

   Graph
   GraphView
   Vertex
   Edge
   PropertyMap
   PropertyArray
   load_graph
   group_vector_property
   ungroup_vector_property
   value_types
   show_config

Tiago Peixoto's avatar
Tiago Peixoto committed
43 44

This module provides:
45

46
   1. A :class:`~graph_tool.Graph` class for graph representation and manipulation
47 48
   2. Property maps for Vertex, Edge or Graph.
   3. Fast algorithms implemented in C++.
49

50 51
How to use the documentation
----------------------------
52

53 54
Documentation is available in two forms: docstrings provided
with the code, and the full documentation available in
Tiago Peixoto's avatar
Tiago Peixoto committed
55
`the graph-tool homepage <http://graph-tool.skewed.de>`_.
56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73

We recommend exploring the docstrings using `IPython
<http://ipython.scipy.org>`_, an advanced Python shell with TAB-completion and
introspection capabilities.

The docstring examples assume that ``graph_tool.all`` has been imported as
``gt``::

   >>> import graph_tool.all as gt

Code snippets are indicated by three greater-than signs::

   >>> x = x + 1

Use the built-in ``help`` function to view a function's docstring::

   >>> help(gt.Graph)

Tiago Peixoto's avatar
Tiago Peixoto committed
74 75
Contents
--------
76
"""
77

78
from __future__ import division, absolute_import, print_function
79 80 81
import sys
if sys.version_info < (3,):
    range = xrange
82

Tiago Peixoto's avatar
Tiago Peixoto committed
83
__author__ = "Tiago de Paula Peixoto <tiago@skewed.de>"
Tiago Peixoto's avatar
Tiago Peixoto committed
84
__copyright__ = "Copyright 2007-2012 Tiago de Paula Peixoto"
Tiago Peixoto's avatar
Tiago Peixoto committed
85
__license__ = "GPL version 3 or above"
Tiago Peixoto's avatar
Tiago Peixoto committed
86
__URL__ = "http://graph-tool.skewed.de"
87

88 89 90 91
# import numpy and scipy before everything to avoid weird segmentation faults
# depending on the order things are imported.

import numpy
92
import numpy.ma
93 94 95
import scipy
import scipy.stats

96 97 98

from .dl_import import *
dl_import("from . import libgraph_tool_core as libcore")
Tiago Peixoto's avatar
Tiago Peixoto committed
99 100
__version__ = libcore.mod_info().version

101
from . import io  # sets up libcore io routines
Tiago Peixoto's avatar
Tiago Peixoto committed
102 103 104 105 106 107 108 109

import sys
import os
import re
import gzip
import weakref
import copy

Tiago Peixoto's avatar
Tiago Peixoto committed
110
from io import BytesIO
111
from .decorators import _wraps, _require, _attrs, _limit_args
Tiago Peixoto's avatar
Tiago Peixoto committed
112
from inspect import ismethod
Tiago Peixoto's avatar
Tiago Peixoto committed
113 114

__all__ = ["Graph", "GraphView", "Vertex", "Edge", "Vector_bool",
115
           "Vector_int16_t", "Vector_int32_t", "Vector_int64_t", "Vector_double",
Tiago Peixoto's avatar
Tiago Peixoto committed
116 117
           "Vector_long_double", "Vector_string", "value_types", "load_graph",
           "PropertyMap", "group_vector_property", "ungroup_vector_property",
118
           "infect_vertex_property", "edge_difference", "seed_rng", "show_config",
Tiago Peixoto's avatar
Tiago Peixoto committed
119 120
           "PropertyArray", "__author__", "__copyright__", "__URL__",
           "__version__"]
Tiago Peixoto's avatar
Tiago Peixoto committed
121

Tiago Peixoto's avatar
Tiago Peixoto committed
122 123
# this is rather pointless, but it works around a sphinx bug
graph_tool = sys.modules[__name__]
Tiago Peixoto's avatar
Tiago Peixoto committed
124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169

################################################################################
# Utility functions
################################################################################


def _prop(t, g, prop):
    """Return either a property map, or an internal property map with a given
    name."""
    if type(prop) == str:
        try:
            pmap = g.properties[(t, prop)]
        except KeyError:
            raise KeyError("no internal %s property named: %s" %\
                           ("vertex" if t == "v" else \
                            ("edge" if t == "e" else "graph"), prop))
    else:
        pmap = prop
    if pmap == None:
        return libcore.any()
    else:
        if t != prop.key_type():
            names = {'e': 'edge', 'v': 'vertex', 'g': 'graph'}
            raise ValueError("Expected '%s' property map, got '%s'" %
                             (names[t], names[prop.key_type()]))
        return pmap._PropertyMap__map.get_map()


def _degree(g, name):
    """Retrieve the degree type from string, or returns the corresponding
    property map."""
    deg = name
    if name == "in-degree" or name == "in":
        deg = libcore.Degree.In
    elif name == "out-degree" or name == "out":
        deg = libcore.Degree.Out
    elif name == "total-degree" or name == "total":
        deg = libcore.Degree.Total
    else:
        deg = _prop("v", g, deg)
    return deg


def _type_alias(type_name):
    alias = {"int8_t": "bool",
             "boolean": "bool",
170
             "short": "int16_t",
Tiago Peixoto's avatar
Tiago Peixoto committed
171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204
             "int": "int32_t",
             "long": "int64_t",
             "long long": "int64_t",
             "object": "python::object",
             "float": "double"}
    if type_name in value_types():
        return type_name
    if type_name in alias:
        return alias[type_name]
    ma = re.compile(r"vector<(.*)>").match(type_name)
    if ma:
        t = ma.group(1)
        if t in alias:
            return "vector<%s>" % alias[t]
    raise ValueError("invalid property value type: " + type_name)


def _python_type(type_name):
    type_name = _type_alias(type_name)
    if "vector" in type_name:
        ma = re.compile(r"vector<(.*)>").match(type_name)
        t = ma.group(1)
        return list, _python_type(t)
    if "int" in type_name:
        return int
    if type_name == "bool":
        return bool
    if "double" in type_name:
        return float
    if "string" in type_name:
        return str
    return object


205 206 207 208
def _gt_type(obj):
    t = type(obj)
    if t is numpy.longlong or t is numpy.uint64:
        return "long long"
209 210
    if issubclass(t, numpy.int16):
        return "short"
211 212 213 214 215 216 217 218 219 220 221 222 223 224 225
    if t is int or issubclass(t, numpy.int):
        return "int"
    if t is numpy.float128:
        return "long double"
    if t is float or issubclass(t, numpy.float):
        return "double"
    if t is str:
        return "string"
    if t is bool:
        return "bool"
    if issubclass(t, list) or issubclass(t, numpy.ndarray):
        return "vector<%s>" % _gt_type(obj[0])
    return "object"


226 227 228 229 230 231 232 233 234
def _convert(prop, val):
    # attempt to convert to a compatible python type. This is useful,
    # for instance, when dealing with numpy types.
    vtype = _python_type(prop.value_type())
    if type(vtype) is tuple:
        return [vtype[1](x) for x in val]
    return vtype(val)


Tiago Peixoto's avatar
Tiago Peixoto committed
235 236 237
def show_config():
    """Show ``graph_tool`` build configuration."""
    info = libcore.mod_info()
238 239 240 241 242 243 244 245
    print("version:", info.version)
    print("gcc version:", info.gcc_version)
    print("compilation flags:", info.cxxflags)
    print("install prefix:", info.install_prefix)
    print("python dir:", info.python_dir)
    print("graph filtering:", libcore.graph_filtering_enabled())
    print("openmp:", libcore.openmp_enabled())
    print("uname:", " ".join(os.uname()))
Tiago Peixoto's avatar
Tiago Peixoto committed
246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273

################################################################################
# Property Maps
################################################################################


class PropertyArray(numpy.ndarray):
    """This is a :class:`~numpy.ndarray` subclass which keeps a reference of its :class:`~graph_tool.PropertyMap` owner, and detects if the underlying data has been invalidated."""

    __array_priority__ = -10

    def _get_pmap(self):
        return self._prop_map

    def _set_pmap(self, value):
        self._prop_map = value

    prop_map = property(_get_pmap, _set_pmap,
                        doc=":class:`~graph_tool.PropertyMap` owner instance.")

    def __new__(cls, input_array, prop_map):
        obj = numpy.asarray(input_array).view(cls)
        obj.prop_map = prop_map

        # check if data really belongs to property map
        if (prop_map._get_data().__array_interface__['data'][0] !=
            obj._get_base_data()):
            obj.prop_map = None
274
            # do a copy
Tiago Peixoto's avatar
Tiago Peixoto committed
275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354
            obj = numpy.asarray(obj)

        return obj

    def _get_base(self):
        base = self
        while base.base is not None:
            base = base.base
        return base

    def _get_base_data(self):
        return self._get_base().__array_interface__['data'][0]

    def _check_data(self):
        if self.prop_map is None:
            return

        data = self.prop_map._get_data()

        if (data is None or
            data.__array_interface__['data'][0] != self._get_base_data()):
            raise ValueError(("The graph correspondig to the underlying" +
                              " property map %s has changed. The" +
                              " PropertyArray at 0x%x is no longer valid!") %
                             (repr(self.prop_map), id(self)))

    def __array_finalize__(self, obj):
        if type(obj) is PropertyArray:
            obj._check_data()

        if obj is not None:
            # inherit prop_map only if the data is the same
            if (type(obj) is PropertyArray and
                self._get_base_data() == obj._get_base_data()):
                self.prop_map = getattr(obj, 'prop_map', None)
            else:
                self.prop_map = None
        self._check_data()

    def __array_prepare__(self, out_arr, context=None):
        self._check_data()
        return numpy.ndarray.__array_prepare__(self, out_arr, context)

    def __array_wrap__(self, out_arr, context=None):
        #demote to ndarray
        obj = numpy.ndarray.__array_wrap__(self, out_arr, context)
        return numpy.asarray(obj)

    # Overload members and operators to add data checking

    def _wrap_method(method):
        method = getattr(numpy.ndarray, method)

        def checked_method(self, *args, **kwargs):
            self._check_data()
            return method(self, *args, **kwargs)

        if ismethod(method):
            checked_method = _wraps(method)(checked_method)
        checked_method.__doc__ = getattr(method, "__doc__", None)
        return checked_method

    for method in ['all', 'any', 'argmax', 'argmin', 'argsort', 'astype',
                   'byteswap', 'choose', 'clip', 'compress', 'conj',
                   'conjugate', 'copy', 'cumprod', 'cumsum', 'diagonal', 'dot',
                   'dump', 'dumps', 'fill', 'flat', 'flatten', 'getfield',
                   'imag', 'item', 'itemset', 'itemsize', 'max', 'mean', 'min',
                   'newbyteorder', 'nonzero', 'prod', 'ptp', 'put', 'ravel',
                   'real', 'repeat', 'reshape', 'resize', 'round',
                   'searchsorted', 'setfield', 'setflags', 'sort', 'squeeze',
                   'std', 'sum', 'swapaxes', 'take', 'tofile', 'tolist',
                   'tostring', 'trace', 'transpose', 'var', 'view',
                   '__getitem__']:
        if hasattr(numpy.ndarray, method):
            locals()[method] = _wrap_method(method)


class PropertyMap(object):
    """This class provides a mapping from vertices, edges or whole graphs to arbitrary properties.

355 356 357
    See :ref:`sec_property_maps` for more details.

    The possible property value types are listed below.
Tiago Peixoto's avatar
Tiago Peixoto committed
358 359 360 361 362 363 364

    .. table::

        =======================     ======================
         Type name                  Alias
        =======================     ======================
        ``bool``                    ``uint8_t``
365
        ``int16_t``                 ``short``
Tiago Peixoto's avatar
Tiago Peixoto committed
366 367 368 369 370 371
        ``int32_t``                 ``int``
        ``int64_t``                 ``long``, ``long long``
        ``double``                  ``float``
        ``long double``
        ``string``
        ``vector<bool>``            ``vector<uint8_t>``
372
        ``vector<int16_t>``         ``short``
Tiago Peixoto's avatar
Tiago Peixoto committed
373 374 375 376 377 378 379 380
        ``vector<int32_t>``         ``vector<int>``
        ``vector<int64_t>``         ``vector<long>``, ``vector<long long>``
        ``vector<double>``          ``vector<float>``
        ``vector<long double>``
        ``vector<string>``
        ``python::object``          ``object``
        =======================     ======================
    """
381
    def __init__(self, pmap, g, key_type):
Tiago Peixoto's avatar
Tiago Peixoto committed
382 383
        self.__map = pmap
        self.__g = weakref.ref(g)
384 385 386 387 388 389 390 391
        self.__base_g = lambda: None
        try:
            if isinstance(g, GraphView):
                self.__base_g = weakref.ref(g.base)  # keep reference to the
                                                     # base graph, in case the
                                                     # graph view is deleted.
        except NameError:
            pass  # ignore if GraphView is yet undefined
Tiago Peixoto's avatar
Tiago Peixoto committed
392 393 394
        self.__key_type = key_type
        self.__register_map()

395 396 397 398 399 400 401
    def __key_trans(self, key):
        if self.key_type() == "g":
            return key._Graph__graph
        else:
            return key


Tiago Peixoto's avatar
Tiago Peixoto committed
402
    def __register_map(self):
403 404 405 406
        for g in [self.__g(), self.__base_g()]:
            if g is not None:
                g._Graph__known_properties.append((self.key_type(),
                                                   weakref.ref(self.__map)))
Tiago Peixoto's avatar
Tiago Peixoto committed
407 408

    def __unregister_map(self):
409 410 411 412 413
        for g in [self.__g(), self.__base_g()]:
            if g is not None:
                i = g._Graph__known_properties.index((self.key_type(),
                                                      weakref.ref(self.__map)))
                del g._Graph__known_properties[i]
Tiago Peixoto's avatar
Tiago Peixoto committed
414 415 416 417 418 419 420 421 422 423 424 425

    def __del__(self):
        self.__unregister_map()

    def __getitem__(self, k):
        return self.__map[self.__key_trans(k)]

    def __setitem__(self, k, v):
        key = self.__key_trans(k)
        try:
            self.__map[key] = v
        except TypeError:
426
            self.__map[key] = _convert(self, v)
Tiago Peixoto's avatar
Tiago Peixoto committed
427 428 429 430 431 432 433 434 435

    def __repr__(self):
        # provide some more useful information
        if self.key_type() == "e":
            k = "Edge"
        elif self.key_type() == "v":
            k = "Vertex"
        else:
            k = "Graph"
436
        g = self.get_graph()
Tiago Peixoto's avatar
Tiago Peixoto committed
437 438 439 440 441 442 443
        if g == None:
            g = "a non-existent graph"
        else:
            g = "Graph 0x%x" % id(g)
        return ("<PropertyMap object with key type '%s' and value type '%s',"
                + " for %s, at 0x%x>") % (k, self.value_type(), g, id(self))

444 445 446 447
    def copy(self, value_type=None):
        """Return a copy of the property map. If ``value_type`` is specified,
        the value type is converted to the chosen type."""
        return self.get_graph().copy_property(self, value_type=value_type)
448

Tiago Peixoto's avatar
Tiago Peixoto committed
449 450
    def get_graph(self):
        """Get the graph class to which the map refers."""
451 452 453 454
        g = self.__g()
        if g is None:
            g = self.__base_g()
        return g
Tiago Peixoto's avatar
Tiago Peixoto committed
455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470

    def key_type(self):
        """Return the key type of the map. Either 'g', 'v' or 'e'."""
        return self.__key_type

    def value_type(self):
        """Return the value type of the map."""
        return self.__map.value_type()

    def python_value_type(self):
        """Return the python-compatible value type of the map."""
        return _python_type(self.__map.value_type())

    def get_array(self):
        """Get a :class:`~graph_tool.PropertyArray` with the property values.

471 472 473 474 475 476 477
        .. note::

           An array is returned *only if* the value type of the property map is
           a scalar. For vector, string or object types, ``None`` is returned
           instead.

        .. warning::
Tiago Peixoto's avatar
Tiago Peixoto committed
478 479 480 481 482 483 484 485 486 487 488 489 490

           The returned array does not own the data, which belongs to the
           property map. Therefore, if the graph changes, the array may become
           *invalid* and any operation on it will fail with a
           :class:`ValueError` exception. Do **not** store the array if
           the graph is to be modified; store a **copy** instead.
        """
        a = self._get_data()
        if a is None:
            return None
        return PropertyArray(a, prop_map=self)

    def _get_data(self):
491 492
        g = self.get_graph()
        if g is None:
Tiago Peixoto's avatar
Tiago Peixoto committed
493
            return None
494
        g.stash_filter(edge=True, vertex=True)
Tiago Peixoto's avatar
Tiago Peixoto committed
495
        if self.__key_type == 'v':
496
            n = g.num_vertices()
Tiago Peixoto's avatar
Tiago Peixoto committed
497
        elif self.__key_type == 'e':
498
            n = g._Graph__graph.GetMaxEdgeIndex() + 1
Tiago Peixoto's avatar
Tiago Peixoto committed
499 500
        else:
            n = 1
501
        g.pop_filter(edge=True, vertex=True)
Tiago Peixoto's avatar
Tiago Peixoto committed
502 503 504 505
        a = self.__map.get_array(n)
        return a

    def __set_array(self, v):
506 507 508 509
        a = self.get_array()
        if a is None:
            return
        a[:] = v
Tiago Peixoto's avatar
Tiago Peixoto committed
510

511
    a = property(get_array, __set_array,
Tiago Peixoto's avatar
Tiago Peixoto committed
512
                 doc=r"""Shortcut to the :meth:`~PropertyMap.get_array` method
513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532
                 as an attribute. This makes assignments more convenient, e.g.:

                 >>> g = gt.Graph()
                 >>> g.add_vertex(10)
                 [...]
                 >>> prop = g.new_vertex_property("double")
                 >>> prop.a = np.random.random(10)           # Assignment from array
                 """)

    def __get_set_f_array(self, v=None, get=True):
        g = self.get_graph()
        if g is None:
            return None
        a = self.get_array()
        filt = [None]
        if self.__key_type == 'v':
            filt = g.get_vertex_filter()
        elif self.__key_type == 'e':
            filt = g.get_edge_filter()
        if get:
533 534 535 536
            if a is None:
                return a
            if filt[0] is None:
                return a
537 538
            return a[filt[0].a == (not filt[1])]
        else:
539 540 541
            if a is None:
                return
            if filt[0] is None:
542 543 544 545
                try:
                    a[:] = v
                except ValueError:
                    a[:] = v[:len(a)]
546
            else:
547 548 549 550 551
                m = filt[0].a == (not filt[1])
                try:
                    a[m] = v
                except ValueError:
                    a[m] = v[:len(m)][m]
552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594

    fa = property(__get_set_f_array,
                  lambda self, v: self.__get_set_f_array(v, False),
                  doc=r"""The same as the :attr:`~PropertyMap.a` attribute, but
                  instead an *indexed* array is returned, which contains only
                  entries for vertices/edges which are not filtered out. If
                  there are no filters in place, the array is not indexed, and
                  is identical to the :attr:`~PropertyMap.a` attribute.

                  Note that because advanced indexing is triggered, a **copy**
                  of the array is returned, not a view, as for the
                  :attr:`~PropertyMap.a` attribute. Nevertheless, the assignment
                  of values to the *whole* array at once works as expected.""")

    def __get_set_m_array(self, v=None, get=True):
        g = self.get_graph()
        if g is None:
            return None
        a = self.get_array()
        filt = [None]
        if self.__key_type == 'v':
            filt = g.get_vertex_filter()
        elif self.__key_type == 'e':
            filt = g.get_edge_filter()
        if filt[0] is None or a is None:
            if get:
                return a
            else:
                return
        ma = numpy.ma.array(a, mask=(filt[0].a == False) if not filt[1] else (filt[0].a == True))
        if get:
            return ma
        else:
            ma[:] = v

    ma = property(__get_set_m_array,
                  lambda self, v: self.__get_set_m_array(v, False),
                  doc=r"""The same as the :attr:`~PropertyMap.a` attribute, but
                  instead a :class:`~numpy.ma.MaskedArray` object is returned,
                  which contains only entries for vertices/edges which are not
                  filtered out. If there are no filters in place, a regular
                  :class:`~graph_tool.PropertyArray` is returned, which is
                  identical to the :attr:`~PropertyMap.a` attribute.""")
Tiago Peixoto's avatar
Tiago Peixoto committed
595 596 597 598 599

    def is_writable(self):
        """Return True if the property is writable."""
        return self.__map.is_writable()

600 601 602 603 604
    def __call__(self, a):
        p = self.copy()
        p.fa = a
        return p

Tiago Peixoto's avatar
Tiago Peixoto committed
605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657

def _check_prop_writable(prop, name=None):
    if not prop.is_writable():
        raise ValueError("property map%s is not writable." %\
                         ((" '%s'" % name) if name != None else ""))


def _check_prop_scalar(prop, name=None, floating=False):
    scalars = ["bool", "int32_t", "int64_t", "unsigned long",
               "double", "long double"]
    if floating:
        scalars = ["double", "long double"]

    if prop.value_type() not in scalars:
        raise ValueError("property map%s is not of scalar%s type." %\
                         (((" '%s'" % name) if name != None else ""),
                          (" floating" if floating else "")))


def _check_prop_vector(prop, name=None, scalar=True, floating=False):
    scalars = ["bool", "int32_t", "int64_t", "unsigned long",
               "double", "long double"]
    if not scalar:
        scalars += ["string"]
    if floating:
        scalars = ["double", "long double"]
    vals = ["vector<%s>" % v for v in scalars]
    if prop.value_type() not in vals:
        raise ValueError("property map%s is not of vector%s type." %\
                         (((" '%s'" % name) if name != None else ""),
                          (" floating" if floating else "")))


def group_vector_property(props, value_type=None, vprop=None, pos=None):
    """Group list of properties ``props`` into a vector property map of the same type.

    Parameters
    ----------
    props : list of :class:`~graph_tool.PropertyMap`
        Properties to be grouped.
    value_type : string (optional, default: None)
        If supplied, defines the value type of the grouped property.
    vprop : :class:`~graph_tool.PropertyMap` (optional, default: None)
        If supplied, the properties are grouped into this property map.
    pos : list of ints (optional, default: None)
        If supplied, should contain a list of indexes where each corresponding
        element of ``props`` should be inserted.

    Returns
    -------
    vprop : :class:`~graph_tool.PropertyMap`
       A vector property map with the grouped values of each property map in
       ``props``.
658 659 660 661 662 663 664

    Examples
    --------
    >>> from numpy.random import seed, randint
    >>> from numpy import array
    >>> seed(42)
    >>> g = gt.random_graph(100, lambda: (3, 3))
665 666
    >>> props = [g.new_vertex_property("int") for i in range(3)]
    >>> for i in range(3):
667 668
    ...    props[i].a = randint(0, 100, g.num_vertices())
    >>> gprop = gt.group_vector_property(props)
669
    >>> print(gprop[g.vertex(0)].a)
670
    [71 40 96]
671
    >>> print(array([p[g.vertex(0)] for p in props]))
672
    [71 40 96]
Tiago Peixoto's avatar
Tiago Peixoto committed
673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708
    """
    g = props[0].get_graph()
    vtypes = set()
    keys = set()
    for i, p in enumerate(props):
        if "vector" in p.value_type():
            raise ValueError("property map 'props[%d]' is a vector property." %
                             i)
        vtypes.add(p.value_type())
        keys.add(p.key_type())
    if len(keys) > 1:
        raise ValueError("'props' must be of the same key type.")
    k = keys.pop()

    if vprop == None:
        if value_type == None and len(vtypes) == 1:
            value_type = vtypes.pop()

        if value_type != None:
            value_type = "vector<%s>" % value_type
            if k == 'v':
                vprop = g.new_vertex_property(value_type)
            elif k == 'e':
                vprop = g.new_edge_property(value_type)
            else:
                vprop = g.new_graph_property(value_type)
        else:
            ValueError("Can't automatically determine property map value" +
                       " type. Please provide the 'value_type' parameter.")
    _check_prop_vector(vprop, name="vprop", scalar=False)

    for i, p in enumerate(props):
        if k != "g":
            g.stash_filter(directed=True, reversed=True)
            g.set_directed(True)
            g.set_reversed(False)
709
            libcore.group_vector_property(g._Graph__graph, _prop(k, g, vprop),
Tiago Peixoto's avatar
Tiago Peixoto committed
710 711 712 713 714
                                          _prop(k, g, p),
                                          i if pos == None else pos[i],
                                          k == 'e')
            g.pop_filter(directed=True, reversed=True)
        else:
715
            vprop[g][i if pos is None else pos[i]] = p[g]
Tiago Peixoto's avatar
Tiago Peixoto committed
716 717 718 719 720 721
    return vprop


def ungroup_vector_property(vprop, pos, props=None):
    """Ungroup vector property map ``vprop`` into a list of individual property maps.

722
    Parameters 
Tiago Peixoto's avatar
Tiago Peixoto committed
723 724 725
    ----------
    vprop : :class:`~graph_tool.PropertyMap`
        Vector property map to be ungrouped.
726 727 728
    pos : list of ints
        A list of indexes corresponding to where each element of ``vprop``
        should be inserted into the ungrouped list.
Tiago Peixoto's avatar
Tiago Peixoto committed
729 730 731 732 733 734 735 736
    props : list of :class:`~graph_tool.PropertyMap`  (optional, default: None)
        If supplied, should contain a list of property maps to which ``vprop``
        should be ungroupped.

    Returns
    -------
    props : list of :class:`~graph_tool.PropertyMap`
       A list of property maps with the ungrouped values of ``vprop``.
737 738 739 740 741 742 743 744 745 746 747

    Examples
    --------
    >>> from numpy.random import seed, randint
    >>> from numpy import array
    >>> seed(42)
    >>> g = gt.random_graph(100, lambda: (3, 3))
    >>> prop = g.new_vertex_property("vector<int>")
    >>> for v in g.vertices():
    ...    prop[v] = randint(0, 100, 3)
    >>> uprops = gt.ungroup_vector_property(prop, [0, 1, 2])
748
    >>> print(prop[g.vertex(0)].a)
749
    [71 60 20]
750
    >>> print(array([p[g.vertex(0)] for p in uprops]))
751
    [71 60 20]
Tiago Peixoto's avatar
Tiago Peixoto committed
752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785
    """

    g = vprop.get_graph()
    _check_prop_vector(vprop, name="vprop", scalar=False)
    k = vprop.key_type()
    value_type = vprop.value_type().split("<")[1].split(">")[0]
    if props == None:
        if k == 'v':
            props = [g.new_vertex_property(value_type) for i in pos]
        elif k == 'e':
            props = [g.new_edge_property(value_type) for i in pos]
        else:
            props = [g.new_graph_property(value_type) for i in pos]

    for i, p in enumerate(pos):
        if props[i].key_type() != k:
            raise ValueError("'props' must be of the same key type as 'vprop'.")

        if k != 'g':
            g.stash_filter(directed=True, reversed=True)
            g.set_directed(True)
            g.set_reversed(False)
            libcore.ungroup_vector_property(g._Graph__graph,
                                            _prop(k, g, vprop),
                                            _prop(k, g, props[i]),
                                            p, k == 'e')
            g.pop_filter(directed=True, reversed=True)
        else:
            if len(vprop[g]) <= pos[i]:
                vprop[g].resize(pos[i] + 1)
            props[i][g] = vprop[g][pos[i]]
    return props


786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808
def infect_vertex_property(g, prop, vals=None):
    """Propagate the `prop` values of vertices with value `val` to all their
    out-neighbours.

    Parameters
    ----------
    prop : :class:`~graph_tool.PropertyMap`
        Property map to be modified.
    vals : list (optional, default: `None`)
        List of values to be propagated. If not provided, all values
        will be propagated.

    Returns
    -------
    None

    Examples
    --------
    >>> from numpy.random import seed
    >>> seed(42)
    >>> g = gt.random_graph(100, lambda: (3, 3))
    >>> prop = g.copy_property(g.vertex_index)
    >>> gt.infect_vertex_property(g, prop, [10])
809
    >>> print(sum(prop.a == 10))
810 811 812 813 814
    3
    """
    libcore.infect_vertex_property(g._Graph__graph, _prop("v", g, prop),
                                   vals)

Tiago Peixoto's avatar
Tiago Peixoto committed
815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838

def edge_difference(g, prop, ediff=None):
    """Return an edge property map corresponding to the difference between the
    values of `prop` of target and source vertices of each edge.

    Parameters
    ----------
    prop : :class:`~graph_tool.PropertyMap`
        Vertex property map to be used to compute the difference..
    ediff : :class:`~graph_tool.PropertyMap` (optional, default: `None`)
        If not provided, the difference values will be stored in this property
        map.

    Returns
    -------
    ediff : :class:`~graph_tool.PropertyMap`
        Edge differences.

    Examples
    --------
    >>> from numpy.random import seed
    >>> seed(42)
    >>> g = gt.random_graph(100, lambda: (3, 3))
    >>> ediff = gt.edge_difference(g, g.vertex_index)
839
    >>> print(ediff.a)
Tiago Peixoto's avatar
Tiago Peixoto committed
840 841 842 843 844 845 846 847 848 849 850 851 852 853 854
    3
    """
    val_t = prop.value_type()
    if val_t == "unsigned long":
        val_t = "int32_t"
    if ediff is None:
        ediff = g.new_edge_property(val_t)
    if ediff.value_type() != val_t:
        raise ValueError("'ediff' must be of the same value type as 'prop': " +
                         val_t)
    libcore.edge_difference(g._Graph__graph, _prop("v", g, prop),
                            _prop("e", g, ediff))
    return ediff


Tiago Peixoto's avatar
Tiago Peixoto committed
855 856
class PropertyDict(dict):
    """Wrapper for the dict of vertex, graph or edge properties, which sets the
857 858 859 860 861 862 863 864 865
    value on the property map when changed in the dict.

    .. note::

        The class is only an one-way proxy to the internally-kept properties. If
        you modify this object, the change will be propagated to the internal
        dictionary, but not vice-versa. Keep this in mind if you intend to keep
        a copy of the class instance.
    """
Tiago Peixoto's avatar
Tiago Peixoto committed
866 867 868 869 870 871 872 873
    def __init__(self, g, old, get_func, set_func, del_func):
        dict.__init__(self)
        dict.update(self, old)
        self.g = g
        self.get_func = get_func
        self.set_func = set_func
        self.del_func = del_func

874 875 876 877
    def __getitem__(self, key):
        if self.get_func != None:
            val = self.get_func(self.g, key)
            dict.__setitem__(self, key, val)
878
            return val
879 880 881
        else:
            raise KeyError("Property dict cannot be gotten")

Tiago Peixoto's avatar
Tiago Peixoto committed
882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897
    def __setitem__(self, key, val):
        if self.set_func != None:
            self.set_func(self.g, key, val)
        else:
            raise KeyError("Property dict cannot be set")
        dict.__setitem__(self, key, val)

    def __delitem__(self, key):
        self.del_func(self.g, key)
        dict.__delitem__(self, key)

################################################################################
# Graph class
# The main graph interface
################################################################################

898 899 900
from .libgraph_tool_core import Vertex, EdgeBase, Vector_bool, Vector_int16_t, \
    Vector_int32_t, Vector_int64_t, Vector_double, Vector_long_double, \
    Vector_string, new_vertex_property, new_edge_property, new_graph_property
Tiago Peixoto's avatar
Tiago Peixoto committed
901 902 903 904 905


class Graph(object):
    """Generic multigraph class.

906 907
    This class encapsulates either a directed multigraph (default or if
    ``directed=True``) or an undirected multigraph (if ``directed=False``),
908
    with optional internal edge, vertex or graph properties.
Tiago Peixoto's avatar
Tiago Peixoto committed
909 910 911 912

    If ``g`` is specified, the graph (and its internal properties) will be
    copied.

913 914 915 916 917
    If ``prune`` is set to True, and ``g`` is specified, only the filtered graph
    will be copied, and the new graph object will not be filtered. Optionally, a
    tuple of three booleans can be passed as value to ``prune``, to specify a
    different behavior to vertex, edge, and reversal filters, respectively.

Tiago Peixoto's avatar
Tiago Peixoto committed
918 919 920 921 922 923 924
    The graph is implemented as an `adjacency list`_, where both vertex and edge
    lists are C++ STL vectors.

    .. _adjacency list: http://en.wikipedia.org/wiki/Adjacency_list

    """

925
    def __init__(self, g=None, directed=True, prune=False):
Tiago Peixoto's avatar
Tiago Peixoto committed
926 927 928 929 930 931 932 933
        self.__properties = {}
        self.__known_properties = []
        self.__filter_state = {"reversed": False,
                               "edge_filter": (None, False),
                               "vertex_filter": (None, False),
                               "directed": True}
        self.__stashed_filter_state = []

934
        if g is None:
Tiago Peixoto's avatar
Tiago Peixoto committed
935 936 937
            self.__graph = libcore.GraphInterface()
            self.set_directed(directed)
        else:
938 939 940 941 942 943
            if isinstance(prune, bool):
                vprune = eprune = rprune = prune
            else:
                vprune, eprune, rprune = prune
            if not (vprune or eprune or rprune):
                g.stash_filter(vertex=vprune, edge=vprune, reversed=rprune)
944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975

            # Copy all internal properties from original graph.
            vprops = []
            eprops = []
            for k, v in g.vertex_properties.items():
                vprops.append([_prop("v", g, v), libcore.any()])
            for k, v in g.edge_properties.items():
                eprops.append([_prop("e", g, v), libcore.any()])

            # The actual copying of the graph and property maps
            self.__graph = libcore.GraphInterface(g.__graph, False, vprops, eprops)

            # Put the copied properties in the internal dictionary
            for k, v in g.vertex_properties.items():
                pmap = new_vertex_property(v.value_type(),
                                           self.__graph.GetVertexIndex(),
                                           vprops[0][1])
                self.vertex_properties[k] = PropertyMap(pmap, self, "v")
                del vprops[0]

            for k, v in g.edge_properties.items():
                pmap = new_edge_property(v.value_type(),
                                         self.__graph.GetEdgeIndex(),
                                         eprops[0][1])
                self.edge_properties[k] = PropertyMap(pmap, self, "e")
                del eprops[0]

            for k, v in g.graph_properties.items():
                new_p = self.new_graph_property(v.value_type())
                new_p[self] = v[g]
                self.graph_properties[k] = new_p

976 977 978
            if not (vprune or eprune or rprune):
                g.pop_filter(vertex=vprune, edge=vprune, reversed=rprune)

Tiago Peixoto's avatar
Tiago Peixoto committed
979 980
            self.__stashed_filter_state = [self.get_filter_state()]

981 982 983
            if not vprune:
                v_filt, v_rev = g.__filter_state["vertex_filter"]
                if v_filt != None:
984
                    if v_filt not in list(g.vertex_properties.values()):
985 986 987 988
                        new_filt = self.new_vertex_property("bool")
                        self.copy_property(v_filt, new_filt)

                    else:
989
                        for k, v in g.vertex_properties.items():
990 991 992 993 994 995 996
                            if v == v_filt:
                                new_filt = self.vertex_properties[k]
                    self.__stashed_filter_state[0]["vertex_filter"] = (new_filt,
                                                                       v_rev)
            if not eprune:
                e_filt, e_rev = g.__filter_state["edge_filter"]
                if e_filt != None:
997
                    if e_filt not in list(g.edge_properties.values()):
998 999 1000 1001
                        new_filt = self.new_edge_property("bool")
                        self.copy_property(e_filt, new_filt)

                    else:
1002
                        for k, v in g.edge_properties.items():
1003 1004 1005 1006 1007 1008 1009 1010 1011 1012
                            if v == e_filt:
                                new_filt = self.edge_properties[k]
                    self.__stashed_filter_state[0]["edge_filter"] = (new_filt,
                                                                     e_rev)
            if not rprune:
                self.__stashed_filter_state[0]["reversed"] = g.is_reversed()

            # directedness is always a filter
            self.__stashed_filter_state[0]["directed"] = g.is_directed()

Tiago Peixoto's avatar
Tiago Peixoto committed
1013
            self.pop_filter()
1014

Tiago Peixoto's avatar
Tiago Peixoto committed
1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025
        # internal index maps
        self.__vertex_index = \
                 PropertyMap(libcore.get_vertex_index(self.__graph), self, "v")
        self.__edge_index = \
                 PropertyMap(libcore.get_edge_index(self.__graph), self, "e")

        # modification permissions
        self.__perms = {"add_edge": True, "del_edge": True,
                        "add_vertex": True, "del_vertex": True}

    def copy(self):
1026 1027
        """Return a deep copy of self. All :ref:`internal property maps <sec_internal_props>`
        are also copied."""
Tiago Peixoto's avatar
Tiago Peixoto committed
1028 1029 1030
        return Graph(self)

    def __repr__(self):
1031
        # provide more useful information
Tiago Peixoto's avatar
Tiago Peixoto committed
1032 1033 1034
        d = "directed" if self.is_directed() else "undirected"
        fr = ", reversed" if self.is_reversed() and self.is_directed() else ""
        f = ""
1035
        if self.get_edge_filter()[0] is not None:
Tiago Peixoto's avatar
Tiago Peixoto committed
1036
            f += ", edges filtered by %s" % (str(self.get_edge_filter()))
1037
        if self.get_vertex_filter()[0] is not None:
Tiago Peixoto's avatar
Tiago Peixoto committed
1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053
            f += ", vertices filtered by %s" % (str(self.get_vertex_filter()))
        n = self.num_vertices()
        e = self.num_edges()
        return "<%s object, %s%s, with %d %s and %d edge%s%s at 0x%x>"\
               % (type(self).__name__, d, fr, n,
                  "vertex" if n == 1 else "vertices", e, "" if e == 1 else "s",
                  f, id(self))

    # Graph access
    # ============

    def __check_perms(self, ptype):
        if not self.__perms[ptype]:
            raise RuntimeError("the graph cannot be modified at this point!")

    def vertices(self):
1054 1055 1056 1057 1058 1059 1060
        """Return an :meth:`iterator <iterator.__iter__>` over the vertices.

        .. note::

           The order of the vertices traversed by the iterator **always**
           corresponds to the vertex index ordering, as given by the
           :attr:`~graph_tool.Graph.vertex_index` property map.
Tiago Peixoto's avatar
Tiago Peixoto committed
1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072

        Examples
        --------
        >>> g = gt.Graph()
        >>> vlist = g.add_vertex(5)
        >>> vlist2 = []
        >>> for v in g.vertices():
        ...     vlist2.append(v)
        ...
        >>> assert(vlist == vlist2)

        """
1073
        return libcore.get_vertices(weakref.ref(self))
Tiago Peixoto's avatar
Tiago Peixoto committed
1074 1075 1076 1077 1078 1079 1080 1081

    def vertex(self, i, use_index=True):
        """Return the vertex with index ``i``. If ``use_index=False``, the
        ``i``-th vertex is returned (which can differ from the vertex with index
        ``i`` in case of filtered graphs). """
        if use_index:
            self.stash_filter(vertex=True)
        try:
1082
            v = libcore.get_vertex(weakref.ref(self), int(i))
Tiago Peixoto's avatar
Tiago Peixoto committed
1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108
        finally:
            if use_index:
                self.pop_filter(vertex=True)
        return v

    def edge(self, s, t, all_edges=False):
        """Return the edge from vertex ``s`` to ``t``, if it exists. If
        ``all_edges=True`` then a list is returned with all the parallel edges
        from ``s`` to ``t``, otherwise only one edge is returned.

        This operation will take :math:`O(k(s))` time, where :math:`k(s)` is the
        out-degree of vertex :math:`s`.
        """
        s = self.vertex(int(s))
        t = self.vertex(int(t))
        edges = []
        for e in s.out_edges():
            if e.target() == t:
                if not all_edges:
                    return e
                edges.append(e)
        if all_edges:
            return edges
        return None

    def edges(self):
1109 1110 1111 1112 1113
        """Return an :meth:`iterator <iterator.__iter__>` over the edges.

        .. note::

           The order of the edges traversed by the iterator **does not**
Tiago Peixoto's avatar
Tiago Peixoto committed
1114
           necessarily correspond to the edge index ordering, as given by the
1115 1116 1117 1118 1119 1120 1121
           :attr:`~graph_tool.Graph.edge_index` property map. This will only
           happen after :meth:`~graph_tool.Graph.reindex_edges` is called, or in
           certain situations such as just after a graph is loaded from a
           file. However, further manipulation of the graph may destroy the
           ordering.

        """
1122
        return libcore.get_edges(weakref.ref(self))
Tiago Peixoto's avatar
Tiago Peixoto committed
1123 1124 1125

    def add_vertex(self, n=1):
        """Add a vertex to the graph, and return it. If ``n > 1``, ``n``
1126
        vertices are inserted and an iterator over the new vertices is returned."""
Tiago Peixoto's avatar
Tiago Peixoto committed
1127
        self.__check_perms("add_vertex")
1128 1129 1130 1131 1132 1133
        v = libcore.add_vertex(weakref.ref(self), n)

        if n <= 1:
            return v
        else:
            pos = self.num_vertices() - n
1134
            return (self.vertex(i) for i in range(pos, pos + n))
Tiago Peixoto's avatar
Tiago Peixoto committed
1135 1136 1137 1138

    def remove_vertex(self, vertex):
        """Remove a vertex from the graph."""
        self.__check_perms("del_vertex")
1139
        vertex = self.vertex(int(vertex))
Tiago Peixoto's avatar
Tiago Peixoto committed
1140 1141
        index = self.vertex_index[vertex]
        for pmap in self.__known_properties:
1142
            if pmap[0] == "v" and pmap[1]() != None and pmap[1]().is_writable():
Tiago Peixoto's avatar
Tiago Peixoto committed
1143 1144 1145 1146 1147 1148 1149 1150
                self.__graph.ShiftVertexProperty(pmap[1]().get_map(), index)
        self.clear_vertex(vertex)
        libcore.remove_vertex(self.__graph, vertex)

    def remove_vertex_if(self, predicate):
        """Remove all the vertices from the graph for which ``predicate(v)``
        evaluates to ``True``. """
        N = self.num_vertices()
1151
        for i in range(0, N):
Tiago Peixoto's avatar
Tiago Peixoto committed
1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167
            v = self.vertex(N - i - 1)
            if predicate(v):
                self.remove_vertex(v)

    def clear_vertex(self, vertex):
        """Remove all in and out-edges from the given vertex."""
        del_es = set()
        for e in vertex.all_edges():
            del_es.add(e)
        for e in del_es:
            self.remove_edge(e)

    def add_edge(self, source, target):
        """Add a new edge from ``source`` to ``target`` to the graph, and return
        it."""
        self.__check_perms("add_edge")
1168 1169
        e = libcore.add_edge(weakref.ref(self), self.vertex(int(source)),
                             self.vertex(int(target)))
1170 1171 1172 1173
        efilt = self.get_edge_filter()
        if efilt[0] is not None:
            efilt[0][e] = not efilt[1]
        return e
Tiago Peixoto's avatar
Tiago Peixoto committed
1174 1175 1176 1177

    def remove_edge(self, edge):
        """Remove an edge from the graph."""
        self.__check_perms("del_edge")
Tiago Peixoto's avatar
Tiago Peixoto committed
1178
        return libcore.remove_edge(self.__graph, edge)
Tiago Peixoto's avatar
Tiago Peixoto committed
1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214

    def remove_edge_if(self, predicate):
        """Remove all edges from the graph, for which ``predicate(e)`` evaluates
        to ``True``."""
        for v in self.vertices():
            del_es = []
            for e in v.out_edges():
                if predicate(e):
                    del_es.append(e)
            for e in del_es:
                self.remove_edge(e)

    def clear(self):
        """Remove all vertices and edges from the graph."""
        self.__check_perms("del_vertex")
        self.__check_perms("del_edge")
        self.__graph.Clear()

    def clear_edges(self):
        """Remove all edges from the graph."""
        self.__check_perms("del_edge")
        self.__graph.ClearEdges()

    # Internal property maps
    # ======================

    # all properties
    def __get_properties(self):
        return PropertyDict(self, self.__properties,
                            lambda g, k: g.__properties[k],
                            lambda g, k, v: g.__set_property(k[0], k[1], v),
                            lambda g, k: g.__del_property(k[0], k[1]))

    @_limit_args({"t": ["v", "e", "g"]})
    @_require("k", str)
    def __set_property(self, t, k, v):
1215 1216 1217 1218 1219 1220
        if t == "g" and not isinstance(v, PropertyMap):
            self.__properties[(t, k)][self] = v
        else:
            if t != v.key_type():
                raise ValueError("wrong key type for property map")
            self.__properties[(t, k)] = v
Tiago Peixoto's avatar
Tiago Peixoto committed
1221 1222 1223 1224 1225 1226 1227 1228 1229 1230

    @_limit_args({"t": ["v", "e", "g"]})
    @_require("k", str)
    def __del_property(self, t, k):
        del self.__properties[(t, k)]

    properties = property(__get_properties,
                          doc=
    """Dictionary of internal properties. Keys must always be a tuple, where the
    first element if a string from the set {'v', 'e', 'g'}, representing a
1231 1232
    vertex, edge or graph property, respectively, and the second element is the
    name of the property map.
Tiago Peixoto's avatar
Tiago Peixoto committed
1233 1234 1235 1236 1237 1238 1239 1240 1241

    Examples
    --------
    >>> g = gt.Graph()
    >>> g.properties[("e", "foo")] = g.new_edge_property("vector<double>")
    >>> del g.properties[("e", "foo")]
    """)

    def __get_specific_properties(self, t):
1242
        props = dict([(k[1], v) for k, v in self.__properties.items() \
1243
                      if k[0] == t])
Tiago Peixoto's avatar
Tiago Peixoto committed
1244 1245 1246 1247 1248 1249 1250 1251 1252
        return props

    # vertex properties
    def __get_vertex_properties(self):
        return PropertyDict(self, self.__get_specific_properties("v"),
                            lambda g, k: g.__properties[("v", k)],
                            lambda g, k, v: g.__set_property("v", k, v),
                            lambda g, k: g.__del_property("v", k))
    vertex_properties = property(__get_vertex_properties,
1253
                                 doc="Dictionary of internal vertex properties. The keys are the property names.")
1254 1255
    vp = property(__get_vertex_properties,
                  doc="Alias to :attr:`~Graph.vertex_properties`.")
Tiago Peixoto's avatar
Tiago Peixoto committed
1256 1257 1258 1259 1260 1261 1262 1263

    # edge properties
    def __get_edge_properties(self):
        return PropertyDict(self, self.__get_specific_properties("e"),
                            lambda g, k: g.__properties[("e", k)],
                            lambda g, k, v: g.__set_property("e", k, v),
                            lambda g, k: g.__del_property("e", k))
    edge_properties = property(__get_edge_properties,
1264
                                 doc="Dictionary of internal edge properties. The keys are the property names.")
Tiago Peixoto's avatar
Tiago Peixoto committed
1265
    ep = property(__get_edge_properties,
1266
                  doc="Alias to :attr:`~Graph.edge_properties`.")
Tiago Peixoto's avatar
Tiago Peixoto committed
1267 1268 1269 1270

    # graph properties
    def __get_graph_properties(self):
        return PropertyDict(self, self.__get_specific_properties("g"),
1271
                            lambda g, k: g.__properties[("g", k)][g],
Tiago Peixoto's avatar
Tiago Peixoto committed
1272 1273 1274
                            lambda g, k, v: g.__set_property("g", k, v),
                            lambda g, k: g.__del_property("g", k))
    graph_properties = property(__get_graph_properties,
1275
                                 doc="Dictionary of internal graph properties. The keys are the property names.")
1276 1277
    gp = property(__get_graph_properties,
                  doc="Alias to :attr:`~Graph.graph_properties`.")
Tiago Peixoto's avatar
Tiago Peixoto committed
1278

1279 1280 1281 1282
    def own_property(self, prop):
        """'Own' property map 'prop', which may belong to another graph."""
        return PropertyMap(prop._PropertyMap__map, self, prop.key_type())

Tiago Peixoto's avatar
Tiago Peixoto committed
1283
    def list_properties(self):
1284
        """Print a list of all internal properties.
Tiago Peixoto's avatar
Tiago Peixoto committed
1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301

        Examples
        --------
        >>> g = gt.Graph()
        >>> g.properties[("e", "foo")] = g.new_edge_property("vector<double>")
        >>> g.vertex_properties["foo"] = g.new_vertex_property("double")
        >>> g.vertex_properties["bar"] = g.new_vertex_property("python::object")
        >>> g.graph_properties["gnat"] = g.new_graph_property("string", "hi there!")
        >>> g.list_properties()
        gnat           (graph)   (type: string, val: hi there!)
        bar            (vertex)  (type: python::object)
        foo            (vertex)  (type: double)
        foo            (edge)    (type: vector<double>)
        """

        if len(self.__properties) == 0:
            return
1302
        w = max([len(x[0]) for x in list(self.__properties.keys())]) + 4
Tiago Peixoto's avatar
Tiago Peixoto committed
1303 1304
        w = w if w > 14 else 14

1305
        for k, v in self.__properties.items():
Tiago Peixoto's avatar
Tiago Peixoto committed
1306
            if k[0] == "g":
1307 1308 1309
                print("%%-%ds (graph)   (type: %%s, val: %%s)" % w % \
                      (k[1], v.value_type(), str(v[self])))
        for k, v in self.__properties.items():
Tiago Peixoto's avatar
Tiago Peixoto committed
1310
            if k[0] == "v":
1311 1312 1313
                print("%%-%ds (vertex)  (type: %%s)" % w % (k[1],
                                                            v.value_type()))