docs: def sigma(G, corpus, featureset_name, B=None, **kwargs):
      """
      Calculate sigma (from `Chen 2009 <http://arxiv.org/pdf/0904.1439.pdf>`_)
      for all of the nodes in a :class:`.GraphCollection`\.
  
      You can set parameters for burstness estimation using ``kwargs``:
  
      =========   ===============================================================
      Parameter   Description
      =========   ===============================================================
      s           Scaling parameter ( > 1.)that controls graininess of burst
                  detection. Lower values make the model more sensitive. Defaults
                  to 1.1.
      gamma       Parameter that controls the 'cost' of higher burst states.
                  Defaults to 1.0.
      k           Number of burst states. Defaults to 5.
      =========   ===============================================================
  
      Parameters
      ----------
      G : :class:`.GraphCollection`
      corpus : :class:`.Corpus`
      feature : str
          Name of a featureset in `corpus`.
  
  
      Examples
      --------
  
      Assuming that you have a :class:`.Corpus` generated from WoS data that has
      been sliced by ``date``.
  
      .. code-block:: python
  
         >>> # Generate a co-citation graph collection.
         >>> from tethne import GraphCollection
         >>> kwargs = { 'threshold':2, 'topn':100 }
         >>> G = GraphCollection()
         >>> G.build(corpus, 'date', 'papers', 'cocitation', method_kwargs=kwargs)
  
         >>> # Calculate sigma. This may take several minutes, depending on the
         >>> #  size of your co-citaiton graph collection.
         >>> from tethne.analyze.corpus import sigma
         >>> G = sigma(G, corpus, 'citations')
  
         >>> # Visualize...
         >>> from tethne.writers import collection
         >>> collection.to_dxgmml(G, '~/cocitation.xgmml')
  
      In the visualization below, node and label sizes are mapped to ``sigma``,
      and border width is mapped to ``citations``.
  
      .. figure:: _static/images/cocitation_sigma2.png
         :width: 600
         :align: center
  
      """
      if 'date' not in corpus.indices:
          corpus.index('date')
  
      # Calculate burstness if not provided.
      if not B:
          B = burstness(corpus, featureset_name, features=G.nodes(), **kwargs)
  
      Sigma = {}      # Keys are dates (from GraphCollection), values are
                      #  node:sigma dicts.
      for key, graph in G.iteritems():
          centrality = nx.betweenness_centrality(graph)
          sigma = {}  # Sigma values for all features in this year.
          attrs = {}  # Sigma values for only those features in this graph.
          for n_, burst in B.iteritems():
              burst = dict(list(zip(*burst)))     # Reorganize for easier lookup.
  
              # Nodes are indexed as integers in the GraphCollection.
              n = G.node_lookup[n_]
  
              # We have burstness values for years in which the feature ``n``
              #  occurs, and we have centrality values for years in which ``n``
              #  made it into the graph.
              if n in graph.nodes() and key in burst:
                  sigma[n] = ((centrality[n] + 1.) ** burst[key]) - 1.
                  attrs[n] = sigma[n]
  
          # Update graph with sigma values.
          nx.set_node_attributes(graph, 'sigma', attrs)
          Sigma[key] = sigma
  
      # Invert results and update the GraphCollection.master_graph.
      # TODO: is there a more efficient way to do this?
      inverse = defaultdict(dict)
      for gname, result in Sigma.iteritems():
          if hasattr(result, '__iter__'):
              for n, val in result.iteritems():
                  inverse[n].update({gname: val})
      nx.set_node_attributes(G.master_graph, 'sigma', inverse)
  
      # We want to return results in the same format as burstness(); with node
      #  labels as keys; values are tuples ([years...], [sigma...]).
      return {n: list(zip(*G.node_history(G.node_lookup[n], 'sigma').items()))
              for n in B.keys()}