English
РусскийНа этой странице
- Быстрый старт
- Переменные
- Входные переменные
- Специальные переменные
- Значения и синтаксис
- Числа
- Строки
- Логические значения
- Массивы
- Индексирование
- Операторы
- Арифметические
- Операторы сравнения
- Логические операторы
- Условный оператор (тернарный)
- Математические функции
- Основные
- Агрегирующие
- Тригонометрические
- Дополнительные агрегирующие функции
- Строковые функции
- Регистр
- Анализ
- Извлечение
- Изменение
- Разбивка и объединение
- Сопоставление с шаблоном
- Форматирование
- Функции для работы с датами
- Практический пример: время до события для анализа выживаемости
- Многопеременные формулы
- Промежуточные переменные
- Редактор формул
- Советы
Справочник формул
Формулы в DataSuite 2 основаны на Math.js с дополнительными строковыми и вспомогательными функциями. На этой странице описано всё доступное — от простой арифметики до сложных выражений.
Быстрый старт
Пошаговые примеры подсчёта баллов по реальным опросникам см. в руководстве по подсчёту баллов.
Формула вычисляется один раз для каждой строки — представьте, что вы пишете расчёт, который выполняется для каждого участника (строки) в данных, используя значения этого участника. Ссылайтесь на выбранные входные переменные как v1, v2, v3 и т. д.:
(v1 + v2) / 2
Используйте синтаксис диапазона v1:v7 совместно с агрегирующими функциями:
sum(v1:v7)
Для большинства задач этого достаточно. Полный справочник — ниже.
Переменные
Входные переменные
При выборе переменных на левой панели они нумеруются в том порядке, в котором были выбраны. Например, если выбраны Возраст, Балл и Оценка — они становятся v1, v2 и v3 соответственно. Метки рядом с каждым именем переменной на панели показывают присвоенные номера.
| Ссылка | Значение |
|---|---|
v1, v2, v3, … |
значение 1-й, 2-й, 3-й, … входной переменной в текущей строке |
c1, c2, c3, … |
полный массив значений столбца 1-й, 2-й, 3-й, … входной переменной (все строки) |
v1:v7 |
раскрывается во все переменные от v1 до v7 — используется внутри функций, например sum(v1:v7) |
Пропущенные значения обрабатываются как 0 при обращении через v1, v2 и т. д.
Специальные переменные
| Переменная | Значение |
|---|---|
i |
номер текущей строки (начиная с 1) |
v |
текущее значение обрабатываемой переменной (см. ниже) |
c |
полный массив значений столбца обрабатываемой переменной (см. ниже) |
v и c доступны, когда правило имеет несколько входных переменных, а в параметрах вывода выбрано замена исходных значений. В этом случае формула выполняется один раз для каждой переменной в каждой строке — v содержит значение текущей ячейки, c — весь столбец. Это удобно для применения одного и того же преобразования сразу ко многим переменным, например v * 100 для перевода всех выбранных переменных с дробными значениями в проценты.
Значения и синтаксис
Числа
Числа записываются как есть: 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
Операторы
Арифметические
| Оператор | Значение | Пример |
|---|---|---|
+ |
сложение (или объединение строк) | v1 + v2 |
- |
вычитание | v1 - 10 |
* |
умножение | v1 * 100 |
/ |
деление | v1 / v2 |
% |
остаток от деления | v1 % 2 |
^ |
возведение в степень | v1 ^ 2 |
Оператор + также объединяет строки: "ID_" + v1 даёт "ID_42".
Операторы сравнения
| Оператор | Значение |
|---|---|
== |
равно |
!= |
не равно |
< |
меньше |
> |
больше |
<= |
меньше или равно |
>= |
больше или равно |
Возвращают true или false. Работают как с числами, так и со строками.
Логические операторы
| Оператор | Значение | Пример |
|---|---|---|
and |
логическое И | v1 > 0 and v2 > 0 |
or |
логическое ИЛИ | v1 == 0 or v2 == 0 |
not |
логическое НЕ | not (v1 == 0) |
Условный оператор (тернарный)
условие ? значениеЕслиИстина : значениеЕслиЛожь
Пример — назначить метку на основе балла:
v1 >= 70 ? "зачёт" : "незачёт"
Для нескольких условий можно использовать вложенность:
v1 >= 90 ? "A" : (v1 >= 70 ? "B" : "C")
Математические функции
Ниже приведены наиболее часто используемые встроенные функции Math.js. Полный список см. в документации Math.js.
Основные
| Функция | Описание | Пример |
|---|---|---|
abs(x) |
абсолютное значение | abs(v1 - v2) |
round(x) |
округление до ближайшего целого | round(v1) |
round(x, n) |
округление до n знаков после запятой |
round(v1, 2) |
ceil(x) |
округление вверх | ceil(v1) |
floor(x) |
округление вниз | floor(v1) |
sign(x) |
-1, 0 или 1 | sign(v1) |
sqrt(x) |
квадратный корень | sqrt(v1) |
cbrt(x) |
кубический корень | cbrt(v1) |
pow(x, n) |
степень (то же, что x ^ n) |
pow(v1, 3) |
exp(x) |
e в степени x | exp(v1) |
log(x) |
натуральный логарифм | log(v1) |
log10(x) |
логарифм по основанию 10 | log10(v1) |
log2(x) |
логарифм по основанию 2 | log2(v1) |
Агрегирующие
Работают с несколькими значениями или массивами (например, через синтаксис диапазона v1:v7):
| Функция | Описание | Пример |
|---|---|---|
sum(...) |
сумма значений | sum(v1:v5) |
mean(...) |
среднее арифметическое | mean(v1:v5) |
median(...) |
медиана | median(v1:v5) |
min(...) |
минимальное значение | min(v1, v2, v3) |
max(...) |
максимальное значение | max(v1:v5) |
std(...) |
стандартное отклонение | std(v1:v5) |
variance(...) |
дисперсия | variance(v1:v5) |
Тригонометрические
sin(x), cos(x), tan(x), asin(x), acos(x), atan(x) — все в радианах.
Дополнительные агрегирующие функции
| Функция | Описание | Пример |
|---|---|---|
countif(массив, значение) |
количество вхождений значение в массив |
countif(c1, "да") |
sumR(массив, k) |
сумма (k - x) для каждого x в массив |
sumR([v3, v5, v8, v9, v10], 3) |
coalesce(a, b) |
возвращает a, если оно имеет значение, иначе b |
coalesce(v1, 0) |
Строковые функции
Все строковые функции работают с текстовыми значениями. Большинство принимают строку в качестве первого аргумента.
Многие строковые функции поддерживают точечный синтаксис — вызов функции как метода значения. Оба варианта равнозначны:
contains(v1, "тест") // обычный синтаксис
v1.contains("тест") // точечный синтаксис — тот же результат
Используйте тот вариант, который читается естественнее. Точечный синтаксис особенно удобен для цепочек вызовов: v1.trim().toLowerCase().
Регистр
| Функция | Описание | Пример |
|---|---|---|
toLowerCase(s) |
привести к нижнему регистру | toLowerCase(v1) |
toUpperCase(s) |
привести к верхнему регистру | toUpperCase(v1) |
capitalize(s) |
сделать первый символ заглавным | capitalize(v1) |
Анализ
| Функция | Описание | Возвращает |
|---|---|---|
length(s) |
количество символов | число |
isBlank(s) |
true, если пустая строка или только пробелы | логическое |
isNotBlank(s) |
true, если содержит непробельные символы | логическое |
isString(x) |
true, если значение является строкой | логическое |
contains(s, search) |
true, если s содержит search |
логическое |
startsWith(s, prefix) |
true, если s начинается с prefix |
логическое |
endsWith(s, suffix) |
true, если s заканчивается на suffix |
логическое |
indexOf(s, search) |
позиция первого вхождения (-1, если не найдено) | число |
lastIndexOf(s, search) |
позиция последнего вхождения (-1, если не найдено) | число |
Извлечение
| Функция | Описание | Пример |
|---|---|---|
substring(s, start) |
от start до конца |
substring(v1, 3) |
substring(s, start, end) |
от start до end (не включая) |
substring(v1, 0, 5) |
slice(s, start) |
как substring, но поддерживает отрицательные индексы |
slice(v1, -3) |
slice(s, start, end) |
извлечь фрагмент с поддержкой отрицательных индексов | slice(v1, 1, -1) |
charAt(s, index) |
символ на заданной позиции | charAt(v1, 0) |
left(s, n) |
первые n символов |
left(v1, 3) |
right(s, n) |
последние n символов |
right(v1, 4) |
Изменение
| Функция | Описание | Пример |
|---|---|---|
trim(s) |
удалить пробелы с обоих концов | trim(v1) |
trimStart(s) |
удалить ведущие пробелы | trimStart(v1) |
trimEnd(s) |
удалить завершающие пробелы | trimEnd(v1) |
replace(s, search, repl) |
заменить первое вхождение | replace(v1, "старое", "новое") |
replace(s, pattern, repl, flags) |
замена по регулярному выражению | replace(v1, "\\d+", "N", "g") |
replaceAll(s, search, repl) |
заменить все вхождения | replaceAll(v1, " ", "_") |
reverse(s) |
перевернуть строку | reverse(v1) |
repeat(s, n) |
повторить n раз |
repeat("*", v2) |
padStart(s, len, pad) |
дополнить слева | padStart(v1, 5, "0") |
padEnd(s, len, pad) |
дополнить справа | padEnd(v1, 10, ".") |
Разбивка и объединение
| Функция | Описание | Пример |
|---|---|---|
split(s, separator) |
разбить в массив | split(v1, ",") |
join(array, separator) |
объединить массив в строку | join(split(v1, ","), ";") |
Сопоставление с шаблоном
| Функция | Описание | Пример |
|---|---|---|
test(s, pattern) |
true, если регулярное выражение совпадает | test(v1, "^[A-Z]") |
test(s, pattern, flags) |
регулярное выражение с флагами | test(v1, "hello", "i") |
match(s, pattern) |
возвращает совпадение (или null) | match(v1, "\\d+") |
Форматирование
format(шаблон, арг0, арг1, ...)
Заменяет {0}, {1} и т. д. соответствующими аргументами:
format("Участник {0}, группа {1}", v1, v2)
Функции для работы с датами
В DataSuite 2 даты хранятся как текст в формате ISO 8601 (YYYY-MM-DD, например "2024-01-15"). Функции ниже разбирают эти строки и позволяют вычислять разности с учётом календаря. Некорректные строки дат превращаются в NaN, который распространяется через арифметику, чтобы плохие строки данных проявились дальше по конвейеру, а не молчаливо исказили вычисления.
| Функция | Описание | Возвращает |
|---|---|---|
today() |
сегодняшняя дата как ISO-строка | строка (например, "2026-04-24") |
dateDiff(d1, d2, unit) |
разность между двумя датами с учётом календаря | число |
dateAdd(d, n, unit) |
сместить дату на n единиц; отрицательное n вычитает |
строка (ISO-дата) или "" при некорректном вводе |
Допустимые значения unit для dateDiff и dateAdd:
"day"— точное целое число дней."week"— точноеdays / 7дляdateDiff;n × 7дней дляdateAdd."month"— дляdateDiffэто полные календарные месяцы плюс дробный остаток текущего месяца, где доля учитывает реальную длину этого месяца (28/29/30/31). ДляdateAddnокругляется до целых месяцев; день месяца ограничивается длиной целевого месяца (например,31 января + 1 месяц → 28/29 февраля)."year"— дляdateDiffэто полные годы плюс дробный остаток относительно реальной длины года (365 или 366). ДляdateAddnокругляется до целых лет; 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 вычитает
Практический пример: время до события для анализа выживаемости
Типичный набор данных по выживаемости содержит дату включения и дату события, которая может быть пустой при цензурировании (наблюдение продолжается). Три правила преобразования превращают это в столбцы, нужные модулю анализа времени до события:
окончание = isBlank(дата_события) ? today() : дата_события
наблюдение = dateDiff(дата_включения, окончание, "month")
событие_наступило = isNotBlank(дата_события)
Первое правило выбирает дату события, если она есть, иначе считает участника всё ещё под наблюдением сегодня. Второе вычисляет длительность наблюдения в месяцах от включения до этой контрольной точки. Третье формирует бинарный индикатор события — модуль анализа автоматически распознаёт false/true как цензурировано/событие.
Чтобы получить дни или годы вместо месяцев, замените третий аргумент: dateDiff(дата_включения, окончание, "day") или ... "year". Если в наборе данных есть отдельная дата последнего контакта для участников, остающихся живыми к концу наблюдения, используйте её вместо today():
окончание = isBlank(дата_события) ? дата_посл_контакта : дата_события
Для исследований с фиксированной административной отсечкой (например, окно наблюдения в 5 лет) синтезируйте контрольную точку с помощью dateAdd:
адм_окончание = dateAdd(дата_включения, 60, "month")
окончание = isBlank(дата_события) ? адм_окончание : дата_события
Многопеременные формулы
Используйте @Имя = выражение, чтобы создать несколько выходных переменных в одном правиле:
@Итог = v1 + v2 + v3
@Среднее = @Итог / 3
@ZОценка = (@Итог - mean(c1 + c2 + c3)) / std(c1 + c2 + c3)
Каждое @Имя создаёт новую переменную (или перезаписывает существующую с тем же именем). В последующих объявлениях можно ссылаться на более ранние с префиксом @. Панель параметров вывода для многопеременных формул недоступна, поскольку выходные переменные задаются явно.
Промежуточные переменные
Формулы могут занимать несколько строк. Используйте присваивания, чтобы разбить сложные вычисления на понятные шаги:
total = v1 + v2 + v3
total / 3
Результатом является последняя строка — именно она сохраняется в данные. Предыдущие строки определяют промежуточные переменные для использования в последующих выражениях. Это эквивалентно записи (v1 + v2 + v3) / 3, но удобнее для сложных формул.
Примечание: промежуточные присваивания (через
=) отличаются от многопеременных формул (через@Имя =). Промежуточные переменные существуют только внутри формулы и не сохраняются в набор данных.
Редактор формул
Редактор формул предоставляет ряд возможностей для удобства написания формул:
- Подсветка синтаксиса — числа, строки, операторы и вызовы функций выделяются цветом
- Подсветка парных скобок — при установке курсора рядом со скобкой подсвечивается соответствующая ей парная скобка
- Автодополнение — начните вводить (от 2 символов), и появится список предложений с переменными, функциями и константами. Нажмите Ctrl+Space, чтобы открыть список вручную. В предложениях переменных рядом со ссылкой отображается имя переменной (например,
v1 Age) - Проверка ошибок — синтаксические ошибки подчёркиваются в редакторе с описанием на полях. Ошибки обнаруживаются по мере ввода
- Поиск — нажмите Ctrl+F для поиска текста, Ctrl+H для поиска и замены
Советы
- Пропущенные значения становятся
0в формулах. Если нужно иное поведение, используйтеcoalesce(v1, значениеПоУмолчанию)для подстановки конкретного значения или условное выражениеv1 == 0 ? NaN : v1, чтобы пометить их. v1vsc1—v1даёт одно значение (текущей строки),c1— весь столбец в виде массива. Используйтеc1для расчётов по всему столбцу:v1 - mean(c1)центрирует каждое значение относительно среднего по столбцу.- Ошибки в формулах приводят к пропущенному значению в этой строке — остальные данные не затрагиваются. Проверьте предпросмотр данных, чтобы выявить неожиданные пустые значения.
- Конкатенация строк выполняется через
+:v1 + " " + v2объединяет два текстовых значения через пробел. - Скобки управляют порядком вычислений ожидаемым образом:
(v1 + v2) * v3. - Константы
pi,e,InfinityиNaNдоступны в формулах. - Комментарии добавляются через
//:v1 + v2 // суммарный балл. Всё после//в той же строке игнорируется.