*! version 0.0.1 01aug2017

FLOWCHART Package

flowchart -- Use this command to generate publication-quality Subject Disposition Flowchart
Diagrams in TikZ code which can be compiled in LaTeX. These flow diagrams are the same as the ones used in the CONSORT 2010
Statement, STROBE Statement, and PRISMA Statement Reporting Guidelines.

After installing the package, to setup flowchart type 'flowchart setup'. This will update the flowchart
package and its main dependencies in your system's ado filepath and also download flowchart's ancillary
files into your current working directory.
Updates to the FLOWCHART package can be installed by using the 'flowchart setup, update' command
and are also available here: https://github.com/IsaacDodd/flowchart/

Support: Support is available at: https://github.com/IsaacDodd/flowchart/issues/new/

Examples: Please see the Ancillary Files for extensive examples with explanations of usage:
flowchart_example1.do, flowchart_example2.do, and manuscript.tex
Example flow diagram:
http://www.texample.net/tikz/examples/consort-flowchart/
Example of the flowchart package's output to replicate this example:
https://github.com/IsaacDodd/flowchart/blob/master/example1output.pdf
If you do not yet have a LaTeX setup, an online LaTeX editor is a good place to start:
https://www.sharelatex.com
https://www.overleaf.com

Syntax

flowchart
[command]
[,
options]

Commands
init init using filename.data -- Initialize the diagram by specifying a filename (or filename with filepath) where the data file to store variables will be generated.
This file is created by the flowchart package in Stata and used by LaTeX's datatool package to generate numerical data within the diagram.

writerow(...): writerow(rowname): center-block, left-block -- Create
a new row in the diagram. A detailed explanation is below.

connect connect rowname_blockorientation rowname_blockorientation, [arrow(type)] --
Draws arrows between the blocks across or between rows by specifying 'rowname underscore block-orientation'.

finalize finalize, template("filename.texdoc") output("filename.tikz") --
Takes the prespecified texdoc syntax in filename.texdoc and writes into it the TikZ code into filename.tikz to be included in a manuscript's LaTeX document.

setup setup, [update] -- Installs texdoc and any other dependencies and
replaces the current flowchart installation. Alternatively, option [, update] can be specified to
update the flowchart package installation.

debug debug, [on off logreset info check tikz] -- Turns on or off the debugging features
and produces a DebugLog.log that can be used when support is needed. Option tikz can be specified
to produce debugging strings in the final TikZ file.

filename.data can have any extension and can have a filepath. See filename for more detailed syntax information.

by is not allowed; see [D] by.

flowchart
[writerow(rowname):]
[line-triplets center-block orientation] ,
[
line-triplets left-block orientation]

Commands
writerow(rowname): Create a new row with 'rowname'. The rowname must be alphanumeric. The rowname
also becomes a part of each row's blocks. The first block is the center block and the second block is the left block.
Each block is divided by a single comma (,).

line-triplets "variablename" nnn "Description." -- Each block can receive
multiple 'lines'. Each line is a triplet of 3 fields separated by a space. Each line-triplet is also separated separated by a space.
The first is the variable name, the second is the number associated with it, and the third is the description that appears in the block.
If more than one line is specified, the first line gets a comma at the end and the others are indented.

Flowchart_Blank This is a keyword that lets the flowchart package know that a block is empty.
This can be used to connect the arrow to the block that comes after it.

More detailed descriptions of these commands, with examples, are below.

Description

The following is a detailed description of the main commands in the flowchart package.

Overall

flowchart is a package that generates a Subject Disposition Flowchart Diagram. It does this by generating TikZ code that can be compiled
from a variable file using the data you generate in your analysis in Stata.

The diagram generated is similar in style to the ones used in many studies and required by the main Reporting Guidelines in LaTeX format.
The flowchart oackage allows you to use data from a dataset in your analysis and generate the flow diagram in a do file.

flowchart getstarted -- Type this command for a simplified message on how to get started with the flowchart package.

flowchart debug info -- Type this command if you have a problem for a simplified message on what to do to get help with the flowchart package.

Dependencies: This command uses the 'texdoc' package (written by Ben Jann) which uses the 'sjlatex' package as a dependency.
The flowchart package can install them both itself after you run in Stata the command: 'flowchart setup' after installing
the flowchart package. This will install both dependencies and also flowchart's Ancillary Files (containing examples) in your current working directory.

Initialization

flowchart init using filename.data

This command takes the filename of a text file where data variables can be written so that the
datatool package in LaTeX can be used to load the file specified to fill in all of the
\figvalues with the numbers specified in each line. (Variable names entered into
this LaTeX command entered must be unique and alphanumeric.)

In LaTeX, place something like this in the preamble section of your .tex file (the space between \documentclass ... \begin ):

...
% Figures, Diagrams, and Other Graphics
\usepackage % TikZ Package - Generates graphics (i.e., flowcharts generated)
\usetikzlibrary
\newcommand*{\h}{\hspace{5pt}}% For indentation
\newcommand*{\hh}{\h\h}% Double indentation
\usepackage % DataTool Package - Loads variable data file
\DTLsetseparator{ = }% Delimiter
...

This will load the datatool and TikZ package in LaTeX. This tells the TikZ package to use \h and \hh to indent lines.
It also tells the datatool package to interpet each line of the data file initialized as having '[variable_name] = [variable_value]' by using the equals sign as a delimiter.

flowchart set variable, name("name_of_setting") value("valuealphanumeric")

This will write a variable to the variable file (flowchart.data by default) which is loaded by the datatool in LaTeX. So, when the LaTeX
document is compiled it will populate the LaTeX document with the variable's value.

Access this variable in a LaTeX document using '\figvalue'

To set layout variables:

flowchart set layout, name("center_textwidth") value("12")
flowchart set layout, name("left_textwidth") value("18")

The variable name is prepended with 'set_' and written to the file.
(Note: Every variable file also includes 1 dummy variable 'set_dummy'.)

Writing Rows ("Boxes")

flowchart writerow(rownamehere):

Format: flowchart writerow(Name_of_row): [Block_Center], [Block_Left]

The content within each block should be separated by a single comma (strings within a block can still
use a comma, it just has to be within double-quotes).

The first block gets assigned the 'center' orientation and the second gets the 'left' orientation.
Each block can have several lines, and each line has to have a triplet of 3 fields which should be
separated by spaces.
A single line is a triplet of these 3 fields: "variable_name" n# "Description of the variable
name and number."

In a Stata do file, multiple line-triplets can be separated by a '\\\' at the end of the line for readability.
This can only be used in a do file and not the Stata command-line but can be used to wrap long triplet lines.

Limitations: Variable names must be unique and the numbers entered should be real numbers.
Descriptions must not contain curly braces (i.e., '{' or '}').

Keywords

Flowchart_Blank

This keyword defines a blank block. Either the left or the center block can be set
to blank using this keyword before or after the comma respectively so that a box
doesn't appear on a given row.
This can be of any casing (e.g., fLoWcHaRT_BLANK, flowchart_blank, or any combination)
as long as the keyword is spelled correctly, but for readibility it is wise to
use Flowchart_Blank.

Block Orientations: Each row can have 2 blocks: center and left. The center-block
appears on the left of the diagram and the left-block appears on the right of the diagram (note: this
can be confusing initially and must be learned).

A blank block is a block with no lines or content (which won't be drawn in the final diagram) and should
have the special keyword 'flowchart_blank' to indicate to the program's parser internally that
there's no content for that block, otherwise the blocks will misalign and the .tex document will not
compile the TikZ picture.

The sides of the diagram are initially counter-intuitive. Think of it like reading a chest x-ray:
when interpreting the x-ray the patient's left is on the right of the page and the patient's right
is on the left of the page -- the orientation being relative to a patient facing out of the plane
of the x-ray.

Likewise, the column that is immediately to the left of the page as the center column
and the column that is immediately to the right of the page is the left column.

Block Connections ("Arrows")

flowchart connect

Format: [rowname_center] --> [rowname_left] - Connect a center block to a left block for horizontal
arrows across rows.
[rowname_center] --> [rowname_center] - Connect a center block to a center block for vertical
across within the same column for blocks in the center.
[rowname_left] --> [rowname_left] - Connect a left block to a left block for vertical across
within the same column for blocks on the left.
, arrow(angled) - This option makes the arrow make a 90 degree angle. Use this across a blank row.

Connect each row's block with an underscore and then the column-orientation corresponding to its
side in this manner.

flowchart connect [blockname_orientation1] [blockname_orientation2], arrow(shape) allows you to specify the type of arrow.

Remarks

For detailed information on the flowchart package, visit https://github.com/IsaacDodd/flowchart/.

Examples

See the very detailed examples in the Ancillary Files. Install them into your working directory by typing into stata:

. flowchart setup

Here is an example of how rows can be written in a do file.

* |||||| EXAMPLE1: Dummy Row
. flowchart writerow(rowname): "lblock1_line1" 46 "This is one line, of a block." ///
"lblock1_line2" 43 "This is another line, of a block" ///
"lblock1_line3" 3 "This is another line, of a block", ///
"rblock1_line1" 97 "This is one line, of a block." ///
"rblock1_line2" 33 "This is another line, of a block" ///
"rblock1_line3" 44 "This is another line, of a block"

* |||||| EXAMPLE2: Row with No center-block
. flowchart writerow(rowname): flowchart_blank, "rblock1_line1" 97 "This is one line, of a block." ///
"rblock1_line2" 33 "This is another line, of a block" ///
"rblock1_line3" 44 "This is another line, of a block"

* |||||| EXAMPLE3: Row with No left-block
. flowchart writerow(rowname): "lblock1_line1" 46 "This is one line, \\ of a block." ///
"lblock1_line2" 43 "This is another line, of a block" ///
"lblock1_line3" 3 "This is another line, of a block", Flowchart_Blank

A block with a single row is called a 'singleton'. Each new line in a block is indented under the first line (the 'lead-line').
You can use macros to fill in the numbers here so that you only need to type these rows once.
The macros can be used to do math on the numbers to simplify adding new rows.

Troubleshooting

Here is a list of known problems that can arise in using this program and their quick-fix solutions.

STATA: unrecognized command: Flowchart_Blank r(199);

This is likely because you forgot to wrap a line where there is a blank.
Here is an example:
flowchart writerow(random): "randomized" 102 "Randomized",
Flowchart_Blank // Blank Row
Here is how it is fixed:
flowchart writerow(random): "randomized" 102 "Randomized", ///
Flowchart_Blank // Blank Row

TIKZ Error in LaTeX

LATEX: Argument of \@dtl@lop@ff has an extra }. ...<filename of data file>.data"}

This is likely because you tried to use the Flowchart_Blank keyword but actually
misspelled the 'Flowchart_Blank' keyword. Go back and edit the keyword and try again.

TIKZ Package pgf Error

Package pgf Error: No shape named <blockname_orientation> is known. \path (<blockname_orientation>)

This is likely due to an error in using the 'flowchart connect' command where
you referred to a block that does not exist. If a row does not have an accompanying
block, whether left or center oriented, it cannot be connected to any other blocks.
Therefore, try reviewing the connection to determine if you may be connecting an
arrow to a block that is blank.

Initialization Error

flowchart init using C:\...\Filename With Spaces.data
invalid 'With'
r(198);

This error happens when you specify a filename that has spaces in it. Instead, put
the entire filepath in quotes:
flowchart init using "C:\...\Filename With Spaces.data"
Note: Specifying the entire path isn't necessary if you are using a working directory
with relative paths. See 'help filename' for an explanation of filenaming conventions.

Setup Errors

Flowchart won't uninstall:
criterion matches more than one package
r(111);

This problem has been fixed in updated versions of flowchart, but this explanation is
left here in case it still happens. This is an error that is known to occur on Stata
version 13 and lower and was fixed by Stata Corp. starting with Stata version 14. This
occurs because Stata keeps track of which packages are installed, from where, and if
you originally installed flowchart from the Boston College SSC database (i.e., through
'ssc install flowchart', or did so through typing 'help flowchart', which may have chosen
the ssc package by default), so updating flowchart by running 'flowchart setup' likely
installed a second installation of flowchart -- in reality you only have 1 installation
of flowchart but there are 2 entries in Stata's internal database of installed package.

This problem can be confirmed by typing into Stata: '. ado dir flowchart' and seeing
that there are 2 flowchart packages installed. Therefore, to fix the problem on Stata
version 13 or lower, type into Stata: '. net query flowchart'. Next to 'ado' you will
find where your packages are installed (i.e., for example 'c:\ado\plus\'). In that
directory, you will find stata.trk. Carefully edit the file: each package ends with
a 'e'; Delete the extra flowchart entry by deleting from the 'S' line to the 'e' line.
Then save this file. Now, run again the command '. ado uninstall flowchart'. Now you
can confirm that both entries have been removed by running '. ado dir flowchart' and
seeing that no entries are returned. You can then install a fresh copy from GitHub by
running the command:

. net install flowchart, from("https://raw.github.com/IsaacDodd/flowchart/master/")

The problem should now be resolved.

Other Issues

For problems not resolved through this list, please open an issue/bug on GitHub. When
opening a new issue, you can greatly speed up the issue resolution process by submitting
2 things:

1. In Stata, type 'flowchart debug info'. Copy and paste the results into your issue. This
command returns the exact version of the packages you are running in case the problem was fixed
or introduced in a subsequent release.

2. In your do file, go to the line or lines that are giving you trouble. Before those
lines, put 'flowchart debug on' and after those lines put 'flowchart debug off'. Then,
rerun your program. You should notice in your working directory a new file was created
called 'DebugLog.log'. Either copy and paste the content or attach it as a new file.
Be sure to first remove any sensitive directories that you would not want the public
to see since GitHub is an open source community.

https://github.com/IsaacDodd/flowchart/issues/new/

References & Bibliography

1. Texdoc Command Use Based On:
Citation: Jann, Ben (2016 Nov 27). Creating LaTeX documents from within Stata using
texdoc. University of Bern Social Sciences Working Paper No. 14; The Stata Journal
16(2): 245-263. Reprinted with updates at
ftp://ftp.repec.org/opt/ReDIF/RePEc/bss/files/wp14/jann-2015-texdoc.pdf Retrieved on
July 28, 2017.

2. TikzPicture Diagram Code Based On:
Citation: Willert, Morten Vejs (2011 Dec 31). "A CONSORT-style flowchart of a
randomized controlled trial". TikZ Example (Texample.net). Retrieved from
http://www.texample.net/tikz/examples/consort-flowchart/

Credits & Acknowledgements

Credit to Ben Jann, whose texdoc package is a dependency in flowchart, and Morten
Willert, whose example of a flowchart diagram in TikZ was studied and used heavily
to generate similar flowcharts in this package.