Merge branch 'develop' into hackdna/citation

.github/workflows/build.yml

@@ -1,28 +1,35 @@
 # Install Python dependencies and run tests
+name: 'Build and test'
 
-name: build
-
-on: push
+on:
+  push:
+  workflow_dispatch:
 
 jobs:
-  build:
+  test:
+    name: 'Run tests'
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
         os: ['ubuntu-22.04', 'windows-2022', 'macos-12']
     steps:
-      - name: Checkout Forest code from GitHub repo
-        uses: actions/checkout@v3
+      - name: Check out Forest code
+        uses: actions/checkout@v4
       - name: Set up Python
         uses: actions/setup-python@v4
         with:
           python-version: 3.8
-      - name: Install Forest dependencies
+      - name: Install Forest dependencies for Linux
         # required by librosa
         if: ${{ startsWith(matrix.os, 'ubuntu') }}
         run: |
           sudo apt-get update
           sudo apt-get install -y ffmpeg libsndfile1
+      - name: Install Forest dependencies for Windows
+        # required by librosa
+        if: ${{ startsWith(matrix.os, 'windows') }}
+        uses: FedericoCarboni/setup-ffmpeg@v2
+        id: setup-ffmpeg
       - name: Install Forest
         run: pip install -e .
       - name: Install dev dependencies
@@ -35,19 +42,3 @@ jobs:
         run: python -m unittest tests/imports.py
       - name: Run pytest suite
         run: pytest
-  build_docs:
-    runs-on: ubuntu-22.04
-    defaults:
-      run:
-        working-directory: ./docs
-    steps:
-      - name: Checkout Forest code from GitHub repo
-        uses: actions/checkout@v3
-      - name: Set up Python
-        uses: actions/setup-python@v4
-        with:
-          python-version: 3.8
-      - name: Install documentation build dependencies
-        run: pip install -r requirements.txt
-      - name: Build the docs
-        run: make html SPHINXOPTS="-W"

.github/workflows/docs.yml

@@ -0,0 +1,24 @@
+name: Sphinx documentation
+
+on:
+  push:
+  workflow_dispatch:
+
+jobs:
+  build-html-docs:
+    name: 'Build HTML docs'
+    runs-on: 'ubuntu-22.04'
+    defaults:
+      run:
+        working-directory: './docs'
+    steps:
+      - name: Check out Forest code
+        uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.8
+      - name: Install documentation build dependencies
+        run: pip install -r requirements.txt
+      - name: Build HTML docs
+        run: make html SPHINXOPTS="-W"

.gitignore

@@ -1,8 +1,9 @@
 __pycache__/
 .DS_Store
 
-# IntelliJ project files
+# IntelliJ, VsCode project files
 .idea
+.vscode
 
 # for installing Forest in editable mode when developing
 /forest.egg-info/
@@ -18,3 +19,6 @@ __pycache__/
 
 #sphinx build
 docs/_build/
+
+# any python environment files
+.python-version

README.md

@@ -117,7 +117,7 @@ sample_gps_data = sim_gps_data(n_persons, location, start_date, end_date, cycle,
 gps_to_csv(sample_gps_data, path_to_synthetic_gps_data, start_date, end_date)
 
 # 2. Specify parameters for imputation 
-# See https://github.com/onnela-lab/forest/wiki/Jasmine-documentation#input for details
+# See https://forest.beiwe.org/en/latest/jasmine.html for details
 # time zone where the study took place (assumes that all participants were always in this time zone)
 tz_str = "Etc/GMT-1"
 # Generate summary metrics e.g. Frequency.HOURLY, Frequency.DAILY or Frequency.HOURLY_AND_DAILY (see Frequency class in constants.py)
@@ -128,12 +128,8 @@ save_traj = False
 parameters = None
 # list of locations to track if visited, leave None if don't want these summary statistics
 places_of_interest = ['cafe', 'bar', 'hospital']
-# True if want to save a log of all locations and attributes of those locations visited
-save_osm_log = True
 # list of OpenStreetMap tags to use for identifying locations, leave None to default to amenity and leisure tagged locations or if you don't want to use OSM (see OSMTags class in constants.py)
 osm_tags = None
-# threshold of time spent in a location to count as being in that location, in minutes
-threshold = 15
 
 # 3. Impute location data and generate mobility summary metrics using the simulated data above
 gps_stats_main(
@@ -144,9 +140,7 @@ gps_stats_main(
     save_traj = save_traj,
     parameters = parameters,
     places_of_interest = places_of_interest,
-    save_osm_log = save_osm_log,
-    osm_tags = None,
-    threshold = threshold,
+    osm_tags = osm_tags,
 )
 
 # 4. Generate daily summary metrics for call/text logs

docs/source/index.md

@@ -70,7 +70,7 @@ Forest structure is based in subpackages, or *trees*, each of which addresses a
 
 ## Expected input data
 
-Input data should be included in one directory. Inside that directory, there should be a direct subdirectory corresponding to each participant ID. Inside each Beiwe ID subdirectory, there should be a direct subdirectory corresponding to each downloaded data stream.
+Input data should be included in one directory. This directory cannot be on a cloud server. Inside that directory, there should be a direct subdirectory corresponding to each participant ID. Inside each Beiwe ID subdirectory, there should be a direct subdirectory corresponding to each downloaded data stream.
 
 Methods are designed to work on data collected using the Beiwe app, with the types of sensor on/off cycles run by the Beiwe app, and with the csv files containing columns generated by Beiwe or generate data matching the data returned from the Beiwe app. Some methods included in Forest are compatible with other data collection environments, but code changes would be required to make Forest work well with those environments.
 
@@ -170,15 +170,15 @@ The summary statistics that are generated are listed below:
   - Entropy measure based on the proportion of time spent at significant locations over the course of a day
   - Letting p_i be the proportion of the day spent at significant location I, significant location entropy is calculated as   -\sum_{i} p_i*log(p_i), where the sum occurs over all non-zero p_i for that day.
 * - mis_duration
-  - Float
+  - Not Available
   - Number of hours of GPS data missing over the course of a day
   - 
 * - Physical circadian rhythm
-  - Not Available
+  - Float
   - A continuous measurement of routine in the interval [0,1] that scores a day with 0 if there was a complete break from routine and 1 if the person followed the exact same routine as have in every other day of follow up
   - For a detailed description of how this measure is calculated, see Canzian and Musolesi's 2015 paper in the Proceedings of the 2015 ACM International Joint Conference on Pervasive and Ubiquitous Computing, titled "Trajectories of depression: unobtrusive monitoring of   depressive states by means of smartphone mobility traces analysis."   Their procedure was followed using 30-min increments as a bin size.
 * - Physical circadian rhythm stratified
-  - Not Available
+  - Float
   - A continuous measurement of routine in the interval [0,1] that scores a day with 0 if there was a complete break from routine and 1 if the person followed the exact same routine as have in every other day of follow up
   - Calculated in the same way as Physical circadian rhythm, except the procedure is repeated separately for weekends and weekdays.
 ```