From 4dcf65d575c974d565b5b34203bc872b624de118 Mon Sep 17 00:00:00 2001 From: nleo575 <38141307+nleo575@users.noreply.github.com> Date: Fri, 6 Mar 2020 16:46:25 -0500 Subject: [PATCH] Restructured instructions for clairty. --- docs/usage/installation.rst | 72 ++++++++++++++----------------------- 1 file changed, 27 insertions(+), 45 deletions(-) diff --git a/docs/usage/installation.rst b/docs/usage/installation.rst index 5f936fa8..ab64a1fa 100644 --- a/docs/usage/installation.rst +++ b/docs/usage/installation.rst @@ -3,10 +3,10 @@ Installation =============== -This instructions have been tested on MacOS Catalina and Mojave and Ubuntu 16.04. If you find a problem, please report it. +This instructions have been tested on macOS (Catalina and Mojave) and Ubuntu 16.04. If you find a problem, please report it on our GitHub page. -Mac OS (tested on Catalina) ----------------------------- +macOS (tested on Catalina 10.15) +-------------------------------- #. Install dependenies (Homebrew if not installed): @@ -36,47 +36,17 @@ Mac OS (tested on Catalina) #. Create a python virtual environment: - ``cd rapids`` - - ``conda env create -f environment.yml -n MY_ENV_NAME`` - - ``conda activate MY_ENV_NAME`` + - ``conda env create -f environment.yml -n rapids`` + - ``conda activate rapids`` #. Install r packages and virtual environment: - ``snakemake packrat_install`` - ``snakemake packrat_init`` - ``snakemake packrat_restore`` + - This step will take several minutes to complete. Please be patient and let it run until completion. - -#. Configure the participants to analyze: - - - Create a file per participant in the ``/data/external`` folder, no extension is necessary, its name will be the label for that participant in the pipeline: ``/data/external/pxx`` - - Add a line with the device_id(s) of that participant as it appears on the database. If multiple device ids, all data for this participant will be relabeled with the last one - - Add a line with the mobile platform (android, or ios) - - For example: - - .. code-block:: bash - - 3a7b0d0a-a9ce-4059-ab98-93a7b189da8a,44f20139-50cc-4b13-bdde-0d5a3889e8f9 - android - - -#. Configure the db connection: - - - Create an empty .env file in the root folder - - Add and complete the following lines: - - | ``[MY_GROUP_NAME]`` - | ``user=MyUSER`` - | ``password=MyPassword`` - | ``host=MyIP`` - | ``port=3306`` - - -#. Once the all of the installation and configurations has been completed the following command can be run to pull the default sample dataset that comes with this project.:: - - $ snakemake - - -This pulls sample data from AWARE_ and processes it with the default rules that come with RAPIDS. +#. See Usage section below. Linux (tested on Ubuntu 16.04) @@ -117,22 +87,32 @@ Linux (tested on Ubuntu 16.04) - ``snakemake packrat_install`` - ``snakemake packrat_init`` - ``snakemake packrat_restore`` + - This step will take several minutes to complete. Please be patient and let it run until completion. -#. Configure the participants to analyze: +#. See Usage section below. - - Create a file per participant in the ``/data/external`` folder, no extension is necessary, its name will be the label for that participant in the pipeline: ``/data/external/pxx`` - - Add a line with the device_id(s) of that participant as it appears on the database. If multiple device ids, all data for this participant will be relabeled with the last one - - Add a line with the mobile platform (android, or ios) - - For example: + +Usage +====== +Once you have the installation for your specific operating system complete, you can follow these steps to get starting using the pipeline. + +#. Configure the participants you want to analyze: + + - Create one file per participant in the ``rapids/data/external/`` directory. The file should NOT have an extension (i.e. no .txt). The name of the file will become the label for that participant in the pipeline. + - The first line of the file should be a comma separated list with each of the device ID numbers for that participant as it appears in AWARE. + - If AWARE is removed and reinstalled on the device, a new device ID is generated. + - The second line should list the device's operating system (Android or iOS) + - As an example. Let's say participant `p00` had 2 AWARE device_id numbers and was running Android OS. Their file would be named `p00` and contain: .. code-block:: bash 3a7b0d0a-a9ce-4059-ab98-93a7b189da8a,44f20139-50cc-4b13-bdde-0d5a3889e8f9 android -#. Configure the db connection: - - Create an empty .env file in the root folder +#. Configure the database connection: + + - Create an empty file called `.env` in the root directory (rapids/) - Add and complete the following lines: | ``[MY_GROUP_NAME]`` @@ -140,18 +120,20 @@ Linux (tested on Ubuntu 16.04) | ``password=MyPassword`` | ``host=MyIP`` | ``port=3306`` + - Replace your database specific credentials with those listed above. #. Once the all of the installation and configurations has been completed the following command can be run to pull the default sample dataset that comes with this project.:: $ snakemake + This pulls sample data from AWARE_ and processes it with the default rules that come with RAPIDS. .. _the-install-note: .. note:: - - Ensure that ``MY_GROUP_NAME`` is the same value for GROUP in the ``DATABASE_GROUP`` variable in the ``config.yaml`` file. + - Ensure that ``MY_GROUP_NAME`` is the same value for GROUP in the ``DATABASE_GROUP`` variable in the ``config.yaml`` file located in the root directory (rapids/config.yaml). - Ensure that your list of ``SENSORS`` in the ``config.yaml`` file correspond to the sensors used in the ``all`` rule in the ``Snakefile`` file (See :ref:`rapids-structure` for more information)