email_graph 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 60c190e3910f79ec5129c9cca0b0227b87390e68
+  data.tar.gz: 2fe939d783d01402f1acecd9fac40aeda554d815
+SHA512:
+  metadata.gz: 53e992b88cff05752d47163afb3d0f0d26c71eb788f3f4c75e67f722a8ff3a325a1b2016e1ac17644571d79a98b8089a2be64cfeae45d862e1e3e7daf27a4232
+  data.tar.gz: 97e5b6f60728506c480982ea02de8a921012daef7a1100632c90f5d0fba9ad1e06a25cf960319b1bfa678dcacf9131889f50d5063ac25f9132edef622418d19c

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in email_graph.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Ryan Dick
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,152 @@
+# EmailGraph
+
+Build and analyze graph data structures from email history.
+
+Focus is on identities and interactions between them, for example:
+  * Who do I email with the most?
+  * Who are my strong contacts, as identified by some two-way interaction
+    threshold function?
+  * What is the distribution of my email interactions with a given person over
+    time?
+
+Subject lines and message bodies are currently ignored for simplification.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'email_graph'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install email_graph
+
+## Graph types
+
+There are two types of graphs to be built from email data.
+
+### 1. Interaction graph
+
+Class: `EmailGraph::InteractionGraph`
+
+This is a directed graph where each vertex is an email address and each edge is
+an instance of `EmailGraph::InteractionRelationship` - a directed interaction
+history between two emails.
+
+The graph has these properties:
+  * Implements common graph methods (e.g., `#vertices`, `#edges`, etc)
+  * Efficient fetching of vertices' in-edges (not always a default of graph
+    structures)
+  * Loops allowed
+
+Given a message, an interaction is created from the sender to every address in
+the `to`, `cc`, and `bcc` fields - there is no distinction among the latter.
+
+`EmailGraph::InteractionRelationship` objects have an `interactions` attribute,
+which holds an array of the `Time` objects of the interactions.
+
+Example:
+
+```ruby
+# Assuming you have an array 'messages' of message-like objects (see below for
+# how to use the Gmail fetcher)
+g = EmailGraph::InteractionGraph.new
+messages.each{ |m| g.add_message(m) }
+
+# ...or...
+
+g = EmailGraph::InteractionGraph.new(messages: messages)
+
+# For example, see a sorted list of your email contacts by emails sent
+g.edges_from("your@emailhere.com")
+  .sort_by{ |e| -e.interactions.size }
+  .map{ |e| [e.to, e.interactions.size] }
+```
+
+### 2. Mutual relationship graph
+
+Class: `EmailGraph::UndirectedGraph` (just uses the abstract class)
+
+This is an undirected graph where each vertex is also an email, however, this
+time, the edges are instances of `EmailGraph::MutualRelationship` - an
+undirected edge that similarly includes an interaction history (though an
+undirected one).
+
+This graph is created from an `EmailGraph::InteractionGraph` by creating
+undirected edges from pairs of directed edge inverses. Optionally, a filter can
+be applied during this process to determine whether an undirected edge is
+created for a given pair of directed edges.
+
+```ruby
+g = EmailGraph::InteractionGraph.new(messages: messages)
+
+# This creates the graph using the default filter, which is that an edge has to
+# have an inverse in order to create a new undirected edge.
+mg = g.to_mutual_graph
+
+# Alternatively, you can specify a custom filter. For example, this replicates
+# the one used by A. Chapanond et al. in their analysis of emails* from the Enron
+# case data set
+filter = Proc.new do |e, e_inverse|
+  if e && e_inverse
+    counts = [e.interactions.size, e_inverse.interactions.size]
+    counts.all?{ |c| c >= 6 } && counts.inject(:+) >= 30
+  else
+    false
+  end
+end
+mg = g.to_mutual_graph(&filter)
+```
+
+\*Chapanond, Anurat, Mukkai S. Krishnamoorthy, and Bülent Yener. "Graph theoretic
+and spectral analysis of Enron email data." Computational & Mathematical
+Organization Theory 11.3 (2005): 265-281.
+
+## Email normalization
+
+You'll likely want to normalize email addresses before adding them to a graph.
+Otherwise, you'll end up with separate vertices for different capitalizations of
+the same address - not to mention differences with '.' placement and other
+issues.
+
+`EmailGraph::InteractionGraph` will do this by default using SoundCloud's
+[Normailize](https://github.com/soundcloud/normailize) gem.
+
+You can also pass your own email processing block on instantiation for the
+entire graph, or when calling `#add_message`.
+
+## Fetching emails
+
+A fetcher for Gmail is included for convenience.
+
+```ruby
+g = EmailGraph::InteractionGraph.new
+
+email = "XXX"
+# You'll need an OAuth2 access token with Gmail permissions. One way to get one
+# is to use the Google Oauth Playground (https://developers.google.com/oauthplayground/)
+# and under "Gmail API v1" authorize "https://mail.google.com/".
+access_token = "XXX"
+
+f = EmailGraph::GmailFetcher::Fetcher.new( email: email,
+                                           access_token: access_token )
+
+# This should cover all emails from that account. If no mailbox param is
+# provided, defaults to Inbox.
+mailboxes = ['[Gmail]/All Mail', '[Gmail]/Trash']
+f.each_message(mailboxes: mailboxes){ |m| g.add_message(m) }
+```
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/email_graph/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/email_graph.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'email_graph/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "email_graph"
+  spec.version       = EmailGraph::VERSION
+  spec.authors       = ["Ryan Dick"]
+  spec.email         = ["rmdick@gmail.com"]
+  spec.summary       = %q{Graph data from emails.}
+  spec.homepage      = "https://github.com/rymodi/email_graph"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency "normailize", '~> 0.0.1'
+
+  # For the GmailFetcher
+  spec.add_runtime_dependency "gmail_xoauth", '~> 0.4.1'
+
+  spec.add_development_dependency "bundler", "~> 1.7"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", '~> 3.1.0'
+end

data/lib/email_graph.rb

@@ -0,0 +1,7 @@
+require 'normailize'
+
+require 'email_graph/version'
+require 'email_graph/directed_graph'
+require 'email_graph/undirected_graph'
+require 'email_graph/interaction_graph'
+require 'email_graph/gmail_fetcher'

data/lib/email_graph/directed_graph.rb

@@ -0,0 +1,122 @@
+module EmailGraph
+
+  # Graph with single, directed edges between vertices; loops allowed.
+  #
+  # Has these additional specifications:
+  # - Vertices and edges are hashable objects; the latter should 
+  #   inherit from Edge
+  # - Efficient fetching of in-edges in addition to out
+  class DirectedGraph
+
+    def initialize
+      @from_store = {}
+      @to_store   = {}
+    end
+
+    # All vertices
+    def vertices
+      @from_store.keys
+    end
+
+    # All edges
+    def edges
+      @from_store.values.to_set.flatten
+    end
+
+    # A specific edge from +v+ to +w+
+    def edge(v, w)
+      (@from_store[v] || []).find{ |e| e.to == w }
+    end
+
+    # Out-edges from vertex +v+ 
+    def edges_from(v)
+      @from_store[v]
+    end
+
+    # In-edges to vertex +v+
+    def edges_to(v)
+      @to_store[v]
+    end
+
+    # Adds a vertex if it doesn't already exist and returns it
+    def add_vertex(v)
+      @from_store[v] ||= Set.new
+      @to_store[v]   ||= Set.new
+    end
+
+    # Adds an edge and associated vertices if they don't already
+    # exist and returns the edge
+    def add_edge(e)
+      add_vertex(e.from); add_vertex(e.to)
+      (@from_store[e.from].add?(e) && @to_store[e.to].add(e) && e) || edge(e.from, e.to)
+    end
+    
+    # Yields each edge and its inverse to the provided block.
+    #
+    # Option to provide edges; default is all edges.
+    # 
+    # A pair set is yielded only once (not again in reverse).
+    def with_each_edge_and_inverse(edges=nil, &block)
+      edges ||= self.edges
+
+      yielded_pairs = Set.new
+      edges.each do |e|
+        pair = Set.new([e.from, e.to])
+        if !yielded_pairs.include?(pair)
+          e_inverse = edge(e.to, e.from)
+          block.call(e, e_inverse)
+          yielded_pairs << pair
+        end
+      end
+    end
+
+    # Converts to an instance of EmailGraph::Undirected graph.
+    #
+    # The optional +edge_factory+ block should take a pair of an edge and its
+    # inverse (if it exists), and return either an undirected edge-ish or if there
+    # should be no edge between the two vertices, then return nil. If
+    # no block is passed, an +UndirectedEdge+ will be created if both the edge and
+    # its inverse exist.
+    #
+    # Only adds vertices that have edges, i.e., no isolated vertices in result.
+    def to_undirected(&edge_factory)
+      edge_factory ||= Proc.new{ |e1, e2| UndirectedEdge.new(e1.from, e1.to) if e1 && e2 }      
+
+      edges = Set.new
+      with_each_edge_and_inverse do |e, e_inverse|
+        new_edge = edge_factory.call(e, e_inverse)
+        edges.add(new_edge) if new_edge
+      end
+
+      UndirectedGraph.new.tap do |g|
+        edges.each{ |e| g.add_edge(e) } 
+      end
+    end
+ 
+  end
+
+  class DirectedEdge
+    attr_reader :from
+    attr_reader :to
+
+    def initialize(from, to)
+      raise ArgumentError, "Vertices cannot be falsy" unless from && to
+      @from = from
+      @to = to
+    end
+
+    def hash
+      from.hash ^ to.hash
+    end
+
+    def ==(other)
+      from == other.from && to == other.to
+    end
+    alias eql? ==
+
+    def to_s
+      "(#{from}-#{to})"
+    end
+  end
+    
+end

data/lib/email_graph/gmail_fetcher.rb

@@ -0,0 +1,102 @@
+require 'time'
+require 'net/imap'
+require 'gmail_xoauth'
+
+module EmailGraph
+  module GmailFetcher
+
+    class Fetcher
+      attr_accessor :batch_size, :email, :access_token
+
+      def initialize(email: nil, access_token: nil)
+        @email = email
+        @access_token = access_token
+        @batch_size = 500
+      end
+
+      def count_messages(mailboxes: ['INBOX'])
+        mailboxes.inject(0){ |r, m| r + imap.status(m, ['MESSAGES'])['MESSAGES'] }
+      end
+
+      def each_message(mailboxes: ['INBOX'], batch_size: nil)
+        each_envelope(mailboxes: mailboxes, batch_size: batch_size) do |e|
+          m = Message.from_net_imap_envelope(e)
+          yield m if block_given?
+        end
+      end
+
+      def each_envelope(mailboxes: ['INBOX'], batch_size: nil)
+        mailboxes.each do |mailbox|
+          # Needed before fetching
+          imap.examine(mailbox)
+
+          batch_size ||= @batch_size
+          limit = count_messages(mailboxes: [mailbox])
+
+          (1..limit).each_slice(batch_size) do |range|
+            envelope_batch = imap.fetch(range, 'ENVELOPE') || []
+            envelope_batch.each{ |e| yield e if block_given? }
+            puts "Fetched #{range.last}/#{limit}"
+          end
+        end
+      end
+
+      def imap_connect
+        Net::IMAP.new('imap.gmail.com', 993, usessl = true, certs = nil, verify = false).tap do |imap|
+          imap.authenticate('XOAUTH2', email, access_token)
+        end
+      end
+
+      def imap
+        @imap ||= imap_connect
+      end
+      
+    end
+
+    Message = Struct.new(:from, :to, :cc, :bcc, :date) do
+
+      def initialize(**kwargs)
+        kwargs.each{ |k, v| self[k] = v }
+      end
+      
+      # @param e [+Net::IMAP::Envelope+]
+      # @return [Message]
+      def self.from_net_imap_envelope(e)
+        addresses_by_field = {}
+        address_fields = [:from, :to, :cc, :bcc]
+        address_fields.each do |field|
+          addresses = e.attr['ENVELOPE'].send(field) || []
+          addresses_by_field[field] = addresses.map{ |a| Address.from_net_imap_address(a) }
+        end
+        
+        date_raw = e.attr['ENVELOPE'].date
+        date = nil
+        begin
+          date = Time.parse(date_raw) if date_raw
+        rescue ArgumentError
+          # Observed cases:
+          # - date_raw == "{DATE}"
+          # - Time.parse raises 'ArgumentError: argument out of range'
+        end
+
+        new(**addresses_by_field, date: date)
+      end
+    end
+
+    Address = Struct.new(:name, :email) do
+
+      def initialize(**kwargs)
+        kwargs.each{ |k, v| self[k] = v }
+      end
+
+      # @param a [Net::IMAP::Address]
+      # @return [Address]
+      def self.from_net_imap_address(a)
+        new( name:  a.name, 
+             email: "#{a.mailbox}@#{a.host}" )
+      end
+
+    end
+
+  end
+end

data/lib/email_graph/interaction_graph.rb

@@ -0,0 +1,114 @@
+module EmailGraph
+  
+  # Directed graph of identities and their relationships, created by parsing
+  # messages.
+  class InteractionGraph < DirectedGraph
+
+    # @param messages [Array<#from, #to, #cc, #bcc, #date>] optional 
+    #   message-like objects. See {#add_message} for specification.
+    # @param email_processor [Proc] block that should return a processed email
+    #   when passed an unprocessed one. Defaults to #default_email_processor; pass
+    #   +Proc.new{ |e| e }+ for no processing.
+    def initialize(messages: [], email_processor: nil)
+      super()
+      @email_processor = email_processor || default_email_processor
+
+      messages.each{ |m| add_message(m) }
+    end
+
+    # Adds a message to the graph.
+    #
+    # @param m [#from, #to, #cc, #bcc, #date] message-like object. Field methods
+    #   should return an array of objects that respond to #name and #email;
+    #   #date should return an instance of +Time+.
+    # @param email_processor [Proc] block that should return a processed email
+    #   when passed an unprocessed one. Pass +Proc.new{ |e| e }+ for no processing.
+    # @return m param
+    def add_message(m, email_processor: nil)
+      email_processor ||= @email_processor
+
+      # Fields are in prioritized order (e.g., if in 'to', don't process again in 'cc')
+      to_emails = []
+      [:to, :cc, :bcc].each do |field|
+        addresses = m.send(field) || []
+        addresses.each do |a|
+          to = email_processor.call(a.email)
+          unless to_emails.include?(to)
+            from ||= email_processor.call(m.from.first.email)
+             
+            add_interaction(from, to, m.date)
+             
+            to_emails << to
+          end
+        end
+      end
+
+      m
+    end
+
+    # Converts graph into an undirected one, where edges are mutual relationships.
+    #
+    # The optional +edge_filter+ is used for determining the mutual relationship
+    # threshold based on the edge pair. It should take an edge and its inverse as
+    # arguments and return true if a +MutualRelationship+ should be created.
+    def to_mutual_graph(&edge_filter)
+      edge_filter ||= Proc.new{ |e, e_inverse| e && e_inverse }
+
+      edge_factory = Proc.new do |e, e_inverse|
+        if edge_filter.call(e, e_inverse)
+          MutualRelationship.new(e.from, e.to).tap do |r|
+            r.interactions.push(*(e.interactions + e_inverse.interactions))
+          end
+        end
+      end
+
+      to_undirected(&edge_factory)
+    end
+
+    def default_email_processor
+      Proc.new do |email| 
+        begin
+          Normailize::EmailAddress.new(email).normalized_address
+        rescue ArgumentError
+          # Chokes on emails like "twitter-confirmation-blah=gmail.com@postmaster.twitter.com"
+          email.downcase
+        end
+      end
+    end
+
+  private
+
+    def add_interaction(from, to, date)
+      r = add_edge(InteractionRelationship.new(from, to))
+      r.add_interaction(date)
+    end
+
+  end
+
+  class InteractionRelationship < DirectedEdge
+    attr_reader :interactions
+
+    def initialize(from, to)
+      super
+      @interactions = []
+    end
+
+    def add_interaction(date)
+      interactions << date
+    end
+  end
+
+  class MutualRelationship < UndirectedEdge
+    attr_reader :interactions
+
+    def initialize(v, w)
+      super
+      @interactions = []
+    end
+    
+    def add_interaction(date)
+      interactions << date
+    end
+  end
+
+end

data/lib/email_graph/undirected_graph.rb

@@ -0,0 +1,67 @@
+module EmailGraph
+
+  class UndirectedGraph
+    
+    def initialize
+      @store = {}
+    end
+
+    # All vertices
+    def vertices
+      @store.keys
+    end
+
+    # All edges
+    def edges
+      @store.values.to_set.flatten
+    end
+     
+    # A specific edge from +v+ to +w+
+    def edge(v, w)
+      (@store[v] || []).find{ |e| e.vertices.include?(w) }
+    end
+
+    # Edges involving a vertex +v+
+    def edges_with(v)
+      @store[v]
+    end
+
+    # Adds a vertex if it doesn't already exist and returns it
+    def add_vertex(v)
+      @store[v] ||= Set.new
+    end
+
+    # Adds an edge and associated vertices if they don't already
+    # exist and returns the edge
+    def add_edge(e)
+      v, w = *e.vertices
+      edge(v, w) || e.vertices.each{ |v| add_vertex(v); @store[v].add(e)}
+    end
+
+  end
+
+  class UndirectedEdge
+    attr_reader :vertices
+    
+    def initialize(v, w)
+      raise ArgumentError, "Vertices cannot be falsy" unless v && w
+      @vertices = Set.new([v, w])
+    end
+    
+    def hash
+      @vertices.hash
+    end
+
+    def ==(other)
+      @vertices == other.vertices
+    end
+    alias eql? ==
+
+    def to_s
+      a = @vertices.to_a
+      "(#{a[0]}-#{a[1]})"
+    end
+
+  end
+
+end

data/lib/email_graph/version.rb

@@ -0,0 +1,3 @@
+module EmailGraph
+  VERSION = "0.0.1"
+end

data/spec/directed_graph_spec.rb

@@ -0,0 +1,90 @@
+require 'spec_helper'
+
+describe EmailGraph::DirectedGraph do
+  let(:edge_pairs) {[ [1, 2],
+                      [2, 1],
+                      [2, 3] ]}
+  let(:edges) { edge_pairs.map{ |p| EmailGraph::DirectedEdge.new(p[0], p[1]) } }
+  let(:g) do
+    EmailGraph::DirectedGraph.new.tap do |g| 
+      edges.each{ |e| g.add_edge(e) }
+      g.add_vertex(4)
+    end
+  end
+
+  it 'returns all vertices' do
+    expect(g.vertices).to contain_exactly(1, 2, 3, 4)
+  end
+
+  it 'returns all edges' do
+    expect(g.edges).to contain_exactly(*edges)
+  end
+
+  it 'returns a specific edge' do
+    expect(g.edge(1,2)).to eq(EmailGraph::DirectedEdge.new(1,2))
+  end
+
+  it 'returns edges from a vertex' do
+    expect(g.edges_from(2).map(&:to)).to contain_exactly(1, 3)
+  end
+
+  it 'returns edges to a vertex' do
+    expect(g.edges_to(2).map(&:from)).to contain_exactly(1)
+  end
+
+  it 'returns existing edge when trying to add one with the same vertices' do
+    e = NewDirectedEdgeType.new(2, 3)
+
+    expect(g.add_edge(e)).to be_instance_of(EmailGraph::DirectedEdge)
+  end
+
+  it 'iterates through each edge and its inverse' do
+    expected_yield = [ [g.edge(1, 2), g.edge(2, 1)],
+                       [g.edge(2, 3), nil] ]
+
+    expect{ |b| g.with_each_edge_and_inverse(&b) }.to yield_successive_args(*expected_yield)
+  end
+
+  describe '#to_undirected' do
+    
+    it 'returns with the correct edges and vertices using default edge_factory' do
+      undirected = g.to_undirected
+
+      expected_edges = [EmailGraph::UndirectedEdge.new(1, 2)]
+      expect(undirected.edges).to contain_exactly(*expected_edges)
+
+      expected_vertices = [1, 2]
+      expect(undirected.vertices).to contain_exactly(*expected_vertices)
+    end
+
+    it 'returns with the correct edges when using a provided edge_factory' do
+      at_least_one_way_edge_factory = Proc.new{ |e1, e2| EmailGraph::UndirectedEdge.new(e1.from, e1.to) if e1 }
+
+      undirected = g.to_undirected(&at_least_one_way_edge_factory)
+
+      expected_edges = [ EmailGraph::UndirectedEdge.new(1, 2),
+                         EmailGraph::UndirectedEdge.new(2, 3) ]
+      expect(undirected.edges).to contain_exactly(*expected_edges)
+
+      expected_vertices = [1, 2, 3]
+      expect(undirected.vertices).to contain_exactly(*expected_vertices)
+    end
+
+  end
+
+end
+
+describe EmailGraph::DirectedEdge do
+
+  it 'raises when a vertex is nil' do
+    expect{ EmailGraph::DirectedEdge.new(nil, 1) }.to raise_exception(ArgumentError)
+  end
+
+  it 'converts into a string' do
+    edge = EmailGraph::DirectedEdge.new("v", "w")
+    expect(edge.to_s).to eq("(v-w)")
+  end
+
+end
+
+class NewDirectedEdgeType < EmailGraph::DirectedEdge; end

data/spec/interaction_graph_spec.rb

@@ -0,0 +1,90 @@
+require 'spec_helper'
+require 'ostruct'
+
+describe EmailGraph::InteractionGraph do
+  let(:a0) { OpenStruct.new(name: "a0", email: "a0@example.com") }
+  let(:a1) { OpenStruct.new(name: "a1", email: "a1@example.com") }
+  let(:msg) { OpenStruct.new(from: [a0], to: [a1], date: Time.now) }
+  let(:g) { EmailGraph::InteractionGraph.new }
+
+  describe '#add_message' do
+
+    it 'adds vertices (identities)' do 
+      g.add_message(msg)
+
+      expect(g.vertices).to contain_exactly(a0.email, a1.email)
+    end
+
+    it 'adds edges (relationships)' do
+      g.add_message(msg)
+
+      expected_edge = EmailGraph::InteractionRelationship.new(a0.email, a1.email)
+      expect(g.edges).to contain_exactly(expected_edge)
+    end
+
+    it 'adds interactions to relationships' do
+      g.add_message(msg)
+
+      expect(g.edge(a0.email, a1.email).interactions).to contain_exactly(msg.date)
+    end
+
+    it 'adds interactions ignoring duplicates' do
+      msg_with_dups = OpenStruct.new( from: [a0],
+                                      to:   [a1],
+                                      cc:   [a1], 
+                                      date: Time.now )
+
+      g.add_message(msg_with_dups)
+
+      expect(g.edge(a0.email, a1.email).interactions).to contain_exactly(msg_with_dups.date)
+    end
+
+    it 'raises when message addresses have nil emails' do
+      nil_email = OpenStruct.new(name: "Nil Email", email: nil)
+    
+      msg_with_nil_email = OpenStruct.new( from: [a0],
+                                           to:   [nil_email],
+                                           date: Time.now )
+
+      expect{g.add_message(msg_with_nil_email)}.to raise_exception(ArgumentError)
+    end
+
+    it 'normalizes emails if no processor is provided' do
+      a_norm = OpenStruct.new(name: "Norm", email: "test@gmail.com")
+      a_not_norm = OpenStruct.new(name: "Not Norm", email: "tEs.t+blah@gmail.com")
+
+      msg = OpenStruct.new(from: [a_norm], to: [a_not_norm], date: Time.now)
+      g.add_message(msg)
+
+      expected_edge = EmailGraph::InteractionRelationship.new('test@gmail.com', 'test@gmail.com')
+      expect(g.edges).to contain_exactly(expected_edge)
+    end
+
+    it 'processes emails if a processor is provided' do
+      processor = Proc.new{ |e| "EMAIL@EMAIL.COM" }
+      g.add_message(msg, email_processor: processor)  
+
+      expect(g.vertices).to contain_exactly("EMAIL@EMAIL.COM")
+    end
+
+  end
+
+  describe '#to_mutual_graph' do
+    
+    it 'returns with the correct edges and vertices using default filter' do
+      g.add_message(msg)
+      g.add_message(OpenStruct.new(from: [a1], to: [a0], date: Time.now))
+      mutual_graph = g.to_mutual_graph
+
+      expected_edges = [EmailGraph::MutualRelationship.new(a0.email, a1.email)]
+      expect(mutual_graph.edges).to contain_exactly(*expected_edges)
+
+      expected_vertices = [a0.email, a1.email]
+      expect(mutual_graph.vertices).to contain_exactly(*expected_vertices)
+
+      expect(mutual_graph.edge(a0.email, a1.email).interactions.size).to eq(2)
+    end
+
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1 @@
+require_relative '../lib/email_graph.rb'

data/spec/undirected_graph_spec.rb

@@ -0,0 +1,53 @@
+require 'spec_helper'
+
+describe EmailGraph::UndirectedGraph do
+  let(:edge_pairs) {[ [1, 2],
+                      [2, 3] ]}
+  let(:edges) { edge_pairs.map{ |p| EmailGraph::UndirectedEdge.new(p[0], p[1]) } }
+  let(:g) do
+    EmailGraph::UndirectedGraph.new.tap do |g|
+      edges.each{ |e| g.add_edge(e) }
+      g.add_vertex(4)
+    end
+  end 
+
+  it 'returns all vertices' do
+    expect(g.vertices).to contain_exactly(1, 2, 3, 4)
+  end
+
+  it 'returns all edges' do
+    expect(g.edges).to contain_exactly(*edges)
+  end
+
+  it 'returns a specific edge, vertex order ignored' do
+    expected_edge = EmailGraph::UndirectedEdge.new(1,2)
+    expect(g.edge(2, 1)).to eq(expected_edge)
+  end
+
+  it 'returns edges involving a vertex' do
+    expected_edges = [EmailGraph::UndirectedEdge.new(2,3)]
+    expect(g.edges_with(3)).to contain_exactly(*expected_edges)
+  end
+
+  it 'returns an existing edge if available when adding one' do
+    e = NewUndirectedEdgeType.new(2, 3)
+
+    expect(g.add_edge(e)).to be_instance_of(EmailGraph::UndirectedEdge)
+  end
+
+end
+
+describe EmailGraph::UndirectedEdge do
+
+  it 'raises when a vertex is nil' do
+      expect{ EmailGraph::UndirectedEdge.new(nil, 1) }.to raise_exception(ArgumentError)
+  end
+
+  it 'converts into a string' do
+    edge = EmailGraph::UndirectedEdge.new("v", "w")
+    expect(edge.to_s).to match(/^\((v-w|w-v)\)$/)
+  end
+
+end
+
+class NewUndirectedEdgeType < EmailGraph::UndirectedEdge; end

metadata

@@ -0,0 +1,135 @@
+--- !ruby/object:Gem::Specification
+name: email_graph
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Ryan Dick
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-11-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: normailize
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.0.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.0.1
+- !ruby/object:Gem::Dependency
+  name: gmail_xoauth
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.4.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.4.1
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.1.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.1.0
+description: 
+email:
+- rmdick@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- email_graph.gemspec
+- lib/email_graph.rb
+- lib/email_graph/directed_graph.rb
+- lib/email_graph/gmail_fetcher.rb
+- lib/email_graph/interaction_graph.rb
+- lib/email_graph/undirected_graph.rb
+- lib/email_graph/version.rb
+- spec/directed_graph_spec.rb
+- spec/interaction_graph_spec.rb
+- spec/spec_helper.rb
+- spec/undirected_graph_spec.rb
+homepage: https://github.com/rymodi/email_graph
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Graph data from emails.
+test_files:
+- spec/directed_graph_spec.rb
+- spec/interaction_graph_spec.rb
+- spec/spec_helper.rb
+- spec/undirected_graph_spec.rb
+has_rdoc: