Справочник формул #

Формулы в DataSuite 2 вычисляет библиотека Math.js, дополненная строковыми и служебными функциями. Здесь описано всё, что доступно в формулах, от простой арифметики до сложных выражений.

Быстрый старт #

Пошаговые примеры подсчёта баллов по реальным опросникам приведены в руководстве по подсчёту баллов.

Формула вычисляется построчно: расчёт повторяется для каждого участника (строки данных) по его собственным значениям. Выбранные входные переменные обозначаются v1, v2, v3 и т. д.:

(v1 + v2) / 2

С агрегирующими функциями удобна запись диапазона v1:v7:

sum(v1:v7)

Для большинства задач этого достаточно. Ниже — полный справочник.

Переменные #

Входные переменные #

Переменные, выбранные на панели входных переменных, нумеруются в порядке выбора. Если выбрать, например, Возраст, Балл и Оценку, они станут v1, v2 и v3. Присвоенный номер показывает метка-ссылка рядом с именем переменной на той же панели.

Пустая ячейка — это пропуск, а не 0. Как пропуск обрабатывается в выражениях разного вида, описано в разделе Пропущенные значения.

Специальные переменные #

v и c доступны, когда у правила несколько входных переменных, а результат записывается в режиме «Заменить исходные значения». Тогда формула выполняется для каждой переменной в каждой строке: v — значение текущей ячейки, c — весь её столбец. Так одно преобразование применяется сразу ко многим переменным: например, v * 100 переводит все выбранные переменные в проценты.

Пропущенные значения #

Пустая ячейка попадает в формулу как пропуск и никогда не превращается в 0. Что будет дальше, зависит от того, где она стоит:

• Арифметика, сравнения и строковые функции — результатом для строки будет пропуск. При пустом v2 выражение (v1 + v2) / 2 даёт пустое значение, как и v1 > 3 ? 1 : 0: сравнение с пропуском не даёт ни истины, ни лжи.
• Агрегирующие функции по диапазону или столбцу — пустое значение не учитывается. mean(v1:v7) с одним пустым пунктом даёт среднее остальных шести, sum(c1) складывает непустые ячейки столбца, а count(v1:v7) считает пункты с ответом. Если пусты все значения, получается пропуск (count в этом случае даёт 0). Необязательный последний аргумент задаёт минимальное число заполненных значений: mean(v1:v7, 5) даёт пропуск, если ответов меньше пяти. (Исключение — quantileSeq: у этой функции второй аргумент задаёт вероятность.)
• == — пропуск не равен ничему, поэтому v1 == 0 на пустой ячейке даёт false. Проверяйте пропуск функциями из таблицы ниже или сравнением с null: v1 == null.

Чтобы обработать пропуск отдельно или подставить вместо него значение, используйте эти функции:

Суммарные баллы и пропущенные пункты: sum(v1:v9) не учитывает пустой пункт, так что респондент, не ответивший на один вопрос, получает сумму остальных восьми, то есть заниженный итог, а не пропуск. Если сумма нужна только при ответах на все пункты, задайте минимум: sum(v1:v9, 9). Другой путь — пересчитать сумму пропорционально: возьмите среднее по пунктам с ответом и умножьте его на число пунктов шкалы. Формула mean(v1:v9, 7) * 9 даёт пропуск, если ответов меньше семи, а иначе — сумму, которую при таком среднем дала бы полностью заполненная шкала.

Значения и синтаксис #

Числа #

Числа записываются как есть: 42, 3.14, -7. Поддерживается экспоненциальная запись: 1.5e3 (= 1500).

Строки #

Строки заключаются в двойные кавычки: "привет". Оператор + соединяет строки: "ID_" + v1.

Логические значения #

true и false возвращают сравнения и логические операторы, на них же опираются условные выражения.

Массивы #

Массив записывается в квадратных скобках:

[1, 2, 3]
[v1, v2, v3]
["низкий", "средний", "высокий"]

Массивы нужны потому, что некоторые функции работают именно с ними. Например, min и max принимают как отдельные аргументы, так и массив:

min(v1, v2, v3)
min([v1, v2, v3])

Обе записи дают одинаковый результат.

Диапазон v1:v7 автоматически раскрывается в массив: запись sum(v1:v7) превращается в sum([v1, v2, v3, v4, v5, v6, v7]).

Индексирование #

К отдельному элементу массива обращаются по индексу в квадратных скобках. Индексы начинаются с 1, а не с 0, как в большинстве языков программирования:

c1[1]       // первое значение столбца 1
c1[i]       // значение столбца 1 в текущей строке

Операторы #

Арифметические #

Оператор + соединяет и строки: "ID_" + v1 даёт "ID_42".

Операторы сравнения #

Результат сравнения — true или false. Сравнивать можно и числа, и строки.

Логические операторы #

Условный оператор (тернарный) #

condition ? valueIfTrue : valueIfFalse

Например, так метка назначается в зависимости от балла:

v1 >= 70 ? "зачёт" : "незачёт"

Для нескольких условий операторы вкладываются друг в друга:

v1 >= 90 ? "A" : (v1 >= 70 ? "B" : "C")

Математические функции #

Ниже перечислены самые употребительные встроенные функции Math.js. Полный список приведён в документации Math.js.

Основные #

Агрегирующие #

Эти функции принимают несколько значений или массив (например, диапазон v1:v7). При расчёте по диапазону или столбцу пустые ячейки пропускаются, а необязательный последний аргумент задаёт минимальное число заполненных значений (см. Пропущенные значения):

Тригонометрические #

sin(x), cos(x), tan(x), asin(x), acos(x), atan(x) — все в радианах.

Дополнительные агрегирующие функции #

Строковые функции #

Строковые функции работают с текстом. Большинство из них принимает строку первым аргументом.

Многие из них допускают и точечную запись, то есть вызов функции как метода значения. Обе формы равнозначны:

contains(v1, "тест")    // обычная запись
v1.contains("тест")     // точечная запись — тот же результат

Выбирайте ту, что удобнее. Точечная запись особенно удобна для цепочек вызовов: v1.trim().toLowerCase().

Регистр #

Проверка и поиск #

Извлечение #

Изменение #

Разбивка и объединение #

Сопоставление с шаблоном #

Форматирование #

format(template, arg0, arg1, ...)

Подставляет на место {0}, {1} и т. д. соответствующие аргументы, не более пяти (от {0} до {4}):

format("Испытуемый {0}, группа {1}", v1, v2)

Функции для работы с датами #

Даты в DataSuite 2 хранятся как текст в формате ISO 8601 (YYYY-MM-DD, например "2024-01-15"). Функции ниже разбирают такие строки и вычисляют разности с учётом календаря. Некорректная дата даёт NaN, а любая арифметика с NaN снова даёт NaN, поэтому ошибочная строка будет видна в результатах, а не исказит расчёт незаметно.

Допустимые значения unit для dateDiff и dateAdd:

• "day" — точное целое число дней.
• "week" — для dateDiff ровно days / 7, для dateAdd сдвиг на n × 7 дней.
• "month" — для dateDiff число полных календарных месяцев плюс остаток в долях текущего месяца с учётом его фактической длины (28, 29, 30 или 31 день). В dateAdd число n округляется до целых месяцев, а если в итоговом месяце нет такого числа, берётся его последний день (Jan 31 + 1 month → Feb 28/29).
• "year" — для dateDiff число полных лет плюс остаток в долях года с учётом его фактической длины (365 или 366 дней). В dateAdd число n округляется до целых лет, а 29 февраля високосного года при сдвиге на невисокосный год становится 28 февраля.

Календарные месяцы вместо средней длины месяца: dateDiff(d1, d2, "month") не делит на среднюю длину месяца (например, 30.4375 дня). Функция считает полные календарные месяцы, а оставшиеся дни берёт как долю того месяца, на который они приходятся, поэтому между одними и теми же числами разных месяцев или лет всегда получается целое число: dateDiff("2024-01-15", "2025-01-15", "year") равно ровно 1.0. По той же логике 29 февраля в невисокосном году приравнивается к 28 февраля.

Примеры:

dateDiff("2024-01-15", "2024-02-15", "month")    // 1.0 — ровно один календарный месяц
dateDiff("2024-01-15", "2024-03-01", "month")    // ~1.517 — 1 месяц и 15 дней 29-дневного февраля
dateDiff("2020-02-29", "2021-02-28", "year")     // 1.0 — 29 февраля приравнивается к 28 февраля
dateDiff("2024-01-15", today(), "day")           // дней с включения в исследование по сегодня

dateAdd("2024-01-15", 60, "month")               // "2029-01-15" — граница наблюдения через 5 лет
dateAdd("2024-01-31", 1, "month")                // "2024-02-29" — ограничено концом месяца
dateAdd("2024-03-01", -30, "day")                // "2024-01-31" — отрицательное n вычитает

Практический пример: время до события для анализа выживаемости #

В данных для анализа выживаемости обычно есть дата включения и дата события, пустая у цензурированных участников (тех, кто всё ещё под наблюдением). Три правила преобразования превращают их в столбцы, которые нужны модулю анализа времени до события:

cutoff = isBlank(event_date) ? today() : event_date
follow_up = dateDiff(consent_date, cutoff, "month")
event_occurred = isNotBlank(event_date)

Первое правило берёт дату события, если она есть, а иначе считает, что участник наблюдается по сегодняшний день. Второе вычисляет срок наблюдения в месяцах от включения до этой даты. Третье создаёт бинарный индикатор события: в модуле анализа значения false и true автоматически получают роли «Цензурировано» и «Событие».

Чтобы считать в днях или годах, замените третий аргумент: dateDiff(consent_date, cutoff, "day") или ... "year". Если в данных есть отдельная дата последнего контакта для участников, живых к концу наблюдения, подставьте её вместо today():

cutoff = isBlank(event_date) ? last_contact_date : event_date

Если наблюдение в исследовании ограничено фиксированным административным сроком (например, пятью годами после включения), вычислите дату его окончания с помощью dateAdd:

admin_cutoff = dateAdd(consent_date, 60, "month")
cutoff = isBlank(event_date) ? admin_cutoff : event_date

Многопеременные формулы #

Запись @Name = expression создаёт в одном правиле несколько выходных переменных:

@Total = v1 + v2 + v3
@Average = @Total / 3
@Centered = @Total - (mean(c1) + mean(c2) + mean(c3))

Объявление @Name создаёт новую переменную или перезаписывает существующую с тем же именем. В следующих объявлениях можно ссылаться на предыдущие через префикс @. Панель параметров вывода для многопеременных формул отключена: выходные переменные в них заданы явно.

Массив столбца есть у каждой входной переменной (mean(c1) — среднее первого пункта), а у объявленной переменной его нет. Поэтому центрируйте итог относительно суммы средних по пунктам, как в примере выше, а не относительно mean(c1 + c2 + c3): при поэлементном сложении столбцов первая же пустая ячейка в любом из них даёт ошибку.

Промежуточные переменные #

Формула может занимать несколько строк. Разбейте сложный расчёт на понятные шаги с помощью присваиваний:

total = v1 + v2 + v3
total / 3

Результатом становится последняя строка, и именно она записывается в данные. Предыдущие строки задают промежуточные переменные для следующих выражений. Это то же самое, что (v1 + v2 + v3) / 3, но сложную формулу так легче читать.

Примечание: промежуточные присваивания (через =) — это не то же самое, что многопеременные формулы (через @Name =). Промежуточные переменные существуют только внутри формулы и в набор данных не сохраняются.

Редактор формул #

Возможности редактора формул:

• Подсветка синтаксиса — числа, строки, операторы и вызовы функций выделены цветом
• Подсветка парных скобок — когда курсор стоит рядом со скобкой, подсвечивается её пара
• Автодополнение — после двух введённых символов появляется список подсказок с переменными, функциями и константами. Чтобы открыть список вручную, нажмите Ctrl+Space. Рядом со ссылкой на переменную в списке показано её имя (например, v1 Age)
• Проверка ошибок — синтаксическая ошибка подчёркивается прямо при вводе, а её описание выводится на полях редактора
• Поиск — Ctrl+F ищет текст, Ctrl+H открывает поиск с заменой

Советы #

• Пустая ячейка — не 0. Арифметика с пропуском даёт пропуск, а агрегирующие функции его не учитывают (см. Пропущенные значения). Заполнить пропуск можно так: coalesce(v1, 0).
• v1 и c1 — v1 даёт одно значение (текущей строки), а c1 — весь столбец в виде массива. Для расчётов по столбцу нужен c1: v1 - mean(c1) центрирует значения относительно среднего по столбцу.
• Ошибка в формуле даёт пропуск в этой строке, остальные данные она не затрагивает. Неожиданные пустые значения ищите в предпросмотре данных.
• Соединение строк выполняется оператором +: v1 + " " + v2 соединяет два текстовых значения через пробел.
• Скобки задают порядок вычислений как обычно: (v1 + v2) * v3.
• Константы pi, e, Infinity и NaN доступны в формулах.
• Комментарий начинается с #: v1 + v2 # total score. Всё, что стоит после # до конца строки, игнорируется.