You will need Python 3.4+ and
pip installed in order to use Cortex.
- You may need root permissions, using
- Alternatively, to install locally, use
pipis not recognized as a command, use
python3 -m pip.
If you meet the prerequisites, install Cortex:
If you do not have your environment variables set up (see Advanced section below), you will need to perform the initial server credentials configuraton below:
cortex.run, you must provide a specific ID or a
list of IDs (only
Participant IDs are supported). Then, you specify the behavioral features to generate and extract. Once Cortex finishes running, you will be provided a
dict where each key is the behavioral feature name, and the value is a dataframe. You can use this dataframe to save your output to a CSV file, for example, or continue data processing and visualization.
For example, running the
survey feature (which is not a behavioral feature, but rather a convenience around raw survey data) yields the following CSV output:
You can then load this CSV file into Microsoft Excel (or Apple Numbers on macOS). Additionally, you can add Categories to group the data by ID, survey, and the specific time that the survey was taken.
It's easy to get started with more advanced analysis on data collected from mindLAMP. In this example, we'll walk through using Cortex with Luminol, an anomaly detection library, and Altair, an interactive visualization library, to tag and visualize survey scores for a particular patient.
This sample code is not intended to be used in clinical practice. All data and visualizations provided here are examples only and not linked to actual patients in any way, shape, or form. Tap here to directly view the Jupyter Notebook for this example.
cortex.run(...) with your Participant ID of interest. Then, we'll need to rearrange the resultant data frame by setting the index to the
timestamp and adding an
anomaly column for later.
In addition to the survey
score column, we also have a
category column that's derived from custom survey grouping. The Cortex feature
survey_scores automatically scores each question for you, whether it's a Likert scale, list of options, True/False, and so on. Then, it groups together questions from a single survey, such as "Weekly Survey" by predefined categories, like "Mood" and "Anxiety" to better understand symptom domains.
Now, we feed the Luminol detector our
score column. It then processes the data and returns anomalous time windows tagged with an anomaly score. We'll tag the actual survey scores in our DataFrame that lie within these windows with their respective anomaly score. We need to iterate over each category and tag anomalies within the category independent of survey scores from other categories.
We'll use the Altair interactive plotting library to break question categories out into their own sub-charts. We'll also bring extra attention to anomalous survey score data points by increasing their size and changing their color.
server_address is set correctly. If using the default server, it will be
api.lamp.digital. Keep your
access_key (sometimes an email address) and
secret_key (sometimes a password) private and do not share them with others. While you are able to set these parameters as arguments to the
cortex executable, it is preferred to set them as session-wide environment variables. You can also run the script from the command line:
Or another example using the CLI arguments instead of environment variables (and outputting to a file):