emailgraph(1)

NAME
emailgraph - Plot social graphs and usage information from email logs

SYNOPSIS
emailgraph [options]

DESCRIPTION
If you've been a netizen for some time then you've probably by now accumulated quite a lot of email. You can do basic kinds of search on your email archives, but it's also possible to do more sophisticated kinds of analysis which may reveal information which you weren't aware of and which (at least in 2012) isn't a routine feature of most email clients. emailgraph is a command line utility which can take email in the form of a mailbox file or a set of text files and produce social graphs and other types of graphical representation. You can also produce subgraphs based upon particular keywords, so that you can investigate networks of people talking about a particular topic. You can also restrict the search between dates or between particular times of day. Any dot file viewing program may be used to show the resulting graphs, such as Dotty , XDot or kgraphviewer.

INSTALLATION
The easiest way to install is from a pre-compiled package, a number of which are available at:
    https://build.opensuse.org/project/show?project=home%3Amotters%3Aemailgraph But if you prefer not to get involved with binaries then this program is pretty easy to compile and install as follows: make
sudo make install If you wish to generate a Debian package you can also run the following script: ./debian.sh To plot additional graphs you will need to have gnuplot installed. For example: sudo apt-get install gnuplot graphviz xdot

EXAMPLE SOCIAL GRAPHS
To create a social graph in dot format for an entire email archive: emailgraph -m mboxfile --dot > social_graph.dot An email stream may also be piped in from elsewhere, like this: cat mboxfile | emailgraph --dot > social_graph.dot You can also process multiple emails within a directory structure. This will recursively examine subdirectories and attempt to read all files within them: emailgraph -d emaildirectory --dot > social_graph.dot To produce an anonymized social graph. This is recommended if you are going to publish the graphs publicly and wish the names of individuals to remain private. emailgraph -m mboxfile --dot --nonames > social_graph.dot To limit between dates, where the date is given in dd/mm/yyyy format: emailgraph -m mboxfile --dot --start 20/1/2007 --end 30/5/2009 > social_graph.dot You can also specify a start date relative to the current date using the options: --start month/3month/6month/year/2year/3year/4year/5year Such as the following, to show a social graph for the previous 6 months: emailgraph -m mboxfile --dot --start 6month > social_graph.dot To limit between times of day (eg. within working hours): emailgraph -m mboxfile --dot --starthour 9 --endhour 17 > social_graph.dot To investigate graphs where participants are using particular keywords. Keywords are not case sensitive and can also include names or email addresses. Multiple keywords are separated by commas. emailgraph -m mboxfile --dot --keywords "foo,bar" > social_graph.dot You can also use the --min option to show only those individuals with more than a given number of interactions. The --corpus option may be used to print all emails which contain matching keywords. emailgraph -m mboxfile --keywords "foo,bar" --corpus > emails.txt Dot files may be viewed using other utilities, such as dotty, xdot or kgraphviewer. To visualize a graph using XDot: xdot social_graph.dot

MERGING CONTACTS
In some cases you may see multiple nodes in the social graph which correspond to the same person. This may be because their name is spelled differently, or because they have more then one email address. To make the graph neater and easier to interpret it is possible to manually specify the names or email addresses of individuals which you wish to be merged together. To do this create a merge file such as the following:
  J Smith,John Smith
  Clarke K,Clarke Kent
  Susan,Susan Jones In each case the first name is the name as it currently appears in the graph and the second is the name that you wish it to be changed to. Then use the --merge option, for example: emailgraph -m mboxfile --dot --merge mymerges.txt > social_graph.dot

EXCLUDING CONTACTS
Contacts can also be excluded from the social graph. This works in a similar manner to merging, but uses the --exclude option to specify a file containing names to be removed. Names are case sensitive. For example you could make a file like this:
  Kevin Killjoy
  Mr Trollalot
  Doctor Strangecode Then call emailgraph as follows: emailgraph -m mboxfile --dot --exclude banned.txt > social_graph.dot

EXAMPLE USAGE GRAPHS
In order for this to work you must have gnuplot installed. To plot email volume for each month, with a specified title: emailgraph -m mboxfile --plotmonthly monthly_emails.png --title "My graph title" To plot email volume for each day of the week: emailgraph -m mboxfile --plotweekly weekly_emails.png To plot email volume for each hour of the day: emailgraph -m mboxfile --plotdaily daily_emails.png To plot email volume for each year: emailgraph -m mboxfile --plotyearly yearly_emails.png To plot the average number of emails for each month of the year: emailgraph -m mboxfile --plotannual annual_emails.png To plot individual emails as points: emailgraph -m mboxfile --plotdensity email_density.png You can also combine this with keywords and date or time limits, as required.

SENTIMENT ANALYSIS
Usage and social graphs may also be produced for measurements of valence. For example the following plots monthly total valence values: emailgraph -m mboxfile --plotmonthly monthly.png --sentiment If you are only interested in negative valence you can also do: emailgraph -m mboxfile --plotmonthly monthly.png --sentimentneg Also social graph nodes may have their background shading altered depending upon the average valence values for emails sent by each individual: emailgraph -m mboxfile --dot --sentiment > social_graph.dot Here lighter background shades indicate more positive valence, and darker represent lower or more negative valence values.

OPTIONS

-m,--mbox
    Mailbox filename.

-d,--dir
    Directory to search for emails.

-c,--contacts
    Print contacts.

-t,--top
    Print the most active contacts.

-i,--influence
    Print contacts in order of influence.

--valence
    Print contacts in order of valence.

--sentiment
    Show valence in plots and social graphs.

--sentimentneg
    Show negative valence in plots and social graphs.

--start
    Start date in the format dd/mm/yyyy.

--end
    End date in the format dd/mm/yyyy.

--starthour
    Start time in hours (0-24).

--endhour
    End time in hours (0-24).

--dot
    Print in dot file format.

-w,--linewidth
    Maximum line width in dot file.

--nonames
    Don't use names within diagrams.

--monthly
    CSV containing monthly email volumes.

--yearly
    CSV containing yearly email volumes.

--daily
    CSV containing daily average email volume for each hour.

--weekly
    CSV containing weekly average email volume for each hour.

-s,--sentences
    Print sentences for subsequent semantic analysis.

--plotdensity
    Plot email density to an image file.

--plotdaily
    Plot daily email volumes to an image file.

--plotweekly
    Plot weekly email volumes to an image file.

--plotmonthly
    Plot monthly email volumes to an image file.

--plotannual
    Plot annual average email volumes to an image file.

--keywords
    Search for keywords.

--corpus
    Prints all emails which contain matching keywords.

--title
    Title to be added to a plot.

--min
    Minimum number of interactions.

--gender
    Select only males (M), females (F) or male/female interactions (MF).

--merge
    Specify a merge file containing contacts to be merged.

--exclude
    Specify an exclude file containing contacts to be removed.

--tests
    Run unit tests.

-v,--version
    Show version number.

-h,--help
    Show help.

BUGS
Report all bugs to https://github.com/fuzzgun/emailgraph/issues

SEE ALSO
gnuplot(1) graphviz(1)

AUTHOR
Bob Mottram <bob@robotics.uk.to>
http://robotics.uk.to