Skip to content

Flowchart is a STATA module/package that generates publication-quality Subject Disposition Flowchart Diagrams in LaTeX Format. This package generates PGF/TikZ code through texdoc, compiled in LaTeX to produce the diagram as a PDF. The final diagram is the same in style as ones used in the PRISMA Statement, CONSORT 2010 Statement, or STROBE State…

License

Notifications You must be signed in to change notification settings

IsaacDodd/flowchart

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

FLOWCHART

Stata module/package to generate a publication-quality subject disposition flow diagram in LaTeX using the PGF/TikZ package directly within Stata using texdoc

Fully tested on Stata versions 13, 14, and 15

Introduction

Use the flowchart package in Stata to generate a publication-quality Subject Disposition Flowchart Diagram in LaTeX Format. This package gives Stata the ability to generate the necessary TikZ code to include in a LaTeX and produce the diagram as a PDF or any other format. Similar to how the 'estout' package in Stata is commonly used to generate tables from regression analysis output for published journal articles, this package can be used to generate flowcharts for publications that show how the subjects from a study were included/excluded into analysis groups, or further refinements.

The final diagram will be similar in style to the ones used in the PRISMA Statement, CONSORT 2010 Statement, or STROBE Statement Reporting Guidelines, which are very commonly used within formal publications for systematic review, clinical trial, or cohort study research findings. This package allows generating this diagram to be automated so that the numbers in the diagram change as the analysis changes, saving hours of work.

For an example of the package's output, please see example1output.pdf and the example code that produced it in flowchart_example1.do.

Here is a low-resolution screenshot of the PDF:

Example1Output

The format follows closely the example of a CONSORT-style flow diagram at TeXample which was written in PGF/TikZ by Morten Willert. The example code to generate the above diagram is incldued in the Ancillary Files installed with flowchart.

 

Install

New Install: In Stata, to install the flowchart package and its main dependencies in your system's ado filepath, and also flowchart's ancillary files into your current working directory, type or copy-and-paste the following commands into Stata:

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

Updates: To later update your flowchart installation with the latest changes to the package, use the following command in Stata:

. flowchart setup, update

Uninstall: In order to complete the remove the package, flowchart can uninstall itself with the following command:

. flowchart setup, uninstall

 

How to Use

After installation, type flowchart getstarted for an introductory message to the flowchart package.

GetStartedMessage

Type help flowchart for detailed instructions on how to get started. Study the files flowchart_example1.do and flowchart_example2.do for very carefully laid out examples of usage and a very detailed, thorough explanation of the format.

The format for the code follows this typical example, which is available in flowchart_example2.do:

* INITIALIZE: Start a new datatool variable file.
flowchart init using "filename.data"

* WRITE ROWS: [center-block] , [left-block]
* Row with 2 blocks.
flowchart writerow(rownametest1): "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"
    
    * A '\\' in a description introduces a newline in LaTeX.
    * Each of the 2 blocks can take several lines.
    * Each line is a space-separated triplet of 3 fields: "variable_name" n_number "Descriptive text."

* Row with No center-block (a center-block appears on the left)
flowchart writerow(rownametest2): 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"

* Row with No left-block (a left-block appears on the right)
flowchart writerow(rownametest3): "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

* Row with No center-block and a Singleton Lead-Line in the left-block
flowchart writerow(rownametest4): Flowchart_Blank, "rblock1_line1" 97 "This is one line, \\ of a block."
    
* Row with Singleton Lead-Line in the center-block and No left-block
flowchart writerow(rownametest5): "lblock1_line1" 46 "This is one line, \\ of a block.", Flowchart_Blank

* CONNECTIONS: Use the block orientation to connect arrows to the appropriate blocks
flowchart connect rownametest1_center rownametest1_left
flowchart connect rownametest1_left rownametest2_left
flowchart connect rownametest1_center rownametest3_center
flowchart connect rownametest3_center rownametest5_center
flowchart connect rownametest2_left rownametest4_left

* FINALIZE: This writes the files and generates the 'tikzpicture'
flowchart finalize, template("figure.texdoc") output("figure.tikz")

After running this code, the LaTeX figure and manuscript files, which tie in the TikZ file and data file, can then be compiled using a LaTeX distribution and IDE editor with a previewer. Please see flowchart_example1.do and the list of resources for more information on LaTeX.

Behind the Scenes

Under the hood, flowchart is an interesting package because it functions like a compiler and extends to some of the limitations of Stata's language features. It converts a simplistic Stata format into discrete tokens using Stata's low-level tokenizer, then through a hand-written parser (similar to a 2-token look-ahead, or LALR(2) parser) flowchart makes sense of each parsed token based on its logical sequence. Other internal functions transcompile the tokens into the correct PGF/TikZ code, looping through each block's lines. The connections go into a separate section.

The result is TikZ code that compiles into a flow diagram. (To see some of this in action, turn on the debugging log with the command flowchart debug on and run the code.) In the future, work can be done to simplify the overall structure to to extend its functionality to further forms of diagrams and other languages, replicating the underlying principles.

Resources

As they are identified, useful resources that produce visuals and diagrams using statistical methods will be listed in RESOURCES.md.

Contributions

Contributions are greatly, greatly appreciated, and a major goal for this package is for flowchart to become a community-driven package.

Support for Issues/Bugs, Suggestions, & Feedback

Please submit bugs using GitHub since it is much more difficult to respond to issues or feature requests via email. All comments, feedback, or suggestions are greatly welcomed.

Source Code & Development

Please send your code via pull requests via the conventional means here on GitHub for review. Please feel free to make this project your own by contributing new code changes, new features, and fixes rather than forking the code into a separate project. Collaborations are greatly welcomed. Please click on CONTRIBUTING.md above for an explanation on how to get started.

 

Future Directions

If this package becomes often-used, or there are further feature requests, additional steps could incldue different styles of flowchart diagrams to match various Reporting Guidelines, functions to be able to create boxes from calculations, or a wider variety of box options. There are many directions this project could take should a user-base arise.

 

Credit

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.

 

License

By installing this package you agree to the GNU LGPL under which this package is licensed. Please see LICENSE.txt for the full license of the GNU LGPL 2007, which does allow for the incorporation of this package in proprietary software if necessary but without warranty. Note: 'Flowchart' comes with ABSOLUTELY NO WARRANTY; This is free software, and you are welcome to redistribute it under certain conditions. Copyright © 2017. Isaac M. E. Dodd. All rights reserved.

About

Flowchart is a STATA module/package that generates publication-quality Subject Disposition Flowchart Diagrams in LaTeX Format. This package generates PGF/TikZ code through texdoc, compiled in LaTeX to produce the diagram as a PDF. The final diagram is the same in style as ones used in the PRISMA Statement, CONSORT 2010 Statement, or STROBE State…

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published