Some Greek-letter organizations assign big brothers or big sisters ("bigs") to new members ("littles"). This program visualizes such relationships as a family tree, using Graphviz.
The simplest usage of snutree is:
snutree -o output.pdf input1.csv input2.csv ...In this example, the CSV should have columns called name, big_name, and
semester where semesters are strings starting with "Fall" or "Spring"
and ending with a year (e.g., "Fall 2014" or "Spring 1956"). With this input,
snutree will append all the input tables together, convert them into a
tree, and output the tree using Graphviz. Each member will be put on a row
representing the semester they joined.
The (name, big_name, semester) headers consist of the
"basic" schema. There are a few other schemas available. They are:
| Schema | Headers |
|---|---|
| basic | name, big_name, semester |
| keyed | id, name, big_id, semester |
| chapter | child, parent, founded |
| sigmanu | badge, first_name, preferred_name, last_name, big_badge, status, semester, affiliations |
Changing schemas can be done with the --schema option. For example, this
will print the DOT source code of a family tree of chapters to the terminal:
snutree --schema chapter chapters.csvA custom Python module may be used as a schema:
snutree --schema /home/example/custom.py input.csvCustom schema modules should validate the tables themselves and turn them into
an internal format snutree can read.
Input files can also be SQL queries. This will run the query in query.sql
on the database described in config.yaml and save the resulting tree to
output.pdf:
snutree --config config.yaml -o output.pdf query.sqlFor a SQL query, a YAML configuration file with appropriate authentication options must be provided. Here is an example of the contents of such a file:
readers:
sql:
host: '127.0.0.1'
port: 3306
user: 'root'
passwd: 'secret'
db: 'database_name'
# Credentials for tunneling queries through SSH
ssh:
host: 'example.com'
port: 22
user: 'example'
private_key: '/home/example/.ssh/id_rsa'Note that the query must rename the column headers to match the schema used.
usage: snutree [-h] [-o <path>] [-f <filetype>] [-t <filetype>] [-m <schema>]
[-w <writer>] [-c <path>] [-S <int>] [-l <path>] [-q] [-v] [-d]
[-V]
[<input> [<input> ...]]
Visualizes big-little brother/sister relationships in Greek-letter
organizations. Input file data is read from stdin and/or any provided
positional <input> arguments. Each input <filetype> has a corresponding
reader, which converts the file into a table of the given <schema> and adds it
to the rest of the input data. The <schema> module then turns the the
resulting table into a tree data structure. The tree is processed and finally
written to the output <path> using the given <writer> and output <filetype>.
Additional options can be provided in configuration files.
positional arguments:
<input> an input file path or '-' for stdin; default is stdin
optional arguments:
-h, --help show this help message and exit
-o <path>, --output <path>
the output file; default is stdout
-f <filetype>, --from <filetype>
expected filetype of stdin, which must be one of
{csv,dot,json,sql}; default is csv
-t <filetype>, --to <filetype>
filetype of the output file, which must be supported
by the writer; default is the output file's extension
(if known) or 'dot'
-m <schema>, --schema <schema>
member table schema, which must be in
{basic,chapter,keyed,sigmanu,*.py}; default is 'basic'
-w <writer>, --writer <writer>
writer module, which must be in
{dot,stats,table,*.py}; default is a guess based on
the output file format
-c <path>, --config <path>
configuration file <path(s)>; files listed earlier
override later ones
-S <int>, --seed <int>
random number generator seed, for moving tree nodes
around in a repeatable way
-l <path>, --log <path>
write logger output to the file at <path>
-q, --quiet write only errors to stderr; suppress warnings
-v, --verbose print more information to stderr
-d, --debug print debug-level information to stderr
-V, --version show program's version number and exit
There is also a simple GUI script called snutree-gui. It is a simple
wrapper over the command-line version and implements most of the command-line
features.
All of snutree's built-in readers and writers use UTF-8, and all of
snutree's configuration files should be encoded in UTF-8. Use iconv or
similar tools to convert to and from UTF-8 as needed.
These instructions are based on Ubuntu and Debian-based installations, but they can be made to apply to any Unix-like system (including macOS) with what should be minor modifications. (These instructions are also applicable to Windows, though after less minor modifications.)
First, install Python (>=3.5), Python's pip package manager, and Graphviz:
# apt install python3 python3-pip graphvizAt this point, python3, pip3, and dot should be in your PATH:
$ python3 --version
Python 3.X.X
$ pip3 --version
pip X.X.X from /path/to/python3/packages (python 3.5)
$ dot -V
dot - graphviz version X.XX.X (20XXXXXX.XXXX)Now install snutree with:
$ pip3 install --user snutreeThis will install snutree and its required Python dependencies to your home
directory. Make sure that ~/.local/bin is in your PATH. You might run
pip without the --user flag to install it system-wide, but this will
require root.
Since installation on Windows is less straightforward, Windows executables have
been compiled and are available here. After downloading the
executable, you must install Graphviz and add C:\Program Files
(x86)\GraphvizX.XX\bin (or equivalent) to your Windows PATH. You can now run
the command-line or GUI executables.
Use pip to install these packages for optional features:
gooey: Use the GUI versionmysqlclient: Allow reading from MySQL databasessshtunnel: Allow tunneling SQL queries through sshpydotplus: Allow reading data from DOT files (experimental)
All configuration is done in YAML (or JSON) files. In the terminal, these files
can be included with --config flags. Configuration files listed later
override those that came earlier and command line options override all
configuration files.
Below are all of the available options along with descriptions in the comments and default values where applicable.
readers: # reader module configuration
stdin: # standard input reader configuration
filetype: csv # type of files coming from stdin
<reader1>:
<reader2>: ...
schema: # members schema module configuration
name: basic # member schema module name
seed: 71 # random number generator seed
writer: # writer module configuration
file: None # output file name
filetype: # output filetype
name: None # writer module namedb: # SQL database name
host: 127.0.0.1 # SQL server hostname
passwd: # SQL user password
port: 3306 # SQL server port
ssh: # credentials to encrypt SQL connection with SSH
host: # SSH server hostname
port: 22 # SSH server port
private_key: # SSH private keyfile path
user: # SSH username
user: root # SQL usernamechapter: # the chapter whose family tree will be generated
name: sigmanuSee Graphviz's documentation for available DOT attributes.
colors: True # add color to member nodes
custom_edges: True # enable custom edges
custom_nodes: True # enable custom nodes
defaults: # default Graphviz attributes
edge: # defaults for Graphviz edges
all: # all edges
<name1>: <value1>
<name2>: ...
rank: # edges between rank nodes
<name1>: <value1>
<name2>: ...
unknown: # edges coming from unknown parents
<name1>: <value1>
<name2>: ...
graph: # defaults for Graphviz graphs
all:
<name1>: <value1>
<name2>: ...
node: # defaults for Graphviz nodes
all: # all nodes
<name1>: <value1>
<name2>: ...
member: # member nodes
<name1>: <value1>
<name2>: ...
rank: # rank nodes
<name1>: <value1>
<name2>: ...
unknown: # nodes of unknown parents
<name1>: <value1>
<name2>: ...
edges: # a list of custom Graphviz edges
- # edge1
attributes: # Graphviz edge attributes
<name1>: <value1>
<name2>: ...
nodes: # keys of nodes connected by this edge
- # key1
- ...
- ...
family_colors: # map of member keys to Graphviz colors
<key1>: <color1>
<key2>: ...
file: # output file name
filetype: # output filetype
name: dot # writer name
no_singletons: True # delete member nodes with neither parent nor child nodes
nodes: # custom Graphviz nodes
<key1>:
attributes: # Graphviz node attributes
<name1>: <value1>
<name2>: ...
rank: # the rank (i.e., year, semester, etc.) the node is in
<key2>: ...
ranks: True # enable ranks
unknowns: True # add parent nodes to members without any
warn_rank: None # if no_singletons=True, singletons with rank>=warn_rank trigger warnings when droppedThis project loosely uses Semantic Versioning.
This project is licensed under GPLv3.