/*** DO NOT EDIT THIS LINE -----------------------------------------------------
Title: makediagram
Description: generates DOT diagram file from data sets
----------------------------------------------------- DO NOT EDIT THIS LINE ***/
/***
Syntax
======
{p 8 16 2}
{cmd: makediagram} [{help using} {it:filename}] {cmd:,}
{it:export(filename)} [ {it:replace} {it:graphtype(name)}
{it:style(filename)} ]
{p_end}
{* the new Stata help format of putting detail before generality}{...}
{synoptset 20 tabbed}{...}
{synopthdr}
{synoptline}
{synopt:{opt e:xport(filename)}}export the DOT diagram file. {p_end}
{synopt:{opt graphtype(name)}}specifies the type of the graph which can
be {bf:digraph} (default) or {bf:graph} (i.e. undirected). {p_end}
{synopt:{opt replace}}replace the exported DOT file{p_end}
{synopt:{opt style(filename)}}appends an external DOT style sheet to the DOT file.{p_end}
{synoptline}
{p2colreset}{...}
Description
===========
__makediagram__ generates a [DOT](http://en.wikipedia.org/wiki/Dot) file from
a data set that can be rendered to a graphical file using {help diagram} program
within Stata. the data set should be prepared as explained in the next section.
Variable discription
====================
The data set should have 5 variables named __cluster__ (numeric), __from__
(numeric or string), __to__ (numeric or string), __label__ (string), and
__properties__ (string). The numeric variables can have labels which also changes
the labels in the DOT file.
cluster from to label properties
--------- -------- -------- ------- -----------
numeric numeric numeric string string
or or or
string string string
the __cluster__, __label__, and __properties__ can be missing. however, the
__from__ and __to__ variables specifies which nodes are connected to one another.
in directed graphs, the direction is __"from"__ towards __"to"__. However, in
undirected graphs, this direction is of no significance and only shows a connection.
the __cluster__ variable defines in which subgraph the connection takes place
(see the examples)
the __from__ and __to__ variables specify the nodes where the connection begines and
ends. the variables can be numeric, e.g. the nodes can be {bf:1 -> 2}Â or strings
such as {bf:A -> B} or {bf:"Node A" -> "Node B"}. If the variables are numeric,
their label is automatically used to alter the labels of the DOT graph (see the examples).
the __label__ variable simply "labels the connection". this merely specifies the "label" or
"value" for the arrow. the label of the connection can also be specified within the
__properties__ variable, but due to its common use and importance
(_and to make life easier for those who don't wish to learn the DOT language_),
it is made available as a separate variable. yet, adding __label="__ _label_ __"__
in the __properties__ variable can change the connection label.
Example(s)
=================
the [diagram torture test](https://raw.githubusercontent.com/haghish/diagram/master/torture_test.do)
includes several examples and example data sets for testing the package.
exporting a directed DOT script file from a data set
. makediagram using name.dta, export("name.txt") label("diagram's label")
exporting undirected DOT script file
. makediagram using name.dta, export("name.txt") graphtype(graph)
Author
======
__E. F. Haghish__
Center for Medical Biometry and Medical Informatics
University of Freiburg, Germany
_and_
Department of Mathematics and Computer Science
University of Southern Denmark
haghish@imbi.uni-freiburg.de
[http://www.haghish.com/markdoc](http://www.haghish.com/statistics/stata-blog/reproducible-research/markdoc.php)
Package Updates on [Twitter](http://www.twitter.com/Haghish)
- - -
This help file was dynamically produced by {help markdoc:MarkDoc Literate Programming package}
***/
*cap prog drop makediagram
prog define makediagram
version 11
syntax [using/] , Export(str) [replace] [GRAPHtype(name)] ///
[style(str)]
// -------------------------------------------------------------------------
// Make sure the data is .dta; initiate the diagram text file
// =========================================================================
if !missing("`using'") {
if (!index(lower("`using'"),".dta")) {
di as err "specified data is not supported"
err 198
}
}
if "`graphtype'" == "graph" {
local source "graph G {"
local sign --
}
else if "`graphtype'" == "digraph" | missing("`graphtype'") {
local source "digraph G {"
local sign ->
}
else {
di as err "{bf:graphtype} invalid"
err 198
}
tempfile tmp
tempname knot
qui file open `knot' using "`tmp'", write replace
file write `knot' "`source'" _n
// adding external style
// -------------------------------------------------------------------------
if !missing("`style'") {
confirm file "`style'"
tempname hitch
qui file open `hitch' using "`style'", read
file read `hitch' line
while r(eof)==0 {
*local source = `"`macval(source)'"' + `"`macval(line)'"'
file write `knot' `"`macval(line)'"' _n
file read `hitch' line
}
}
// -------------------------------------------------------------------------
// Loading the specified data set, if specified
// =========================================================================
if !missing("`using'") {
preserve
qui use "`using'", clear
}
// -------------------------------------------------------------------------
// Testing the data set variables
// =========================================================================
// Check if cluster variable exists:
// IF cluster variable exists and it is missing, OR IF it does not exist:
// ELSE if it exists and not missing:
// -------------------------------------------------------------------------
capture confirm variable cluster
if _rc == 0 {
if missing(cluster) {
file close `knot'
diagramconnection , tempfile("`tmp'") sign(`sign')
file open `knot' using "`tmp'", write append
}
else {
//check if cluster is string
cap confirm string variable cluster
if _rc == 0 local clusterisstring 1
qui drop if missing(cluster) //drop missing values
*sort cluster
tempfile master
qui save `master'
clear
qui use `master'
//first evaluate when cluster observation is not missing
//if cluster is string, the missings come first
local current : di cluster[1]
while !missing(cluster[1]) {
qui keep if cluster == cluster[1]
if missing("`clusterisstring'") {
local nme : di "`: label (cluster) `=cluster[1]''" // label
}
if !missing("`clusterisstring'") {
if substr(cluster[1], 1,1) == `"""' {
local current : di substr(`"`macval(current)'"',2,.)
}
if substr(cluster[1], -1,1) == `"""' {
local current : di substr(`"`macval(current)'"',1,strlen(`"`macval(current)'"')-1)
}
local nme `"`macval(current)'"' // label
//remove white space
local current : subinstr local current " " "", all
}
file write `knot' " subgraph cluster_`current' {" _n
if !missing("`nme'") file write `knot' `" label="`nme'";"' _n
file close `knot'
diagramconnection , tempfile("`tmp'") sign(`sign') indent(" ")
file open `knot' using "`tmp'", write append
file write `knot' " }" _n
qui use `master', clear
qui drop if cluster == cluster[1]
qui save `master', replace
local current : di cluster[1]
}
*else {
* qui drop if missing(cluster)
*}
//evaluate for observations with missing cluster
*qui use "`using'", clear
if !missing("`using'") {
qui use "`using'", clear
}
//evaluate arguments when cluster is missing
qui keep if missing(cluster)
file close `knot'
diagramconnection , tempfile("`tmp'") sign(`sign')
file open `knot' using "`tmp'", write append
}
}
//if missing cluster variable...
else {
file close `knot'
diagramconnection , tempfile("`tmp'") sign(`sign')
file open `knot' using "`tmp'", write append
}
file close `knot'
if !missing("`using'") local use using "`using'"
diagramnode `use' , tempfile("`tmp'")
file open `knot' using "`tmp'", write append
file write `knot' "}" _n
file close `knot'
copy "`tmp'" "`export'", `replace'
if !missing("`using'") restore
cap confirm file "`export'"
if _rc == 0 {
di as txt "{p}({bf:makediagram} created "`"{bf:{browse "`export'"}})"' _n
}
else display as err "{bf:makediagram} could not produce `export'" _n
end
* markdoc makediagram.ado, export(sthlp) replace ascii
* markdoc makediagram.ado, export(pdf) replace style(stata) linesize(200)
*makediagram, export(sth.txt) replace