The timeline follow-back is a method for retrospectively ascertaining recent alcohol and other substance use history, developed by Linda C. and Mark B. Sobell. This software is a web-based timeline form developed for the MGH Center for Addiction Medicine and designed for use with REDCap databases in clinical research.
This open-source software1 is developed by by Michael Pascale and maintained by Zach Himmelsbach. A major revision in Typescript was finished in 2024 by Ivy Zhu. Additional contributions have been made by Bryn Evohr, Kevin Potter, and Lindsay Nielsen.
Adapted from the the clinical procedure, Sobell L.C. & Sobell M.B. (1992), and from the timeline follow-back application developed for the Adolescent Brain Cognitive Development study. See also another application by the University of Washington.
Made possible with FullCalendar, Bulma, TypeScript and Webpack.
You may run the web application on your own local machine or you will need to self host this application on a static web server. Your institution may have this capacity and may also have rules governing the use of software.
Download and copy the following libraries to the static/ directory.
bulma.min.css(Bulma v0.9.4)fonts/material-icons.css(Material Design Icons v7.0.96)
You'll also need to install Node.js which provides npm (Node Package Manager). You'll need this to install TypeScript and Webpack.
On MacOS, the easist way to install Node is with brew (Homebrew). Alternatively, you can use nvm (Node Version Manager).
brew install node@18Using npm, we can now automatically install all the packages listed in package.json.
npm installThe application consists of what you see in index.html and the TypeScript under src/.
We won't be using the TypeScript compiler tsc directly. Instead, Webpack will compile and then bundle all of our code into a single JavaScript file under static/tlfb-v3-bundle.js.
webpack-dev-server provides hot reload each time you save a TypeScript file. See the head of index.html to correct the path, then run webpack.
npx webpack serveThis will start the development server, and you should be able to open the webpage by going tolocalhost:8080 in your web browser.
See the head of index.html to correct the script paths, then run webpack.
npx webpackThis will create the final bundle under static/tlfb-v3-bundle.js.
Simply copy index.html and the static/ directory onto your production webserver.
For accuracy and efficiency, the timeline followback settings can be autofilled using data from REDCap passed in the URL query string.
Add a Project Bookmark to the REDCap sidebar in your project settings. Using an "advanced link" will allow you to customize the fields using Smart Variables. Alternatively, you can embed a link in any form of your REDCap project. For the REDCap Event and Record ID to autofill correctly, bookmark must be clicked from within a specific record and event.
For example, your project bookmark URL might look like:
https://your-web-server.example.com/tlfb/?record=[record-name]&pid=[project-id]&event=[event-name]&subject=[study_level_arm_1][record_subject_id]&start=[tlfb_start_date]&end=[tlfb_end_date]&keyfield=subject_id&staff=[tlfb_compby]
The application accepts record, pid, event, subject, start, end, keyfield, and staff in the query string.
startandenddefine the calendar date range visible for the user to fill in and should be passed in YYYY-MM-DD format. You can use calculated fields to determine the appropriate date range.keyfieldis the study-specific subject identifier field name (e.g. "subject_id"), if your study uses a subject identifier that is separate from the record identifier. The app collects the subject field name because this is not a standard redcap feature.subjectis the actual subject identifier (e.g. "S472"). In contrast, the REDCap Record ID (record) must exist in all REDCap projets.
Current versions (v3.0.0+) run entirely in client side JavaScript and do not transmit information 2. The downloaded CSV may be processed and, optionally, manually imported to a REDCap instrument.
If the data is to be imported into REDCap, a repeating instrument will be necessary to capture each substance use event. An example form is provided in this REDCap Instrument ZIP. Alternatively, you may elect to use your own software to summarize the exported CSV.
After the researcher has completed the procedure, the calendar must be downloaded from the application to be saved temporarily on the researcher's computer. Two export formats are available. Both formats include the metadata passed in via the query string (or modified in the TLFB Properties window), the application version, and the list of substance use events and key events.
This tabular format include the session metadata in a header. With some modification, the CSV can be uploaded to a REDCap repeating instrument. Alternatively, the data file may be stored separately for processing by custom software.
Data may also be exported in JSON format.
Click to expand an example of data stored in JSON format.
Lisdahl, K. M., Sher, K. J., Conway, K. P., Gonzalez, R., Feldstein Ewing, S. W., Nixon, S. J., Tapert, S., Bartsch, H., Goldstein, R. Z., & Heitzeg, M. (2018). Adolescent brain cognitive development (ABCD) study: Overview of substance use assessment methods. Developmental Cognitive Neuroscience, 32, 80–96. https://doi.org/10.1016/j.dcn.2018.02.007
Nova Southeastern University. (n.d.). Timeline Followback Forms and Related Materials. NSU Guided Self-Change. Retrieved August 9, 2021, from https://www.nova.edu/gsc/forms/timeline-followback-forms.html
Robinson, S. M., Sobell, L. C., Sobell, M. B., & Leo, G. I. (2014). Reliability of the Timeline Followback for cocaine, cannabis, and cigarette use. Psychology of Addictive Behaviors, 28(1), 154–162. https://doi.org/10.1037/a0030992
Sobell, L. C., Brown, J., Leo, G. I., & Sobell, M. B. (1996). The reliability of the Alcohol Timeline Followback when administered by telephone and by computer. Drug and Alcohol Dependence, 42(1), 49–54. https://doi.org/10.1016/0376-8716(96)01263-X
Sobell, L. C., & Sobell, M. B. (1992). Timeline Follow-Back. In R. Z. Litten & J. P. Allen (Eds.), Measuring Alcohol Consumption: Psychosocial and Biochemical Methods (pp. 41–72). Humana Press. https://doi.org/10.1007/978-1-4612-0357-5_3
Source code is copyright © 2021-2025 Michael Pascale, © 2024 Ivy Zhu, and distributed under the MIT License.
Footnotes
-
This software is open source and available without warranty under the terms of the MIT License, which you may find in the LICENSE file. See this primer on open-source software from WashU if this is not something you are familiar with. ↩
-
Previous versions of the application used the REDCap API to load data into REDCap (see the ABCD study's PHP application) and therefore required data to be transmitted to the webserver. The current version runs in the web browser and does not store data nor transmit data to the server. ↩
{ "subject": "TEST_001", "event": "visit_4_arm_1", "pid": "0", "start": "2025-04-01", "end": "2025-04-30", "staff": "research assistant", "record": "1", "keyfield": "subject_id", "datetime": "2025-05-14T15:06:09.304Z", "appversion": "3.0.1", "events": [ { "_eid": 1, "_gid": 1, "_title": "Smoked Cannabis 5x | 4 hits", "_date": "2025-04-01T00:00:00.000Z", "_type": "use", "_category": "cb", "_substance": "Cannabis", "_methodType": "Bowls", "_methodTypeOther": null, "_method": "Smoked Cannabis", "_methodOther": null, "_times": 5, "_amount": 4, "_units": "hits", "_unitsOther": null, "_note": "" }, // Additional substance use events... { "_eid": 76, "_gid": 51, "_title": "Vaped Cannabis 6x | 2 hits", "_date": "2025-04-29T00:00:00.000Z", "_type": "use", "_category": "cb", "_substance": "Cannabis", "_methodType": "Vape pen", "_methodTypeOther": null, "_method": "Vaped Cannabis", "_methodOther": null, "_times": 6, "_amount": 2, "_units": "hits", "_unitsOther": null, "_note": "" } ] }