flowchart_example1.do

********************************************************************************
****** EXAMPLE
********************************************************************************
*
********************
* INTRODUCTION: Producing a Subject Disposition Flowchart
********************
* 
* A similar example flowchart can be seen here: 
*   http://www.texample.net/tikz/examples/consort-flowchart/
*   The code from this example was used as a guide for this project.
*   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/
* Running this example should produce similar otuput.
* 
* INSTRUCTIONS:
*   This file is a part of the ancillary files that come with flowchart 
*       (installed by typing 'net get flowchart').
*   By default it installs to the working directory at the time that
*       the 'net get' command is run. 
*
*   Run this do file from the do editor by hitting Ctrl + D (or Cmd + D on a 
*       mac) in the same directory as the ancillary files.
*   After running, a .tikz file will be produced. Open this file. In your LaTeX 
*       editor, run the manuscript with this file 
*       included (\input{<filename>.tikz})
*   Be sure to use the recommended packages and commands in the preamble of the 
*       ancillary file manuscript for the diagram to display properly.
*
* DEPENDENCIES:
*   After installing flowchart, be sure the following are in place: 
*   1. texdoc, sjlatex - STATA Packages
*       Installation Instructions:
*       In the STATA command-line, run the following command:
*           flowchart setup
*       This installs 2 dependencies: texdoc and its dependency, sjlatex
*   2. figure-flowchart.texdoc = Ancillary File
*       Installation Instructions:
*       In the STATA command-line, when you ran the setup command, it also 
*           installed the Ancillary Files into your present working directory.
*   3. LaTeX Setup (Typesetting)
*       A LaTeX setup should be installed to compile .tex and .tikz files:
*       a) Distribution (MiKTeX or TeXLive)
*           Recommended: MiKTeX, then use it to install the following packages: 
*               datatool, listings, multicol, xcolor, graphicx, tikz
*           Download: https://miktex.org/download/
*       b) Distribution Engine 
*           Recommended: pdfLaTeX 
*           Download: (Comes preinstalled with either Distribution)
*       c) IDE Editor
*           Recommended: TeXstudio (instead of others: TeXworks, TeXMaker, etc.)
*           Download: http://www.texstudio.org/
*       -----------------------------
*       d) Online LaTeX Setup 
*           Setting up a, b, and c can take some time. Therefore, an online
*           LaTeX can be used if you would like get started quickly.
*               ShareLaTeX - http://www.sharelatex.com/
*               Overleaf - http://www.overleaf.com/
*           These two companies have announced that they will soon merge into 
*           one editor.
*       -----------------------------
*       If you are a beginner/new to LaTeX, here are good starting points:
*           Installations:
*               https://www.youtube.com/watch?v=WewSa9aaFXg
*           Syntax: 
*               https://www.sharelatex.com/learn/Learn_LaTeX_in_30_minutes
*               https://www.youtube.com/watch?v=SoDv0qhyysQ
*           Help: 
*               https://tex.stackexchange.com
*         
********************
* SUGGESTED ANALYSIS APPROACH: Organization, Workflow, and Writing Code
********************
*
*   Here is a proposed way to use the flowchart program:
*   * DISPOSITION SUBANALYSIS: Analyze and setup the subject disposition.
*       *** Subanalysis Data is performed here where the numbers and data to 
*           produce the flowchart are created. 
*       *** Rows can be created using macros to fill in each row as the data for
*           the analysis are changed.
*   
*   * DIAGRAM: This writes the analysis as a diagram.
*       * Note: All files are relative to the current working directory unless
*           you specify a path with the filenames specified. Here is an example.
* 
*   The following details suggested directory structures and naming conventions:
* 
*   /Manuscript/
*       |
*       |-- ##-[ProjectName]-[Main-Manuscript-File].tex      <-- LaTeX Document
*       |-- ##-[ProjectName]-[Section]-Fig-[FigureName].tex  <-- LaTeX Document
*       +-- ##-[ProjectName]-[Section]-Fig-[FigureName].tikz <-- TikZ Picture
* 
*   /Stata/
*       |
*       |-- /Data/
*       |     |
*       |     +-- /Subanalysis Data/
*       |           |
*       |           +-- [Section]-Fig-[FigureName].data      <-- Suba. Data File
*       +-- /Do/
*             |
*             |-- ##-[ProjectName]-PostProduction-[Section]--Fig-[FigureName].do
*             |                                  Figure Do-File -------^
*             \\   ...
*             | 
*             +-- ##-[ProjectName]-[Section]-[Main Analysis File].do
*                                     Main Analysis File -----^
*
*   For this suggested structure, the filepaths to use would be as follows:
*   
*  . flowchart init using "..\Data\Subanalysis Data\methods--fig-flowchart.data"
*  
*  . flowchart writerow ...
*  . flowchart writerow ...
*  . flowchart writerow ...
*  
*  . flowchart connect ...
*  . flowchart connect ...
*  . flowchart connect ...
* 
*  . flowchart finalize, template("fig-flowchart.texdoc") output("..\..\Manuscript\methods--fig-flowchart.tikz")
*   
********************
* EXPLANATION OF FILES:
********************
* 
*   Do File
*       This is the .do file that contains your analysis where you can use
*       the flowchart commands to generate the diagram.
*           See Example: flowchart_example2.do
*   LaTeX Documents
*       This is a (.tex) file that contains a \begin{figure}...\end{figure} 
*       Environment command. STATA does not manipulate this file. It instead 
*       contains all of the design elements that arrange the TikZ picture 
*       appropriately in the Manuscript and also loads the Subanalysis Data 
*       (.data) in the Data file for generating the different components of the 
*       TikZ picture's diagram (e.g., data for the boxes of a 
*       Subject Disposition Flowchart).
*           See Example: methods--figure-flowchart.tex
*       The manuscript's .tex file can then include this .tex file specific to 
*       the figure directly into the manuscript file with an \input{ } command:
*       \input{methods--figure-flowchart.tex}
*           See Example: manuscript.tex
*   Figure Texdoc Do File - Do Not Edit
*       This Do file is a 'Texdoc Do File' which is to say it is invoked by the 
*       texdoc command in STATA in the Main Analysis File that is producing the 
*       Subanalysis Data created from your analysis using your dataset. There's
*       no need to edit this file beyond changing its filename to match your
*       project's naming convention.
*           See Example: figure-flowchart.texdoc (No Need to Edit)
*   TikZ Picture (Automatically regenerated)
*       This is a 'picture' that is used by the TikZ package in LaTeX to 
*       generate a diagram in LaTeX. There's no need to edit this file beyond
*       changing its filename to match your project's naming convention.
*       Instead, in your LaTeX document, use the \input{<filename.tikz>} to
*       make LaTeX automatically include it in the final document when 
*       compiling.
*           See Example: methods--figure-flowchart.tikz (No Need to Edit)
*   Subanalysis Data File (Automatically regenerated)
*       The data for a figure is produced from a subanalysis and is assigned to 
*       variables. The Data file consists of variables with the generated data, 
*       as one variable assignment per line. A '=' sign is used as a delimiter 
*       to denote [variable] = [value] where the left-hand side is the 
*       variable-name and the right-hand side is the value or data produced in 
*       the subanalysis. The variables with data produced by the subanalysis 
*       have to have a unique name and are given a name in the do file that 
*       produces the figure. Data from the Dataset used in an analysis can be 
*       used to generate the data for the diagram. There's no need to edit the
*       file beyond changing its filename to match your project's naming 
*       convention.
*           See Example: methods--figure-flowchart.data (No Need to Edit)
*
* OVERALL: 
* 
*     Main Analysis File --> Runs the Figure Do-File (which is changed by the 
*       user to reflect the flow of data analysis).
* 
*     Figure Do-File --> Produces the boxes in the TikZ Picture and writes the 
*       equivalent values in the Subanalysis Data File.
* 
*     LaTeX Document --> Changed by the user to arrange or re-arrange the 
*       'TikZ picture' in the Manuscript.
*     
* REFERENCES
* 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/ 
* Acknowledgements: Thank you Morten Willert for the TikZ flowchart example.

********************************************************************************
****** EXAMPLE
********************************************************************************

* DISPOSITION SUBANALYSIS: 
*
*   ... This subanalysis section would be performed in your main analysis do file 
*       to produce the data for the the flowchart command.

* ------------------------------------------------------------------------------

* DIAGRAM: 
* Run this code to produce a similar flowchart to M. Willert's CONSORT-style 
*   flowchart: http://www.texample.net/tikz/examples/consort-flowchart/
* It should resemble that flowchart.

* Initiate a flowchart by specifying the subanalysis data file to write: 
flowchart init using "methods--figure-flowchart.data"


* Format: flowchart writerow(rowname): [center-block triplet lines] , [left-block triplet lines]
*   Triplet Format: "variable_name" n= "Descriptive text."

flowchart writerow(enrollment): ///
    "referred" 173 "Referred", ///
    "referred_excluded" 17 "Excluded" ///
        "referred_excluded_nopartic" 9 "a) Did not wish to participate" ///
        "referred_excluded_noshow" 5 "b) Did not show for interview" ///
        "referred_excluded_other" 3 "c) Other reasons"
    
flowchart writerow(assessment): ///
    "assessed" 156 "Assessed for Eligibility", ///
    "assessed_excluded" 54 "Excluded" ///
        "assessed_excluded_inclusioncritunmet" 22 "a) Inclusion criteria not met" ///
        "assessed_excluded_exclusioncritmet" 13 "b) Exclusion criteria met" ///
        "assessed_excluded_unsuitedgroup" 7 "c) Not suited for waitlist group" ///
        "assessed_excluded_unsuitedtx" 2 "d) Not suited for intervention" ///
        "assessed_excluded_othertx" 3 "e) Sought other treatment" ///
        "assessed_excluded_other" 7 "f) Other reasons"

flowchart writerow(random): "randomized" 102 "Randomized", flowchart_blank // Blank Row

flowchart writerow(allocgroup): ///
    "alloc_interventiongroup" 51 "Allocated to Intervention group", ///
    "alloc_waitlistgroup" 51 "Allocated to Wait-list control group"

flowchart writerow(allocdetails): ///
    "intervention_received" 49 "Received intervention" ///
        "intervention_unreceived" 2 "Did not receive intervention" ///
        "intervention_unreceived_exclusioncrit" 1 "With exclusionary criteria" ///
        "intervention_unreceived_notime" 1 "Could not find time to participate", ///
    "waitlist_stayedon" 48 "Stayed on wait-list" ///
        "waitlist_didnotstay" 3 "Did not stay on wait-list" ///
        "waitlist_didnotstay_selfinduced" 2 "Lost motivation" ///
        "waitlist_didnotstay_leftarea" 1 "Was offered treatment elsewhere"
    
flowchart writerow(postmeasurement): ///
    "postintervention_lost" 5 "Post-intervention measurement" ///
        "postintervention_lost_droppedout" 2 "Dropped out of the intervention" ///
        "postintervention_lost_nomeasurement" 3 "Did not complete measurement", ///
    "postwaitlist_lost" 6 "Post-wait-list measurement" ///
        "postwaitlist_lost_droppedout" 3 "Dropped out of the wait-list" ///
        "postwaitlist_lost_nomeasurement" 3 "Did not complete measurement" ///
    
flowchart writerow(wlistintervention): flowchart_blank, /// 
    "postwaitlist_intervention_allocated" 48 "Allocated to intervention" ///
        "postwaitlist_intervention_received" 46 "Received intervention" ///
        "postwaitlist_intervention_didnotreceive" 2 "Did not receive intervention" ///
        "postwaitlist_intervention_dnr_lowmotivation" 1 "Reported low motivation" ///
        "postwaitlist_intervention_dnr_notime" 1 "Could not find time to participate"
    
flowchart writerow(measurement3monpostint): ///
    "intervention_3monthfollowup" 9 "3-months follow-up measurement: \\ \h Loss to follow-up", ///
    "postwaitlist_postintervention_losstofollowup" 5 "Post-intervention measurement: \\ \h Loss to follow-up" ///
        "postwaitlist_postintervention_losstofollowup_droppedout" 2 "Dropped out of the intervention" ///
        "postwaitlist_postintervention_losstofollowup_incomplete" 3 "Did not complete measurement"

flowchart writerow(wlist3mon): flowchart_blank, ///
    "postwaitlist_3monthfollowup" 2 "3-months follow-up measurement \\ \h Did not complete measurement"
    
flowchart writerow(analyzed): ///
    "intervention_analyzed" 51 "Analyzed in Intervention group", ///
    "postwaitlist_analyzed" 51 "Analyzed in Wait-list control group"

* Format: rowname_blockorientation rowname_blockorientation
* This command connects the blocks with arrows by their assigned orientation. 
*   Use rowname_center for the center-block (first block of triplets), which will appear on the left of the diagram.
*   Use rowname_left for the left-block (second blow of triplets), which will appear on the right of the diagram.
flowchart connect enrollment_center enrollment_left
flowchart connect enrollment_center assessment_center
flowchart connect assessment_center assessment_left
flowchart connect assessment_center random_center
flowchart connect random_center allocgroup_center
flowchart connect random_center allocgroup_left, arrow(angled)
flowchart connect allocgroup_center allocdetails_center
flowchart connect allocgroup_left allocdetails_left
flowchart connect allocdetails_center postmeasurement_center
flowchart connect allocdetails_left postmeasurement_left
flowchart connect postmeasurement_center measurement3monpostint_center
flowchart connect measurement3monpostint_center analyzed_center
flowchart connect postmeasurement_left wlistintervention_left
flowchart connect wlistintervention_left measurement3monpostint_left
flowchart connect measurement3monpostint_left wlist3mon_left
flowchart connect wlist3mon_left analyzed_left 

flowchart finalize, template("figure-flowchart.texdoc") output("methods--figure-flowchart.tikz")


* Now, using LaTeX, compile the manuscript.tex file -- This file is already setup to tie all of these files together.
*   This file shows you how you would use \input{} to include the new .tikz file as a figure diagram into a 'figure' tex LaTeX document.
*   The preamble in the ancillary manuscript file is a guide on which packages and commands to include in your LaTeX setup.