{smcl} {* 5 Nov 2019}{...} {hline} help for {hi:ieboilstart} {hline} {title:Title} {phang}{cmdab:ieboilstart} {hline 2} harmonizes Stata settings across team members in the same project. {phang2}For a more descriptive discussion on the intended usage and workflow of this command please see the {browse "https://dimewiki.worldbank.org/wiki/Ieboilstart":DIME Wiki}. {phang}{hi:DISCLAIMER} {hline 1} Due to technical reasons, it is impossible to guarantee that different types of Stata (version number, Small/IC/SE/MP or PC/Mac/Linux) work exactly the same in every possible context. This command does not guarantee against any version discrepancies in Stata or in under-contributed commands, it is solely a collection of common practices to reduce the risk of the same code running differently on different computers. See more details {help ieboilstart##comp:below}. {marker synt}{...} {title:Syntax} {phang}Note that due to technical requirements in Stata, to include the most important setting - version() - in this command you must include the second line below.{p_end} {pmore} {cmdab:ieboilstart} , {cmdab:v:ersionnumber(}{it:version_number}{cmd:)} [{it:optional_options}]{break} `r(version)' {phang}The second line "`r(version)'" uses the command {help version} to set the same Stata version across all users. "`r(version)'" is identical to setting the version to the version number set in {cmdab:v:ersionnumber()} but both helps standardize this setting across different parts in the project and function as a reminder to set the version number. {p_end} {marker opts}{...} {synoptset 20}{...} {synopthdr:options} {synoptline} {synopt :{cmdab:v:ersionnumber(}{it:string}{cmd:)}}sets a stable version of Stata for all users. This option does {ul:nothing} unless "`r(version)'" is included as in the example above.{p_end} {synopt :{cmdab:maxvar(}{it:numlist}{cmd:)}}manually sets the maximum number of variables allowed in a data set. The default if omitted is the maximum number of variables allowed depending on the version of Stata used.{p_end} {synopt :{cmdab:matsize(}{it:numlist}{cmd:)}}manually sets the maximum number of variables allowed in an estimation command, for example {help regress:regress}. The default if omitted is 400.{p_end} {synopt :{cmdab:noclear}}prevents the command from clearing all data which some settings require. Best practice is to use this command before opening any data.{p_end} {synopt :{cmdab:q:uietly}}suppresses the output with the disclaimer and the list of settings.{p_end} {synopt :{cmdab:veryquietly}}does what {cmdab:quietly} does, but also suppresses the reminder to include "`r(version)'".{p_end} {synopt :{cmdab:setmem(}{it:string}{cmd:)}}manually sets the memory for Stata 11 users.{p_end} {synopt :{cmdab:c:ustom(}{it:string}{cmd:)}}allows the user to enter custom lines of code to be added.{p_end} {synopt :{cmdab:noperm:anently(}{it:string}{cmd:)}}is used to not change settings for future sessions of Stata.{p_end} {synoptline} {marker desc}{...} {title:Description} {pstd}{cmdab:ieboilstart} standardizes best practice settings across all users using for a project. Such standardized code is usually referred to as boilerplate code, and that is where {cmdab:ieboilstart} gets its name. Standardizing the boilerplate code in a project reduces the risk that code behaves differently across users regardless of what version and type of Stata they are running. {pstd}A command like this is impossible to make comprehensive in terms of versions control. Therefore, the ambition of this command is only to provide a convenient way to include boilerplate code based on commonly used best practices, which is much better than having no boilerplate code at all. The default values used are the values that are standard in boilerplate code for dofiles written for Impact Evaluations at DIME, World Bank. Suggestions for additions or improvements are very welcomed. See the {help ieboilstart##auth:author} section for contact details. {marker comp}{...} {title:Compatibility Across Different Stata:} {pstd}{cmdab:ieboilstart} sets settings that increases compatibility between Stata 11.0-15.0, Stata Small/IC/SE/MP and Stata for PC/Mac/Linux. {it:Increase compatibility} does not mean an absolute guarantee that all code will always work the same in different types of Stata. That is technically impossible. {it:Increase compatibility} here means reducing the risk of code working differently in different types of Stata. {pstd}{cmdab:ieboilstart} does sometimes apply different settings for different users as all settings does not work for all versions and types of Stata. For example, new memory settings were introduced in Stata 12 and {inp:set maxvar} is not allowed in Stata IC. {cmdab:ieboilstart} is implemented to set the settings in each version and type of Stata that reduces the risk of errors when different users run the same code, but the only way to eliminate the risk completely, is to use exactly the same version of Stata. {pstd}In addition to version control, {cmdab:ieboilstart} allows a project to standardize user preference settings such as {help set varabbrev:varabbrev} that can cause code to behave differently across users. {title:Important Details on Version Setting:} {pstd}Impact Evaluations and other research projects often span over many years, which means that the same code is likely to run in different versions of Stata. Stata provides a method to reduce the risk of discrepancies due to this. See {help version:version} settings for more details. This method is included in {cmdab:ieboilstart}, however, {cmd:version} is mainly intended for making code written in Stata 11 work in Stata 14 and not necessarily the other way around. Setting the version is still best practice and perhaps the most important setting in {cmdab:ieboilstart}. Read the {help ieboilstart##synt:syntax section} on the extra step required for {cmdab:ieboilstart} to set the version.{p_end} {pstd}{hi:Warning:} Any dofiles containing randomization {ul:{hi:MUST}} set the version number as Stata occasionally makes updates to its randomization algorithm between versions. A dofile including random assignment or random sampling is therefore not necessarily stable across different versions of Stata, unless the dofile has a version number explicitly set in the beginning of the file.{p_end} {pstd}The version setting has the scope of a local, meaning that it expires when a dofile and all sub-dofiles it is calling are completed. Therefore, set the version in your master dofile {ul:and} in every single dofile using randomization. This will make your randomization stable even if another user would only run the specific dofile with the randomization.{p_end} {title:Details on Memory Settings:} {pstd}In Stata versions before Stata 12, memory was assigned statically from the computer memory, meaning that there was a fixed amount of memory assigned to Stata regardless if required it or not. Stata would crash if it went over that fixed limit when for example increasing the data set or running a complex calculation. In Stata 12 and more recent versions, this is done dynamically, meaning that Stata is assigned a little bit of memory when it is starts and assigned additional memory dynamically as needed. The only memory limit is the hardware limits on the computer it is running on. {pstd}The fixed memory in Stata 11 was assigned by the command {cmdab:set memory}. This command is simply ignored in Stata 12 or later. Instead the dynamic memory setting can be fine tuned with {cmdab:min_memory}, {cmdab:max_memory}, {cmdab:niceness} and {cmdab:segmentsize}, although even highly advanced users rarely have to worry about these settings as long as they are set to the recommended default values (which this command ensures that they are). {p2colset 5 22 24 2} {p2col : Memory Settings}Short explanation{p_end} {p2line} {pstd}{it: Basic Settings:}{p_end} {p2col :{cmdab:set maxvar}}sets the maximum number of variables allowed. The default value is the maximum allowed in the version of Stata used which is 32,767 in Stata MP or SE, and 120,000 in Stata MP 15. A lower maximum number can manually be set by the option {cmdab:maxvar()}. The maxvar is fixed in Stata Small or IC so this setting is ignored when any of those versions of Stata is used. See {help set maxvar:set maxvar}.{p_end} {p2col :{cmdab:set matsize}}sets the maximum number of variables that can be included in estimation commands such as {cmd:regress}. The {cmdab:ieboilstart} default value is 400 which is the default value for Stata. A higher value is often allowed but it slows down Stata and is only needed when running very complex analysis. This option can be used to set a higher value, as long as the value does not violate the limitations in the version of Stata used. See {help set matsize:set matsize}.{p_end} {break} {pstd}{it: Dynamic Memory Settings (see {help memory:memory} for details and reasons for default values. Few users ever need to change these values):}{p_end} {p2col :{cmdab:set min_memory}}sets a lower bound for the amount of memory assigned to Stata. The default value is no lower bound.{p_end} {p2col :{cmdab:set max_memory}}sets an upper bound for the amount of memory assigned to Stata. The default is as much as the hardware of the computer allows.{p_end} {p2col :{cmdab:set niceness}}defines how quickly Stata releases unused memory back to the computer{p_end} {p2col :{cmdab:set segmentsize}}defines how large bundles of data is assigned each time Stata request more memory. Too large bundles make Stata occupy an unnecessary large part of the computer's memory (that otherwise could have been used by other applications), and too small bundles make Stata frequently consume processing power requesting new bundles.{p_end} {break} {pstd}{it: Static Memory Settings (only applicable in Stata 11)}{p_end} {p2col :{cmdab:set memory}}sets the amount of static memory assigned to Stata. {p_end} {p2line} {pstd}{hi:{ul:Other Settings:}}{break}The other settings are included as they are either very commonly preferred or reduces the risk of errors for users that do not yet fully understand the implication of setting these settings to other values than what is recommended. These settings can be reverted to personal preferences after running {cmdab:ieboilstart} or by using the {cmd:custom()} option.{p_end} {p2colset 5 24 26 2} {p2col : Other Settings}Short explanation{p_end} {p2line} {p2col :{cmdab:set more off}}disables the default setting that Stata stops and waits for the user to press any key each time the output window is full. Long dofiles would take a very long time to run and require constant attention from the user without this setting. Most Stata users always disable the default which is {cmdab:set more on}. See {help set more:set more}.{p_end} {p2col :{cmdab:pause on}}allows the usage of the command {cmdab:pause} which can be very useful during debugging. See {help pause:pause}.{p_end} {p2col :{cmdab:set varabbrev off}}allows users to abbreviate variable names similarly to command names such as gen for generate and reg for regress. However, while command abbreviation has strict rules constant across data sets, users, and Stata versions; variable name abbreviation does not have the same strict rules and consistency. While enabling variable abbreviation can speed up coding, it is an error-prone technique unless all users using a dofile with variable abbreviations organize their coding practices exactly the same way. See {help set varabbrev:set varabbrev} for more details and carefully consider this caution before enabling variable abbreviations in a collaborative dofile.{p_end} {p2line} {title:Options} {phang}{cmdab:v:ersionnumber(}{it:string}{cmd:)} sets a stable version of Stata for all users. Stata does not (for good reasons) allow a user-written command to alter the version setting from inside a command. Therefore, this option does {ul:nothing} unless "`r(version)'" is included as described in the {help ieboilstart##synt:syntax section}. While the version number cannot be set inside the command code, {cmd:ieboilstart} does two things. First it reminds the user to set the version since it is a required command. Second, it makes sure that the version number used is not too old. A too old version might risk that there are far too big a difference in many commands. Best practice is therefore to keep the same version number throughout a project, unless there is something specific to a newer version that is required for any dofile. Only major and recent versions are allowed in order to reduce errors and complexity. The valid versions are 11.0, 11.1, 11.2, 12.0, 12.1, 13.0, 13.1, 14.0, 14.1, 14.2, 15.0, 15.1, and all versions without decimals. However, it is recommended to use a .1 over a .0 version. .1 is free of charge if you already have the corresponding .0 and .1 includes bug fixes to the functions introduced in .0. All versions of Stata can be set to run any older version of Stata but not a newer. {p_end} {phang}{cmdab:maxvar(}{it:numlist}{cmd:)} manually sets the maximum number of variables allowed in a data set. The default is to set the number to the highest allowed. Reducing this number can occasionally improve performance, but modern computers running Impact Evaluations analysis are more likely to face the problem of too few variables allowed than running out of memory. The maximum number allowed in Stata 15.1 is 2047 in Stata IC; 32,767 in Stata SE; and 120,000 in Stata MP. This setting is ignored for users that use Stata IC or Small Stata.{p_end} {phang}{cmdab:matsize(}{it:numlist}{cmd:)} manually sets the maximum number of variables allowed in estimation commands, for example {help reg:regress}. The default is to set the number to the highest allowed in your version of Stata. Reducing this number can occasionally improve performance, but modern computers running Impact Evaluations analysis are more likely to run into problems by allowing too few variables than running out of memory. Although, this is more likely the case with {cmdab:maxvar} than with {cmdab:matsize}. The maximum number allowed is 800 in Stata IC and 11,000 in Stata MP or SE.{p_end} {phang}{cmdab:noclear} prevents the command from clearing/deleting the data set in working memory. No data may be in working memory in order to modify settings for maxvar, min_memory, max_memory and segmentsize. That is why the default is to clear the data set stored in working memory. Working memory is your RAM memory so no data saved to your hard drive will ever be deleted by this command. This command is intended to be placed at the very top of a dofile, so the data needed could be loaded into memory after running {cmd:ieboilstart}. For the reasons above, {cmdab:noclear} and {cmdab:maxvar()} cannot be combined.{p_end} {phang}{cmdab:q:uietly} suppresses two of three outputs this commands generates in the result window. The first output is a disclaimer warning the user that there is no guarantee that commands will always behave identically. The second output is a list of all the settings applied and their values..{p_end} {phang}{cmd:veryquietly} suppresses the third output this commands generates in the result window in addition to the two that {cmd:quietly} is suppressing. The third output is a reminder to set the version number using "`r(version)'" after running the command. {phang}{cmdab:c:ustom(}{it:string}{cmd:)} allows the user to add one or multiple custom lines of code. Each line of code should be separated with a "@". See example 2 below for more details.{p_end} {phang}{cmdab:setmem(}{it:string}{cmd:)}This option is only relevant for users of Stata 11. This value must be an integer followed by the letter B, K, M or G. The default if omitted is 50M. Cannot be used if versionnumber() is set to version 12.0 or more recent. See {help set memory} for more details. This link will only display options relevant to Stata 11 when clicking it in Stata 11. Otherwise it will show the options relevant to Stata 12 and later. {phang}{cmdab:noperm:anently(}{it:string}{cmd:)} is used to not change settings for future sessions of Stata. The default is that all settings are set as defaults so that they apply each time Stata starts after using this command. This option disable that. See option permanently in {help memory:memory} for mroe details. {cmd:set more off} is always set permanently.{p_end} {title:Examples} {pstd}{hi:Example 1.} {pmore}{inp:ieboilstart, versionnumber(11.1)} {break}`r(version)' {pmore}After running the two lines of code above all users will run their version of Stata as if the version was 11.1. That means that anyone who bought or upgraded Stata after June 2010 can use the command and all commands will behave identically for all those users. All other settings have been set to common best practice values. {pstd}{hi:Example 2.} {pmore}{inp:ieboilstart, versionnumber(12.1) custom(ssc install estout @ ssc install winsor)} {break}`r(version)' {pmore}In the example above, the version is set to 12.1. When running this command, it also makes sure that the user has the two commands {inp:estout} and {inp:winsor} installed. {title:Acknowledgements} {phang}I would like to acknowledge the help in testing and proofreading and suggestions I received in relation to this command and help file from (in alphabetic order):{p_end} {pmore}Michell Dong{break}John Dundas{break}Paula Gonzales{break}Seungmin Lee{break}Srujith Lingala{break}William Lisowski{break}Daniel Klein {marker auth}{...} {title:Author} {phang}All commands in ietoolkit is developed by DIME Analytics at DECIE, The World Bank's unit for Development Impact Evaluations. {phang}Main author: Kristoffer Bjarkefur, DIME Analytics, The World Bank Group {phang}Please send bug-reports, suggestions and requests for clarifications writing "ietoolkit ieboilstart" in the subject line to:{break} dimeanalytics@worldbank.org {phang}You can also see the code, make comments to the code, see the version history of the code, and submit additions or edits to the code through {browse "https://github.com/worldbank/ietoolkit":the GitHub repository of ietoolkit}.{p_end}