Package: carwatch
carwatch-pythonGet the Android app on the Play Store:CARWatch is an open-source framework to supportobjectiveandlow-costassessment of cortisol samples in real-world, unsupervised environments. It is especially suitable forcortisol awakening response (CAR)research, but not limited to this application.It consists of anAndroid applicationthat schedules sampling times and tracks
them by scanning a barcode on the respective sampling tube as well as a Python package that provides tools toconfigure studiesandprepare the study materialsand toprocess the log datarecorded by the app.FeaturesIn order to use CARWatch, you need to prepare the study materials and configure the app. The whole workflow is
illustrated in the following figure:All these features are provided bycarwatchwhich offers a user-friendly command-line interface (CLI)
for the following tasks:Setting up a CAR study.This includes:Customizing study properties to your needsSetting up your desired sampling scheduleGenerating a QR-Code for theCARWatch appto automatically set up
the study in the appCreating printable labels with barcodes for objective sampling time assessment.This includes:Customizing the numer of saliva samples per day, the number of days, and the number of study participantsAdding an optional evening saliva sampleCustomize barcodes to fit your printable label templatesAnalyzing the CARWatch log data.This includes:Extracting the sampling timestamps from the log dataExtracting the self-reported awakening times (if available)Merging the time information with the cortisol measuresInstallationcarwatchrequires Python >=3.8. First, install a compatible version of Python
(e.g. usingminiconda). Then, open a terminal (or Anaconda prompt)
and install thecarwatchpackage via pip:pipinstallcarwatchAlternatively, you can download the package directly from the source repository on GitHub:gitclonehttps://github.com/mad-lab-fau/carwatch-python.gitcdcarwatch-python
pipinstall.For DeveloperIf you are a developer and want to contribute tocarwatchyou can install an editable version of the package from
a local copy of the repository.carwatchusespoetryto manage dependencies and packaging. Once you installed poetry,
run the following commands to clone the repository, initialize a virtual environment and install all development
dependencies:gitclonehttps://github.com/mad-lab-fau/carwatch-python.gitcdcarwatch-python
poetryinstallUsagecarwatchcan be used bothprogrammaticallyand with the providedcommand line interface (CLI).The core functionalities of thecarwatchpackage arecreating a QR-Code for configuring theCARWatch App(Preparation),creating a PDF with printable barcode labels for the saliva sampling tubes (Preparation),and extracting the sampling times for the CARWatch app log recordings (Postprocessing).Programmatic UsageFor the preparation steps, the study details can be specified using theStudyclass. Participant IDs can also be
parsed from a *.csv file, when the path to it is specified assubject_path, and the corresponding column assubject_column.Some basic examples are given below. For more information about the available parameters, please refer to the
documentation of the mentioned classes.Study Setup Examplefromcarwatch.utilsimportStudystudy=Study(study_name="ExampleStudy",num_days=3,num_subjects=15,num_samples=5,subject_prefix="VP_",has_evening_sample=True,start_sample_from_zero=True,)Barcode Generation ExampleFor generating barcodes, theLabelGeneratorclass can be used, receiving aStudyinstance as a parameter. Your
custom printing label layout can be specified using theCustomLayoutclass. By default, theAveryZweckform J4791layout is used.To start the PDF generation, call thegeneratemethod of theLabelGeneratorclass. The output PDF will be exported
to the directory specified byoutput_dir(per default: the current working directory).fromcarwatch.utilsimportStudyfromcarwatch.labels.print_layoutimportCustomLayoutfromcarwatch.labels.label_generatorimportLabelGeneratorstudy=Study(study_name="ExampleStudy",num_days=3,num_subjects=15,num_samples=5,subject_prefix="VP_",has_evening_sample=True,start_sample_from_zero=True,)generator=LabelGenerator(study=study,add_name=True,has_barcode=True)layout=CustomLayout(num_cols=3,num_rows=4,left_margin=3,right_margin=3,top_margin=2,bottom_margin=2,inter_col=0.2,inter_row=0.5,)generator.generate(output_dir=".",debug=True,layout=layout)QR-Code Generation ExampleFor generating the QR-Code, theQrCodeGeneratorclass can be used, again receiving aStudyinstance as a parameter.
Thesaliva_distancesparameter specifies the desired distances between saliva samples in minutes. The resulting
QR-Code for setting up the CARWatch App will be exported to the directory specified byoutput_dirdirectory
(per default: the current working directory).fromcarwatch.qr_codesimportQrCodeGeneratorfromcarwatch.utilsimportStudyif__name__=="__main__":study=Study(study_name="ExampleStudy",num_days=3,num_subjects=15,num_samples=5,subject_prefix="VP_",has_evening_sample=True,start_sample_from_zero=True,)generator=QrCodeGenerator(study=study,saliva_distances=[10,10,10],contact_email="dum@my.com")generator.generate(output_dir=".")Postprocessing ExampleTo be addedCommand Line InterfaceFor the preparation steps,carwatchalso provides a CLI for more convenient usage.
Make sure you installed thecarwatchpackage withpip install carwatch.After that, you can simply run the TUI (terminal user interface) by runningprepare_study tuiin a terminal session.This will implicitly run thescripts/prepare_study.pyscript, which will guide you through the preparation steps.
You will then be prompted to enter all the required information step-by-step. The desired output files will
be automatically generated for you.The regular command line interface (CLI) can be used by runningprepare_study runFor more information about the prompted commands please run:prepare_study run --helpLicenseThis project is licensed under the MIT License. See the LICENSE file for details.ContributingWe welcome contributions tocarwatch! For more information, have a look at theContributing Guidelines.Citing carwatchIf you usecarwatchin your work, please report the version you used in the text. Additionally, please also citeour paperpublished in
Psychoneuroendocrinology:Richer, R., Abel, L., Küderle, A., Eskofier, B. M., & Rohleder, N. (2023). CARWatch – A smartphone application for 
improving the accuracy of cortisol awakening response sampling. Psychoneuroendocrinology, 151, 106073. 
https://doi.org/10.1016/j.psyneuen.2023.106073ContactIf you have any questions or feedback about CARWatch, please contactRobert Richer.