Running CompTIES

You can run the CompTIES code using the compTIES web interface. You can upload your data to our web server, run the application from a browser, and view or download the results. This page describes how to do so.

The CompTIES app trains and tests the full TIES coupled-oscillator model of emotional interaction. Using cross-validation, this learns shared parameters for the oscillator and tests those models.

Quick Start

In a nutshell, you will submit compTIES job like so:

• Format your data as a CSV file.
• Navigate to Job Submission page.
• Upload your input CSV file or select uploaded CSV file from the web server.
• Choose an "observable" category name, a "distinguisher" category name, and optional "moderator" and "categorical moderator" names.
• Select "options" and submit the job!

Input Data

The input data file contains measurements and other information about participants, who are paired into dyads (i.e., two individual participants). The file contains both time-varying and time-invariant data.

The input data file is organized as a table of numbers, stored in comma-separated-variable (CSV) format. (Spreadsheets such as Excel and OpenOffice can export data in this form.) The first row stores text labels, and rows 2 and below hold numeric data for the participants. Each row stores information about one participant at one moment in time. Each column stores one category of data.

The text labels in the first row describe the data categories. Two column labels are mandatory: Dyad, and time.

Required column labels (and meanings)

Two of the columns must have the exact labels below. The labels are case-sensitive!

• Dyad — a unique dyad number, e.g., 1, 2, 3, which is an identifier shared by exactly two participants. This number is used extensively in the output.

• time — an index of the time measurement, e.g., 1, 2, 3, . . . .

Other required columns

At least two more columns are required, but the labels are up to you:

• A distinguisher category — one column must contain just 0 or 1 and differentiate between the two members of the dyad. For example, in a mother-daughter study this column might have row-1 label "is_mother" and rows 2 and below could store 1 for the mother, and 0 for the daughter. You must specify this label name when you run the app.

• (an observable category) — at least one column contains time-varying data for the participant. For example, this might be respiration rate. It could have row-1 label "resp_rate" and rows 2 and below would store numeric measurements, probably changing on each row.

  The goal of the CompTIES code is to try to infer an oscillator model that "explains" these data, i.e., a model whose oscillations tend to fit the observations with low root-mean-square (RMS) error.

• (optional: a moderator category) — if you wish to investigate the explanatory power of a time-invariant factor, then your file should include one or more columns of such data. When they are continuously-varying numerical values, we call them "moderators". For example, this might be age. It could have row-1 label "age_years" and constant value (perhaps rounded) per participant. The hypothesis is that the oscillator parameters are a linear function of the moderator (or, that they tend to be, if the parameters are stochastic).

  Moderators can describe individuals, or entire dyads.

• (optional: a Categorical Moderator) — This is similar to a moderator, but for discrete, categorical values. If the hypothesized explanatory factor takes the form of discrete categories that describe dyads, then the category label is a "categorical moderator." In other words, the dyads can be partitioned into disjoint groups, and you hypothesize that the oscillator parameters can be predicted by group identity. For example, the categorical moderator might be the dyad's preferred language of interaction, possibly encoded using numeric labels (e.g., 0=English, 1=French, 2=Kannada, etc.), and recorded in one column. For each group identity, independent sets of oscillator parameters will be inferred, one set per group.

  Like a moderator, the values of a categorical moderator must be time-invariant. Note that group identity applies to dyads, not individuals. Thus both individuals in a dyad must have the same group-identity label in the grouping-variable column.

For more discussion about the differences between moderator and grouping-variable factors, please see below, Moderator or Grouping Variable?

Technical considerations

Extra columns are ignored, and thus you may store all your measurements in one file. Unreferenced columns have no effect on the model.

Every column in the file must have a row-1 label composed of solely of letters, numbers, and underscore characters. Do not use spaces, punctuation, or other characters. Each label must be unique. Labels are case-sensitive: you must match upper case and lower case exactly whenever you refer to one.

If necessary, you can use the special string "NA" in place of a number to indicate missing observable data. However, if "NA" is present in the Dyad, time, or distinguisher column of any row, that entire row is unusable and is disregarded.

Input File Example

The fictional example below shows the format. Here's how it would look in LibreOffice Calc or Excel:

Dyad	is_mother	age_years	conflict	resp_rate	dial	time	language
2	0	17.3	4.2	0.84	0	1	1
2	0	17.3	4.2	0.72	0.2	2	1
2	0	17.3	4.2	0.70	-0.4	3	1
2	0	17.3	4.2	0.83	-0.1	4	1
2	0	17.3	4.2	0.87	0.3	5	1
3	0	19.4	1.1	0.50	0.3	1	0
3	0	19.4	1.1	0.55	0.3	2	0
3	0	19.4	1.1	0.57	0.4	3	0
3	0	19.4	1.1	0.55	0.2	4	0
3	0	19.4	1.1	0.56	-0.1	5	0
3	0	19.4	1.1	0.55	-0.1	6	0
7	0	16.7	2.3	0.70	-0.3	1	0
7	0	16.7	2.3	0.77	-0.2	2	0
7	0	16.7	2.3	0.80	-0.1	3	0
7	0	16.7	2.3	0.78	0.2	4	0
2	1	39.2	4.2	0.73	0.1	1	1
2	1	39.2	4.2	0.74	0.2	2	1
2	1	39.2	4.2	0.73	0.2	3	1
2	1	39.2	4.2	0.72	0.1	4	1
2	1	39.2	4.2	0.73	0.0	5	1
3	1	44.6	1.1	0.68	-0.4	1	0
3	1	44.6	1.1	0.69	-0.5	2	0
3	1	44.6	1.1	NA	-0.4	3	0
3	1	44.6	1.1	0.60	0.2	4	0
3	1	44.6	1.1	0.58	0.3	5	0
3	1	44.6	1.1	0.62	0.1	6	0
7	1	41.1	2.3	0.77	-0.2	1	0
7	1	41.1	2.3	0.80	-0.1	2	0
7	1	41.1	2.3	0.78	0.2	3	0
7	1	41.1	2.3	0.75	0.1	4	0

If you open the CSV file in a text editor, the first few lines of the above example would look something like this:

Parameters

The "Parameters" section of the interface asks for several category names and modeling decisions.

• Observable(s) — You should enter the exact name(s) of the column label(s) for the observable data column(s) (i.e., the labels are case sensitive). You may use more than one observable, with names separated by commas (e.g., blood_pressure, heart_rate). Whitespace between observable category names has no effect.

• Moderator(s) — this is an optional category name, or list of names, for moderator data, which does not change with time. If you use this field, you must enter the exact name of the column label for the moderator column, including lower-case or capital letters. You may use more than one moderator, with the names separated by commas (e.g., health, wealth). Whitespace between moderator category names has no effect.

• Categorical Moderator — this is an optional category name used to partition the dyads into two or more groups. If you use this field, you must enter the exact name of the column label. Only one categorical moderator name is accepted, but the values in this category can partition the dyads into as many sub-groups as desired.

• Distinguisher category name — this is a category name for data that corresponds to an individual participant, does not change with time, and is 0 or 1 to differentiate between two members of the dyad.

• Exclude Percentage — Percentage of marginal input values to be excluded from analysis. Example, 10 excludes last 10% of the data.

Options

• Infer baseline models? — This checkbox determines which models the CompTIES app will infer. The app will always infer the full-power TIES model (a shared-parameter coupled oscillator, using all moderators and any categorical moderators). If this checkbox is checked, the app will also infer four simpler models, called baseline models, for the sake of comparison. The baseline models, in order of increasing complexity, are as follows:

  • Average model — explains the observable data using a constant value (equal to the average value of the observable over time).
  • Line model — explains the data by fitting a line through the observables.
  • Individual coupled oscillator model — explains the data by learning a shared error variance, then choosing the best-fitting oscillator to the observable data used for training. This model tends to overfit.
  • Shared-parameter coupled oscillator without moderator — This model disregards any moderator or grouping-variable factors. In all other respects is the same as the full-power TIES model.

Moderator or Categorical Moderator?

If you are testing the hypothesis that some known per-dyad or per-individual time-invariant factor can help explain the observed oscillations in your data, then you should use either a moderator or a categorical moderator. But which one?

Categorical Moderator

A categorical moderator is intended for discrete values that describe categories lacking a natural sequential order. Each dyad must belong to exactly one such category. For example, if you hypothesize that the first language of the dyad members helps explain your data, you might record categorical values for each dyad indicating 1=Catalan, 2=Korean, 3=Urdu, etc. The order of these numbers is meaningless: Catalan is neither greater than nor less than Korean, just a different category. But, this fact is not obvious to the TIES modeler. By indicating that this category is a categorical moderator, you tell the TIES modeler to ignore the order properties of the category values.

The TIES modeler uses categorical moderator to segregate the data, and then it infers separate shared-parameter coupled oscillator models for each group, where the shared parameters are learned only from dyads in the same group. All else being equal, data with fewer groups or more dyads per group will yield results with better significance. Of course a categorical moderator must define at least two groups to have any explanatory power.

Categorical moderators describe dyads, not individuals. Both individuals of a dyad must share the same category. This is not a limitation, since discrete individual differences can be combined to form dyad-level categories. For example, deaf identity of a mother-daughter dyad could be encoded as 0=(mother deaf and daughter deaf), 1=(only mother deaf), 2=(only daughter deaf), 3=(neither is deaf).

Moderators

A moderator is intended for numerical values that have a meaningful natural order. Examples include age, body-mass index, number of siblings. A moderator category might assume discrete values, but the order of the values naturally has meaning. For example, if body-mass index truly helps predict good oscillator parameters, then two individuals with BMIs of 30 and 31 (all else being equal) will have oscillator parameters more similar to each other than to those of an individual with BMI of 20.

The TIES modeler uses moderators in a linear regression model, either to determine oscillator parameters, or (if the parameters are stochastic) to determine the distributions of the oscillator parameters.

You can choose to make moderators either characterize the individuals in your study, or to characterize entire dyads. That choice affects the complexity of the regression used to set the oscillator parameters. Currently the CompTIES app requires you to choose this property once for all moderators: the app does not presently support mixtures of both dyad-level and individual-level moderators. This is not a serious limitation because individual-level moderators can be reformulated as dyad-level moderators. For example, the individual-level moderator "age_years" for a mother-daughter dataset could be reformulated into two dyad-level moderators "mother_age_years" and "daughter_age_years."