How to post Stata program via Dropbox or private website?

Question

Here is a sample program .do file, sampleprog.do:

program sampleprog
egen newVar = group (`1' `2')
end

How can I post it on my website (or dropbox), so that other people could install it to their Stata like this?

net from http://www.mywebsite.com/sampleprog.do
*** or may be like like this:
ssc install ...

I read the documentation about stata.toc...but I did not quite get it. What files should I upload and should it be one folder or what?

(PS: I definitely can simply email the .do file but this is not an option in my case.)

Answer 1

Here is a full explanation of how to share program or data files with others using your own website. I tried using Dropbox, but Stata 12 appears to have issues with https, which is the protocol for all Dropbox public links. If you want to use Dropbox, I recommend creating a shared folder that will sync on your collaborators' machines. The rest of this answer assumes you have a website serving pages over http or are using Stata 13, which supports https.

If this is a one-time thing, you can skip the rest of this answer by putting the file on your website and telling your collaborator to type:

. copy http://your-site.com/ado/program.ado program.ado

That will copy the ado file at the specified url into the user's current directory. If you want to provide information about your files, plan on sharing with multiple people and need to maintain/document a set files, read on!

Step 1 Create a folder on your website to hold the programs. I will call mine ado/

Step 2 Add the program files, help files, and data files you want to share. For this example, I have created a simple ado file called unique.ado with the following contents:

********************************************** unique.ado
capture program drop unique
program define unique
    *! Count and number observations within group defined by varlist
    *  Example: unique person_id, obs(prow) tobs(pcount) sortby(time)
    *           to count and number rows by a variable called person_id
    syntax varlist, obs(name) tobs(name) [sortby(varlist)]
    bys `varlist' (`sortby') : gen long `obs' = _n
    bys `varlist' (`sortby') : gen long `tobs' = _N
    la var `obs' "Number of this row within `varlist' group."
    la var `tobs' "Total number of rows with identical `varlist' values."
end

Step 3 Create a file called stata.toc to describe the files you wish to share. Here is mine:

********************************************** stata.toc
v 3
d Program to count observations by group
p unique [The unique.ado program for counting observations by group]

These files can be complicated. There are many features I won't cover here, but you can read this documentation to learn more.

Step 4 Create a package file for each of the packages defined by the lines in stata.toc that start with the letter p. Here is my package file for the unique package defined above:

********************************************** unique.pkg
v 3
d unique
d Program to count observations by group
d Distribution-Date: 28 June 2012
f unique.ado

Your directory now looks like this:

ado/
    stata.toc
    unique.ado
    unique.pkg

Step 5 Use the site! Here are the commands to enter.

. net from http://example.com/ado/
. net describe unique
. net install unique

Here is what you'll see after entering the first command:

-----------------------------------------------------------------------------------
http://www.example.com/ado/
Program to count observations by group
-----------------------------------------------------------------------------------

PACKAGES you could -net describe-:
    unique            [The unique.ado program for counting observations by group]
-----------------------------------------------------------------------------------

The second command will tell you more about the package net describe unique:

---------------------------------------------------------------------------------------
package unique from http://www.example.com/ado
---------------------------------------------------------------------------------------

TITLE
      unique

DESCRIPTION/AUTHOR(S)
      Program to count observations by group
      Distribution-Date: 28 June 2012

INSTALLATION FILES                               (type net install unique)
      unique.ado
---------------------------------------------------------------------------------------

The third command will install the package net install unique:

checking unique consistency and verifying not already installed...
installing into /Users/cpoliquin/Library/Application Support/Stata/ado/plus/...
installation complete.

EDIT

See Nick's comments in the answer below. I intended this example to be simple and I don't expect other people to use this program. If you plan on submitting things to Stata Journal or SSC then his comments certainly apply! I hope this answer can serve as a decent tutorial for those confused by the official documentation.

Answer 2

This will be too long for a comment, so it is going to be an extra answer.

1. Your example uses the program name unique. If you search unique, all (or in Stata 13, search unique) you will find that a user-written program with the same name has been installed on SSC since 1998. This will create a clash of names for your users if (and only if) they attempt to use your program and also that earlier program. The more general advice is to search to see if a program name is already in use to try to avoid these problems.

2. Specifically, although you may just be using your unique as an arbitrary example, note that it contains bugs. An int doesn't contain enough bits to hold observation numbers exactly for large datasets. Also, as a matter of style, unique can change the sort order of your data, which is widely considered to be poor data management style.

3. Your example concerns dissemination of a program file without an accompanying help file. Suffice it to say that the SSC site would never accept such a program and the Stata Journal would not even review a paper based on such a submission before a help file was written to accompany it. Including explanatory comments with the code may be sufficient for your personal practices, but it falls below general Stata standards.

4. Stata 13 now supports https. See http://www.stata.com/manuals13/u.pdf, Section 3.6.

In short, I appreciate that you are trying to explain how to do something, but it is already well documented, and explicitly and implicitly some of your recommendations are below community standards.