Automatic grouping

You can add a grouping variable, e.g. for multiple meal types, to compute between group differences of means. Cross-over, randomized or mixed designs (some patients cross-over) are supported.

You must explicitlty state the grouping variable for each single file as shown below. Without names, it is possible to vectorize, e.g. read_any_breathtest(c(file1, file2)), but the ‘c()’ operator used on vectors disambiguates the names by appending numbers.

files1 = c(
  group_a = btcore_file("IrisCSV.TXT"), # Use only single file with grouping
  group_a = btcore_file("Standard.TXT"),
  group_b = btcore_file("350_20043_0_GER.txt")
 )

# Alternative syntax using magrittr operator
suppressPackageStartupMessages(library(dplyr))
read_any_breathtest(files1) %>% 
  cleanup_data() %>% 
  null_fit() %>% 
  plot()

Simulated data

Function simulate_breathtest_data() generates sample data you can use to test different algorithms. Curves with outliers can be generated by setting student_t_df to values from 2 (very strong outliers) to 10 (almost gaussian).

set.seed(212)
data = list(meal_a = simulate_breathtest_data(n_records = 3, noise = 2,
                          student_t_df = 3, missing = 0.3), 
            meal_b = simulate_breathtest_data(n_records = 4))
data %>% 
  cleanup_data() %>% 
  nlme_fit() %>% 
  plot()

Example of a cross-over design with missing data, outliers and missing record in the red curve.

data$meal_a$record

  patient_id  m       k beta t50_maes_ghoos
1     rec_01 38 0.01310 2.41            106
2     rec_02 47 0.00918 1.69            119
3     rec_03 16 0.01039 2.25            128

Built-in data sets

Three data sets are included in R format and can be loaded as shown below. All data were provided by the University Hospital of Zürich; details are given in the documentation.

data("usz_13c")
cat("usz_13c has data from", length(unique(usz_13c$patient_id)), "patients with" , 
    length(unique(usz_13c$group)), "different meals")

usz_13c has data from 163 patients with 4 different meals

• breathtestcore::usz_13c A large data set used to establish reference ranges for healthy volunteers and patients
• breathtestcore::usz_13c_a Exotic data, a challenge for fitting algorthms
• breathtestcore::usz_13c_d Has gastric emptying half time from MRI as attribute, and can used to compare recorded data with gold standards; see the example in the documentation.

How to use the Excel data formats

• Use function read_breathtest_excel(); this is the only way to select a worksheet different other than first in the workbook by passing parameter sheet. All other methods only read the first worksheet.
• Use function read_any_breathtest(). This always reads the first worksheet, but you can combine results from several files, even when they have different formats

(bt = read_breathtest_excel(btcore_file("ExcelSamples.xlsx"), "2col"))

[[1]]
# A tibble: 22 × 2
  minute   pdr
   <dbl> <dbl>
1   0.42 0.547
2  11.9  1.64 
3  23.4  3.89 
4  34.9  6.13 
# ℹ 18 more rows

(cbt = cleanup_data(bt))

# A tibble: 22 × 4
  patient_id group minute   pdr
  <chr>      <chr>  <dbl> <dbl>
1 pat_a      A       0.42 0.547
2 pat_a      A      11.9  1.64 
3 pat_a      A      23.4  3.89 
4 pat_a      A      34.9  6.13 
# ℹ 18 more rows

cbt %>% nls_fit() %>% plot()

(bt = read_breathtest_excel(btcore_file("ExcelSamples.xlsx"), "3col"))

[[1]]
# A tibble: 43 × 3
  patient_id minute   pdr
  <chr>       <dbl> <dbl>
1 7951500      0.42 0.547
2 7951500     11.9  1.64 
3 7951500     23.4  3.89 
4 7951500     34.9  6.13 
# ℹ 39 more rows

(cbt = cleanup_data(bt))

# A tibble: 43 × 4
  patient_id group minute   pdr
  <chr>      <chr>  <dbl> <dbl>
1 7951500    A       0.42 0.547
2 7951500    A      11.9  1.64 
3 7951500    A      23.4  3.89 
4 7951500    A      34.9  6.13 
# ℹ 39 more rows

bt = read_breathtest_excel(btcore_file("ExcelSamples.xlsx"), "4col_2group") %>% 
  cleanup_data()
kable(sample_frac(bt, 0.08) %>% arrange(patient_id, group), caption = "A sample from a four-column format. See worksheet 4col_2group.")

bt %>% nlme_fit() %>% plot()

IRIS-Wagner composite data

The first lines of IrisMulti.TXT

"Testergebnis"
"Nummer","22"
"Datum","12.06.2009"
"Testart"
"Name","Magenentleerung fest"
"Abkürzung","GE FEST"
"Substrat","Natriumoktanoat"

Use read_iris() or read_any_breathtest() :

read_iris(btcore_file("IrisMulti.TXT")) %>% 
  cleanup_data() %>% 
  null_fit() %>% 
  plot()

IRIS/Wagner composite file. These data cannot be fitted successfully with the single-curve fit method, therefore only data are shown.

IRIS/Wagner CSV format

Files in this format start like this (lines shortened …)

"Name","Vorname","Test","Identifikation","Testzeit[min]",...
"Einstein","Albert","GE FEST","330240","0","0","-26.32","4.501891E-02", ...
"Einstein","Albert","GE FEST","330240","10","2.02","-24.3","5.617962E-02","2.391013",..
"Einstein","Albert","GE 

Use read_iris_csv() or read_any_breathtest() :

read_iris_csv(btcore_file("Standard.TXT")) %>% 
  cleanup_data() %>% 
  nls_fit() %>% 
  plot()

IRIS/Wagner CSV file

BreathID composite format

Files in this format start like this

Test and Patient parameters                 

                    
Date           -    12/11/12                    
End time       -    08:54                   
Start time     -    12:49                   
Patient # - 0       
Patient ID   - Franz                    

Use read_breathid() or read_any_breathtest():

read_breathid(btcore_file("350_20043_0_GER.txt")) %>% 
  cleanup_data() %>% 
  nls_fit() %>% 
  plot()

BreathID composite file

BreathID XML format

The more recent XML format from BreathID can contain data from multiple record and starts like this:

<Tests Device="1402">
  <Test Number="2">
    <ID>TEST123</ID>
    <DOB>N/A</DOB>
    <StartTime>19Jul2017 11:56</StartTime>
    <EndTime>19Jul2017 12:12</EndTime>
    <LastResultCode>0</LastResultCode>
    <StoppedByUser>true</StoppedByUser>
  </Test>
  <Test Number="3">
    <ID>45689</ID>
    <StartTime>19Jul2017 12:22</StartTime>
    <EndTime>19Jul2017 12:29</EndTime>
    <LastResultCode>0</LastResultCode>

Use read_breathid_xml() or read_any_breathtest():

read_breathid_xml(btcore_file("NewBreathID_multiple.xml")) %>% 
  cleanup_data() %>% 
  nls_fit() %>% 
  plot()

BreathID XML format

Grouping is most useful in a cross-over design to force within-subject comparisons by functions coef_by_group() and coef_diff_by_group(); in the above case, the default grouping above might not be what you required. Replace the group parameter manually to remove the groups, but do not delete the column with group = NULL, because the fitting functions requires a dummy group name.

# Could also use read_any_breathtest()
read_breathid_xml(btcore_file("NewBreathID_multiple.xml")) %>% 
  cleanup_data() %>% 
  mutate(
    group = "New"
  ) %>% 
  nls_fit() %>% 
  plot()

BreathID XML format with manual grouping.