*! version 0.2 16 NOV 2019
help dependenciesalso see: adopath sysdir net ssc

Title

dependencies -- Manages user-written commands for reproducible code (ado version freeze)

Syntax

Manages user-written commands required in a project (dependencies) to ensure reproducibility of all code, as ado files available online may change. This is achieved by freezing the current version of installed packages into a zip file, and later unfreezing it into an adopath that takes top priority.

dependencies subcommand [ usingfilename.zip ], [ adolist(string) all replace ]

Options

Subcommand: one and only one required
freeze save filename.zip with the dependencies passed in adolist or all

unfreeze unzip to dependencies adopath the frozen dependencies in filename.zip

which list whethever is currently in the dependencies adopath

remove remove the dependencies adopath and all its contents

Using: required for freeze/unfreeze
using indicates the zipfile to be written/read

Others: for freeze only
adolist(string) freeze the selection of commands in adolist (cannot be combined with all)

all freeze everything in the adopath that is properly registered in stata.trk (cannot be combined with adolist)

replace freeze will replace the using filename.zip if it already exists

Description

dependencies manages required user-written commands for a project (dependencies) to ensure reproducibility of all code, as ado files available online may change. This is achieved by freezing the current version of installed packages into a zip file, and later unfreezing it into an adopath that takes top priority.

For example, suppose a project uses a package that is available in SSC. You could include in your master run do file a line to install the required package on the fly from ssc - but if the version in ssc changes, you may run into compatibility issues. This could happen because ssc install will always retrieve the most up to date version of a package.

The suggested use of dependencies is:

( 1 ) create of a zip file with all dependencies, which should be saved with all the project code. This is done by dependencies freeze

( 2 ) add to the start of your project master run do file dependencies unfreeze

( 3 ) include at the end of your project master run do file dependencies remove

Though there is no harm in forgetting to remove the dependencies after usage, you may find yourself in trouble when trying to update or use a more recent version of a command that was copied into the dependencies priority adopath.

At any given point, call dependencies which to check the ado files currently in the dependencies priority adopath. This functionality also displays the date of freeze, making use of the metadata file dependencies.trk that is included in any zip file created or unpacked through dependencies, analogous to the automatically generated registry of installed packages stata.trk.

Options

Subcommand

freeze save a zip file with the current version of the dependencies. Requires option using filename.zip and either adolist(string) or all.

unfreeze unzip to dependencies adopath the frozen dependencies from a zipfile. Requires option using filename.zip.

which list whethever ado files are currently in the dependencies adopath. No additional options accepted.

remove remove the dependencies adopath and all its contents. No additional options accepted.

Using

using filename.zip indicates the zip file to be written if subcommand freeze or read if subcommand unfreeze.

Others

adolist(string) freeze a selection of commands, passed in adolist. Cannot be combined with all. Multiple commands and packages can be passed in the same string, separated by spaces. First, the adopath registries of installed packages -stata.trk- are searched for matching packages, then, remaining commands are searched as standalone files in the adopath by findfile. Commands that are not found will trigger a warning display but won't cause errors.

all freeze everything in the adopath for which a corresponding entry in the adopath registries of installed packages -stata.trk- exists (multiple files are appended / combined). Cannot be combined with adolist.

replace freeze will replace the zip file specified in using filename.zip if it already exists.

Examples

Suppose your project requires the commands iegraph and iematch, which are part of the awesome package ietoolkit, available in SSC and in GitHub. Your project runs well with the version of ietoolkit that you have currently installed. Maybe you even had already included a provisional installation from SSC in your master do file:

. `"cap ssc install ietoolkit"'

But you want to make sure your project will be reproducible as is. Thus, you freeze the dependencies:

. `"dependencies freeze using dependencies_myproject.zip, adolist(iegraph iematch)"'

Note that you could also have listed the whole package instead of naming just some of its components:

. `"dependencies freeze using "dependencies_myproject.zip", adolist(ietoolkit) replace"'

Moreover, you learn that if you list both the package and the components, it's equivalent to just listing the package. Thus it's a bit silly (but won't break) to request:

. `"dependencies freeze using "dependencies_myproject.zip", adolist(ietoolkit iegraph iematch) replace"'

For reproducibility, your master run do file will not install ietoolkit from SSC on the fly. Instead, you unfreeze the dependencies at the beginning:

. `"dependencies unfreeze using "dependencies_myproject.zip" "'

At the end of your master run, it's recommended that you remove the dependencies, to avoid trouble when trying to update or use a more recent version of those commands in the future.

. `"dependencies remove"'

At any time, you can consult the contents of your dependencies adopath:

. `"dependencies which"'

Author

Diana Goldemberg

diana_goldemberg@g.harvard.edu

Acknowledgements

Kristoffer Bjarkefur and Joao Pedro Azevedo provided invaluable contributions to this package. The idea for the command was originated in this statalist discussion. A big thank you to all contributors creating commands for the Stata community, especially in SSC! Without your time and effort, this command would be useless.

You can see the code, make comments to the code, report bugs, and submit additions or
edits to the code through the GitHub repository of dependencies.