Preparing to analyze your data in Python


If you'd like to follow along with this tutorial but don't have a Python development environment set up, consider using Google Collab, a free service from Google Research.

Installation and Setup

First install the package.

pip install lamp-core

Then, import the library and connect to the server.

import LAMP
LAMP.connect('api.lamp.digital', 'my_email@address.com', 'my_password')


Protocol methods

Methods native to the LAMP API can now be called to pull data from the platform. These methods can be easily viewed on the API page.

For example, we can find all of the participants belonging to a Researcher:



#{'data': [{'id': 'U34260565',
#    'language': 'en',
#    'theme': '#359FFE',
#    'emergency_contact': None,
#    'helpline': None},
#   {'id': 'U33327158',
#    'language': 'en',
#    'theme': '#359FFE',
#    'emergency_contact': None,
#    'helpline': None}]}

For information on API object hiearchy, please see the


For example, the code below will make CSV files of all the 'lamp.gps.contextual' sensor events for all participants under a given researcher id:

import LAMP
import pandas as pd 

for participant in LAMP.Participant.all_by_researcher("me")['data']:
    data = []
    events = LAMP.SensorEvent.all_by_participant(participant['id'], origin='lamp.gps.contextual')['data']
    for event in events:
            'timestamp': event['timestamp'],
            'UTC time': "",
            'latitude': event['data']['latitude'],
            'longitude': event['data']['longitude'],
            'altitude': 1.0,
            'accuracy': 1.0
    # Don't make CSV files for participants without any `lamp.gps.contextual` events.
    if len(data) > 0:
        pd.DataFrame.from_dict(data, orient='columns').to_csv(f"{participant['id']}.csv", index=False)

To learn more about the data types available for Activities and Sensors, see here:

Dataframe methods

Pandas dataframe-based functionality has been implemented on top of the protocol methods to allow users to more easily work with data. This functionality is in the form of "Cohort" and "Subject" objects.

Subject objects

Subjects are designed to represent individual LAMP participants. The objects have various properties and methods that will discussed here and can be viewed in more detail in the "subject.py" file.

Subjects are be initialized with their LAMP id, as well as various other (optional) fields:

subject_1 = lamp.Subject(id = TEST_PARTICIPANT)

subject_2 = lamp.Subject(id = TEST_PARTICIPANT2, 
												 domains = ['Anxiety', 'Mood'], 
												 age = 42, 
												 sex = 'F',
												 beiwe_filepath = '/path/to/beiwe_data')

Integrated data can now be viewed in the Subject's df:

#           Date         id   Anxiety      Mood
# 0   2018-08-22  U34260565       NaN       NaN
# 1   2018-08-23  U34260565  0.857143  1.000000
# 2   2018-08-24  U34260565       NaN       NaN
# 3   2018-08-25  U34260565       NaN  1.111111
# 4   2018-08-26  U34260565       NaN       NaN
# ..         ...        ...       ...       ...
# 115 2018-12-15  U34260565       NaN       NaN
# 116 2018-12-16  U34260565       NaN       NaN
# 117 2018-12-17  U34260565       NaN       NaN
# 118 2018-12-18  U34260565       NaN       NaN
# 119 2018-12-19  U34260565       NaN       NaN

# [120 rows x 4 columns]

To create this dataframe, "Subject.create_subject_df()" is automatically called upon Subject initialization. A dataframe with customizable properties can also be generated after intialization:

import datetime

subject_1.create_subject_df(days_cap=10, day_first=datetime.datetime(year=2018, month=8, day=24).date())
#         Date           id   Anxiety      Mood
# 0 2018-08-24  U1684566141       NaN       NaN
# 1 2018-08-25  U1684566141       NaN  1.111111
# 2 2018-08-26  U1684566141       NaN       NaN
# 3 2018-08-27  U1684566141  1.714286       NaN
# 4 2018-08-28  U1684566141       NaN       NaN
# 5 2018-08-29  U1684566141  1.571429  1.111111
# 6 2018-08-30  U1684566141       NaN       NaN
# 7 2018-08-31  U1684566141       NaN       NaN
# 8 2018-09-01  U1684566141       NaN       NaN
# 9 2018-09-02  U1684566141       NaN       NaN

Cohort objects

If you have many participants that would like to group together as a cohort, you can do so with the Cohort object.

Cohorts consist of one or many Subject objects. They are initialized with a list of valid LAMP ids, along with other (optional) parameters:

test_cohort = lamp.Cohort(subjects = ['U1234567', 'U33327158'])

for subject in test_cohort:
# U1234567
#         Date         id      Mood   Anxiety  beta_a  beta_b
# 0 2020-02-27  U1234567  2.555556  2.428571     NaN     NaN

# U33327158
#         Date         id     Sleep  Psychosis   Anxiety  beta_a  beta_b
# 0 2020-02-27  U33327158  2.333333        1.4  1.428571     NaN     NaN

Many methods are shared between Subject and Cohort objects. More details on Cohort objects can be viewed in the "cohort.py" file.

Was there something we didn't cover, or need more help? Let us know by making a post in the LAMP Community, or contact us directly. Thank you for your contribution! 🌟 Page last updated on August 10th, 2020.