<<<<<<< HEAD

Hybrid-Physical-Digital-Spaces

Repo for HPDS, "The Building Project," supervised by James Landay and Liz Murnane.

Getting Started

Welcome to Hybrid-Physical-Digital-Spaces! Thank you for stopping by.

This repository contains the code for an iOS-based data collection app (collects biometric and experience-sampling-method momentary assessment data from users), and a series of Python scripts to aggregate the data for processing and analysis.

These instructions will get you copies of the iOS app and Python scripts up and running on your local machine for development and testing purposes.

Prerequisites

This project requires XCode 9.4.1 and Python 3 (links to download pages). All XCode frameworks/pods are included within the repository.

Setup - HPDS Mobile (iOS) Client

Navigate into the directory on your computer where you would like to place the project folder. Then type the following command to download the project.

$ git clone --recursive https://github.com/StanfordHCI/Hybrid-Physical-Digital-Spaces.git

The --recursive flag tells git to install the submodules that this project uses. If you have installed the project but it is missing one or more, navigate to the project folder in your terminal, then enter the following two commands to install the project's submodules:

$ git submodule init

$ git submodule update

Now that the project submodules are installed, navigate into the Hybrid-Physical-Digital-Spaces directory, then into HPDS-Data. Open up the file with the .xcworkspace extension (not the .xcproject) in XCode. From here, you can make various edits, add features, have a party, etc.

Setup - Python Scripts

Before running the Python scripts on your computer, there are some libraries that you may need to install.

To do so, navigate into the project folder, then run the following command (if you wish you may setup a virtual environment beforehand):

$ pip install -r requirements.txt

After this, you should be able to run the command $ python3 [filename] to run the file [filename].py.

Committing Changes

To commit changes to the repo, save all of your changes locally, then navigate into the project folder from your terminal. Then, type the following commands:

$ git add .
$ git commit -m “[message]”

Where “message” (inside quotes but no need for the square brackets), is a brief description of the changes you have made since last committing to the repo. Next, type,

$ git push origin master

And this should update the repository to the version running locally on your machine. :)

The rule of thumb with which I am familiar is to "commit whenever something works”. This means you probably shouldn't quite commit as often as you save, but once progress has been made (even if it's a small tweak), don’t be hesitant to commit your changes.

When starting work on a project each day, you should confirm that you are working on the latest version of the codebase. To do so, navigate to the project folder in your terminal, then type,

$ git pull

This will ensure your local copy of the code is up to date with the latest version in the codebase.

Orientation

Below, you will find descriptions of some of the key files in the project:

XCode:

AppDelegate.swift: Contains the code necessary to get the sensors up and running, and sending data to the AWARE server.
ViewController.swift: Provides the syncSensors function (though sensors sync automatically, this enables the "Sync Sensors" button you will find on the home screen), openEmail function (which enables the user to contact the researchers running the study), and the researchKitSurvey function (which starts a survey through ResearchKit).

Python:

read_building_data.py: Upon being passed in the filename of a .csv file containing building or Qualtrics survey data (since Stanford Qualtrics does not allow API access, to read in the data, one must download the Qualtrics responses as a .csv file, then run this script on the downloaded file), this program creates a Pandas dataframe of the building data.
read_sql_remote_data.py: This program pulls data from a remote SQL database and reads it into a Pandas dataframe. By default, this script is set up to pull data from an AWARE server (though this can be altered by modifying the host and credentials).

Deployment

To deploy the HPDS Mobile Client to an iOS simulator or to a live device:

Follow the instructions at this tutorial to set up an AWARE server. (There is currently a test server to which data is forwarded, but it is linked to Michael Cooper's SUID, so you may want to set up another one to test on).
Update the getUrl() -> String function in AppDelegate.swift to return the url of your new AWARE server. Additionally, update the variable email under the openEmail function in ViewController.swift to an email at which you would like users to be able to reach you.
Build and run the project in XCode. From XCode, you can set the simulated device on which you would like the project to run. To run on a live device, plug the device into your computer. After a few seconds, the device should become available to select from the menu in the top-left corner (to the right of the play button). Select your device, then run the project.

Data Collection

The following instructions detail how to collect data from a deployment of the HPDS Mobile Client:

Create a new Python file for your data analysis. At the top of the file, add the lines:

from read_sql_remote_data import gen_df_from_remote_SQL
from read_csv_data import read_csv_data

Call the functions in your analysis file with the required parameters. Each function call will return a pandas dataframe.

Built With

AWARE Framework iOS
ResearchKit

Contributing

See CONTRIBUTING.md for more project context and contribution instructions/guidance!

Authors

Michael Cooper
Alex Weitzman
Gabe Saldivar
Andrew Ying

License

Acknowledgments

Yuuki Nishiyama for his work on the AWARE Framework iOS, and for his AWARE Framework tutorials, which were used in the development of this application.

Stephen Groom on StackOverFlow. His solution to send an email from an iOS app was used in this project.

Tutorials for Reference

Here are a list of tutorials that were used over the course of this project. The hope here is that, if you are not familiar with some of the design elements of the HPDS-Data app, these resources will enable you to quickly bring yourself up to speed.

(I'm sorry I took 5 mins uploading everything so this README is in need of some work - but hopefully it indicates what everything here is so that you aren't lost). :)

Basic Study Platform - a basic platform to display an atmosphere behind a study task.
Platform with Recording - experiments with using the RecordRTC JavaScript library to record the user while they are doing the task. Currently it records the video of the user during the task and plays it back (the library has capabilities to send the recording to a server but this is to-be-implemented).
HPDS-Posenet-Python - a Python port of the PoseNet library, which is one technique we're considering using to determine if the subject is looking at the screen and paying attention to the task at hand. Nothing from this has yet been integrated.
HR Analysis - work on analyzing heart rate from a video signal. It includes visualize_video_signal.py which is some experimental code I wrote which uses EVM (Eulerian Video Magnification) to output a graph of heart rate over time (but this doesn't work very well). Our current development direction references the iphys-toolbox (https://github.com/danmcduff/iphys-toolbox), a MATLAB repo which should work much better. Currently resolving MATLAB licensing issues on my (Michael's) end to unblock on this part of development.

If you've got any questions, please Slack me and I'll be happy to help answer.

c224143cadb0e04fa4b1e543b0f20cfb0df2e661

StanfordHCI/HPDS-Online-Platform