이 번역 페이지는 최신 내용을 담고 있지 않습니다. 최신 내용을 영문으로 보려면 여기를 클릭하십시오.

varfun

함수를 테이블 또는 타임테이블 변수에 적용

구문

B = varfun(func,A)

B = varfun(func,A,Name,Value)

설명

B = varfun(func,A)는 func 함수를 개별적으로 테이블 또는 타임테이블 A의 각 변수에 적용하고 그 결과를 테이블 또는 타임테이블 B에 반환합니다.

함수 func는 호출될 때마다 입력 인수를 하나 가져와서 같은 개수의 행을 포함한 배열을 반환해야 합니다. 출력 인수의 i번째 값 B{:,i}는 func(A{:,i})와 같습니다.

B = varfun(func,A,Name,Value)는 하나 이상의 Name,Value 인수로 지정된 추가 옵션을 사용하여 테이블 또는 타임테이블 A의 각 변수에 개별적으로 함수 func를 적용합니다.

예를 들어, "GroupingVariables" 이름-값 인수를 사용하여 테이블 변수의 데이터 그룹에 대한 계산을 수행할 수 있습니다. 데이터 그룹 계산에 대한 자세한 내용은 데이터 그룹에 대한 계산 항목을 참조하십시오.

예제

요소별 함수 적용하기

테이블의 변수에 요소별 함수를 적용합니다.

숫자형 변수가 포함된 테이블을 만듭니다.

A = table([10.71;-2.05;-0.35;-0.82;1.57],[9.23;3.12;-1.18;0.23;16.41])

A=5×2 table
    Var1     Var2 
    _____    _____

    10.71     9.23
    -2.05     3.12
    -0.35    -1.18
    -0.82     0.23
     1.57    16.41

round 함수를 사용하여 A의 숫자형 값을 반올림합니다. 함수를 varfun에 대한 입력 인수로 지정하려면 @ 기호를 사용하십시오. 출력 테이블 B의 변수 이름에는 함수에 기반한 이름과 A의 변수 이름이 사용됩니다.

B = varfun(@round,A)

B=5×2 table
    round_Var1    round_Var2
    __________    __________

        11             9    
        -2             3    
         0            -1    
        -1             0    
         2            16    

테이블 변수를 축소하는 함수 적용하기

첫 번째 차원을 따라 테이블 변수를 축소하는 함수(예: sum 또는 max)를 적용할 수 있습니다. 예를 들어, varfun을 사용하여 테이블에 있는 각 변수의 평균을 계산합니다.

숫자형 변수가 포함된 테이블을 만듭니다.

A = table([0.71;-2.05;-0.35;-0.82;1.57],[0.23;0.12;-0.18;0.23;0.41])

A=5×2 table
    Var1     Var2 
    _____    _____

     0.71     0.23
    -2.05     0.12
    -0.35    -0.18
    -0.82     0.23
     1.57     0.41

func를 mean 함수로 지정합니다. func를 함수 핸들로 지정하려면 @ 기호를 사용하십시오.

func = @mean

func = function_handle with value:
    @mean

함수를 테이블 A의 모든 변수에 적용합니다.

B = varfun(func,A)

B=1×2 table
    mean_Var1    mean_Var2
    _________    _________

     -0.188        0.162  

B는 각 변수의 평균값을 포함하는 테이블입니다.

varfun이 테이블 대신 숫자형 벡터를 반환하도록 하려면 "OutputFormat"을 "uniform"으로 지정하십시오. "uniform" 출력 형식을 사용하려면 func가 항상 스칼라를 반환해야 합니다.

B = varfun(func,A,"OutputFormat","uniform")

B = 1×2

   -0.1880    0.1620

함수를 변수 내 그룹에 적용하기

데이터가 담긴 숫자형 변수 여러 개와 그룹화 변수인 비숫자형 변수 한 개를 포함하는 테이블을 만듭니다. 그런 다음, 숫자형 변수 내의 각 그룹에 대해 계산을 수행합니다.

readtable 함수를 사용하여 CSV(쉼표로 구분된 값) 파일인 testScores.csv의 데이터를 테이블로 읽어올 수 있습니다. 샘플 파일에는 두 학교에 다니는 학생 10명의 테스트 점수가 포함되어 있습니다. 출력 테이블에는 숫자형 데이터를 가지는 변수와 텍스트 데이터를 가지는 다른 변수가 포함됩니다. 이러한 변수 중 하나인 School에는 고정된 값 집합 또는 범주 집합이 있습니다. 이러한 범주는 이 테이블 내에 있는 두 개의 학생 그룹을 나타냅니다. School을 categorical형 변수로 변환합니다.

scores = readtable("testScores.csv","TextType","string");
scores.School = categorical(scores.School)

scores=10×5 table
     LastName       School      Test1    Test2    Test3
    __________    __________    _____    _____    _____

    "Jeong"       XYZ School     90       87       93  
    "Collins"     XYZ School     87       85       83  
    "Torres"      XYZ School     86       85       88  
    "Phillips"    ABC School     75       80       72  
    "Ling"        ABC School     89       86       87  
    "Ramirez"     ABC School     96       92       98  
    "Lee"         XYZ School     78       75       77  
    "Walker"      ABC School     91       94       92  
    "Garcia"      ABC School     86       83       85  
    "Chang"       XYZ School     79       76       82  

학교별로 각 테스트의 평균 점수를 계산합니다. 변수 Test1, Test2, Test3은 데이터를 포함하는 숫자형 변수입니다. School 변수는 그룹화 변수입니다. 그룹화 변수를 지정하면 그룹화 변수의 고유한 값에 의해 데이터 변수의 대응값이 속하는 그룹이 결정됩니다.

vars = ["Test1","Test2","Test3"];
meanScoresBySchool = varfun(@mean, ...
                            scores, ...
                            "InputVariables",vars, ...
                            "GroupingVariables","School")

meanScoresBySchool=2×5 table
      School      GroupCount    mean_Test1    mean_Test2    mean_Test3
    __________    __________    __________    __________    __________

    ABC School        5            87.4            87          86.8   
    XYZ School        5              84          81.6          84.6   

출력 meanScoresBySchool은 이러한 그룹의 입력 테이블 scores에 있는 항목의 개수를 나타내는 GroupCount라는 변수도 포함합니다.

함수를 타임테이블 변수 내 그룹에 적용하기

샘플 데이터가 포함된 타임테이블을 만듭니다. 행 시간값은 중복된 값이 허용되므로 타임테이블의 행 시간값에 대해서도 그룹을 정의할 수 있습니다.

Timestamps = datetime(2023,1,1)+days([0 1 1 2 3 3])';
A = timetable(Timestamps, ...
              [0.71;-2.05;-0.35;-0.82;1.57;0.09], ...
              [0.23;0.12;-0.18;0.23;0.41;0.02], ...
              'VariableNames',["x","y"])

A=6×2 timetable
    Timestamps       x        y  
    ___________    _____    _____

    01-Jan-2023     0.71     0.23
    02-Jan-2023    -2.05     0.12
    02-Jan-2023    -0.35    -0.18
    03-Jan-2023    -0.82     0.23
    04-Jan-2023     1.57     0.41
    04-Jan-2023     0.09     0.02

타임테이블에 포함된 변수의 평균값을 계산합니다. 행 시간값으로 구성된 벡터를 그룹화 변수로 지정합니다. 입력 A가 타임테이블이므로 출력 B는 타임테이블입니다. 행 시간값으로 구성된 벡터를 그룹화 변수로 지정하는 경우, 어떤 변수도 또 다른 그룹화 변수로 지정할 수 없습니다.

B = varfun(@mean,A,"GroupingVariables","Timestamps")

B=4×3 timetable
    Timestamps     GroupCount    mean_x    mean_y
    ___________    __________    ______    ______

    01-Jan-2023        1          0.71      0.23 
    02-Jan-2023        2          -1.2     -0.03 
    03-Jan-2023        1         -0.82      0.23 
    04-Jan-2023        2          0.83     0.215 

입력 인수

func — 함수

함수 핸들

함수로, 함수 핸들로 지정됩니다. 기존 함수의 핸들을 지정하거나, 함수를 파일에 정의하거나, 함수를 익명 함수로 정의할 수 있습니다. func가 둘 이상의 함수 파일에 대응하는 경우(즉, func가 일련의 오버로드된 함수를 나타내는 경우) MATLAB^®은 입력 인수의 클래스에 따라 어떤 함수를 호출할지를 결정합니다.

함수 func가 호출될 때마다 한 개의 입력 인수를 받고 서로 다른 개수의 행을 포함하는 배열을 반환하는 경우에는 "OutputFormat","cell" 이름-값 인수를 사용하십시오. 그렇지 않으면, func는 같은 개수의 행을 포함하는 배열을 반환해야 합니다.

예: func = @sum;은 입력값의 합을 계산합니다.

예: func = @(x) x.^2;은 입력값의 각 요소의 제곱을 계산합니다.

A — 입력 테이블

테이블 | 타임테이블

입력 테이블로, table형이나 timetable형으로 지정됩니다.

이름-값 인수

선택적 인수 쌍을 Name1=Value1,...,NameN=ValueN으로 지정합니다. 여기서 Name은 인수 이름이고 Value는 대응값입니다. 이름-값 인수는 다른 인수 뒤에 와야 하지만, 인수 쌍의 순서는 상관없습니다.

R2021a 이전 릴리스에서는 쉼표를 사용하여 각 이름과 값을 구분하고 Name을 따옴표로 묶으십시오.

예: InputVariables=["Var2","Var3"]은 func의 입력값으로 A의 Var2 변수와 Var3 변수만 사용합니다.

InputVariables — func에 전달할 A의 변수를 선택하기 위한 지정자

양의 정수 | 양의 정수로 구성된 벡터 | string형 배열 | 문자형 벡터 | 문자형 벡터로 구성된 셀형 배열 | pattern형 스칼라 | 논리형 벡터 | 함수 핸들

func에 전달할 A의 변수를 선택하기 위한 지정자로, "InputVariables"와 함께 양의 정수, 양의 정수로 구성된 벡터, string형 배열, 문자형 벡터, 문자형 벡터로 구성된 셀형 배열, pattern 스칼라, 논리형 벡터 또는 함수 핸들로 지정됩니다.

"InputVariables"를 함수 핸들로 지정하는 경우, 이것은 논리형 스칼라를 반환해야 하고, varfun은 A에서 함수가 1(true)을 반환하는 변수만 전달합니다.

GroupingVariables — 그룹화 변수가 될 A의 변수를 선택하기 위한 지정자

양의 정수 | 양의 정수로 구성된 벡터 | string형 배열 | 문자형 벡터 | 문자형 벡터로 구성된 셀형 배열 | pattern형 스칼라 | 논리형 벡터

그룹화 변수가 될 A의 변수를 선택하기 위한 지정자로, "GroupingVariables"와 함께 양의 정수, 양의 정수로 구성된 벡터, string형 배열, 문자형 벡터, 문자형 벡터로 구성된 셀형 배열, pattern 스칼라 또는 논리형 벡터로 지정됩니다.

그룹화 변수의 고유한 값은 그룹을 지정합니다. A에서 그룹화 변수 값이 같은 행은 같은 그룹에 속합니다. varfun은 func를 전체 변수가 아니라, A의 남아 있는 각 변수 내 각 행 그룹에 적용합니다. 그룹화 변수를 사용한 계산에 대한 자세한 내용은 데이터 그룹에 대한 계산 항목을 참조하십시오.

그룹화 변수는 다음 표에 나열된 임의의 데이터형을 가질 수 있습니다.

그룹을 지정하는 값	그룹화 변수의 데이터형
숫자	숫자형 벡터 또는 논리형 벡터
텍스트	string형 배열, 또는 문자형 벡터로 구성된 셀형 배열
날짜/시간	datetime형 벡터, duration형 벡터 또는 calendarDuration형 벡터
범주	categorical형 벡터
Bin	숫자형 값, datetime형 값 또는 duration형 값의 연속 분포를 비닝하여 생성된 비닝된 값으로 구성된 벡터

그룹화 변수가 NaN 또는 누락값(예: NaT, 정의되지 않은 categorical형 값 또는 누락값인 string형)을 포함하는 경우, 이에 해당하는 행은 어떤 그룹에도 속하지 않으며 출력값에서 제외됩니다.

행 레이블은 그룹화 변수일 수 있습니다. 사용자는 행 레이블만을 기준으로, 또는 하나 이상의 A의 변수를 기준으로, 또는 행 레이블과 변수를 함께 기준으로 하여 그룹화할 수 있습니다.

• A가 테이블인 경우 레이블은 행 이름입니다.

• A가 타임테이블인 경우 레이블은 행 시간값입니다.

출력값 B는 입력값 A의 각 행 그룹에 대한 하나의 행을 포함합니다. B가 테이블 또는 타임테이블이면 B는 다음을 포함합니다.

• func가 적용된 입력 테이블 변수에 대응하는 변수.

• 그룹화 변수에 대응하는 변수.

• 값이 각 그룹에 있는 입력값 A의 행 개수인 새로운 변수 GroupCount.

참고: B가 타임테이블이면 B는 다음도 포함합니다.

• A의 각 행 그룹의 첫 번째 행 시간값이 B의 대응하는 행 시간값인 행 시간값. B를 행 시간값이 없는 테이블로 반환하려면 "OutputFormat"을 "table"로 지정하십시오.

OutputFormat — B의 형식

"auto" (디폴트 값) | "table" | "timetable" | "uniform" | "cell"

B의 형식으로, "OutputFormat"과 함께 값 "auto", "table", "timetable", "uniform", "cell" 중 하나로 지정됩니다.

"auto"(디폴트 값) (R2023a 이후)	varfun은 데이터형이 입력값 A의 데이터형과 일치하는 출력값을 반환합니다.
"table"	varfun은 A의 각 변수(또는 "InputVariables"로 지정한 각 변수)에 대한 변수를 하나씩 포함한 테이블을 반환합니다. 그룹화 계산의 경우, B에는 그룹화 변수와 새 GroupCount 변수도 포함됩니다. "table"을 사용하여 A의 서로 다른 변수에 대해 크기나 데이터형이 다른 값을 반환하는 함수를 사용할 수 있습니다. 하지만 그룹화되지 않은 계산의 경우, func는 호출될 때마다 행 개수가 같은 배열을 반환해야 합니다. 그룹화된 계산의 경우에는 지정된 그룹에 대해 func를 호출할 때마다 이 함수는 행 개수가 같은 값을 반환해야 합니다. A가 테이블인 경우 이것은 디폴트 출력 형식입니다.
"timetable"	varfun은 A의 각 변수(또는 "InputVariables"로 지정한 각 변수)에 대한 변수를 하나씩 포함한 타임테이블을 반환합니다. 그룹화 계산의 경우, B에는 그룹화 변수와 새 GroupCount 변수도 포함됩니다. varfun은 A의 행 시간값에서 B의 행 시간값을 만듭니다. B에 할당된 행 시간값이 func를 사용하여 수행된 계산 맥락에서 타당하지 않은 경우, 출력 형식을 "OutputFormat","table"로 지정하십시오. A가 타임테이블인 경우 이것은 디폴트 출력 형식입니다.
"uniform"	varfun은 출력값들을 하나의 벡터에 결합합니다. func는 호출될 때마다 같은 데이터형의 스칼라를 반환해야 합니다.
"cell"	varfun은 출력값을 셀형 배열로 반환합니다. "cell"을 사용하면 크기나 데이터형이 다른 값을 반환하는 함수를 사용할 수 있습니다.

ErrorHandler — func가 실패할 경우 호출할 함수

함수 핸들

func가 실패할 경우 호출할 함수로, "ErrorHandler"와 함께 함수 핸들로 지정됩니다. 오류를 다시 발생시키거나 함수 func에 대해 유효한 출력값을 반환하도록 이 함수를 정의합니다.

MATLAB에서는 다음과 같이 2개의 입력 인수로 지정된 오류 처리 함수를 호출합니다.

• 다음 필드를 포함한 구조체:

  identifier	오류 ID입니다.
  message	오류 메시지 텍스트입니다.
  index	오류가 발생한 변수의 인덱스입니다.
  name	오류가 발생한 변수의 이름입니다.

• 오류 발생 시 함수 func의 입력 인수 세트

예를 들면 다음과 같습니다.

function [A, B] = errorFunc(S, varargin)
warning(S.identifier, S.message)
A = NaN; B = NaN;

출력 인수

B — 출력값

테이블 | 타임테이블 | 셀형 배열 | 벡터

출력값으로, 테이블, 타임테이블, 셀형 배열 또는 벡터로 반환됩니다.

B가 테이블 또는 타임테이블이면 설명, 변수 단위, 변수 이름, 행 이름과 같은 메타데이터를 저장할 수 있습니다. 자세한 내용은 table 또는 timetable 속성 설명을 참조하십시오.

세부 정보

데이터 그룹에 대한 계산

데이터 분석에서는 일반적으로 데이터 그룹에 대한 계산을 수행합니다. 이러한 계산의 경우 하나 이상의 데이터 변수를 데이터 그룹으로 분할하고, 각 그룹에 대해 계산을 수행하고, 결과를 하나 이상의 출력 변수로 조합합니다. 하나 이상의 그룹화 변수를 사용하여 그룹을 지정할 수 있습니다. 그룹화 변수의 고유 값은 데이터 변수의 대응값이 속하는 그룹을 정의합니다.

예를 들어, 다음 도식은 6×1 숫자형 벡터를 두 개의 데이터 그룹으로 분할하고 각 그룹의 평균을 계산한 다음 출력값을 2×1 숫자형 벡터로 조합하는 그룹화된 간단한 계산을 보여줍니다. 6×1 그룹화 변수에는 두 개의 고유한 값 AB와 XYZ가 있습니다.

숫자, 텍스트, 날짜/시간, 범주 또는 Bin이 포함된 그룹화 변수를 지정할 수 있습니다.

확장 기능

tall형 배열

메모리에 담을 수 없을 정도로 많은 행을 가진 배열을 계산할 수 있습니다.

이 함수는 tall형 배열을 지원하지만 다음과 같은 제한 사항이 있습니다.

• func 입력값은 항상 tall형 배열을 반환합니다.

• 지원되는 이름-값 쌍은 다음과 같습니다.

  • 'InputVariables' — 함수 핸들 또는 패턴 표현식으로 지정할 수 없습니다.

  • 'GroupingVariables' — 값은 패턴 표현식이 될 수 없습니다.

  • 'OutputFormat' — 값은 'uniform', 'table', 'timetable', 'cell' 중 하나만 될 수 있습니다.

• 입력 배열이 tall형 타임테이블이고 'OutputFormat'이 'timetable'인 경우 지정한 함수는 첫 번째 차원의 크기가 입력값과 같은 배열을 반환해야 합니다. 입력 함수가 mean과 같은 감소 함수일 때는 'OutputFormat'을 'table'로 지정하십시오.

자세한 내용은 tall형 배열 항목을 참조하십시오.

C/C++ 코드 생성

MATLAB® Coder™를 사용하여 C 코드나 C++ 코드를 생성할 수 있습니다.

사용법 관련 참고 및 제한 사항:

• 함수 핸들 입력값 func는 상수여야 합니다.

• 함수 핸들은 varfun 함수 자체에 대한 입력값은 될 수 있지만, 진입점 함수에 대한 입력값은 될 수 없습니다. 코드 생성 용도의 코드 내에 func를 지정하십시오. 자세한 내용은 코드 생성 시 함수 핸들 제한 사항 (MATLAB Coder) 항목을 참조하십시오.

• 모든 이름-값 인수의 값은 상수여야 합니다.

• "InputVariables"와 "GroupingVariables" 이름-값 인수의 값은 패턴 표현식을 지원하지 않습니다.

• 코드 생성 시 "ErrorHandler" 이름-값 인수는 지원되지 않습니다.

• 가변 크기 입력 인수는 지원되지 않습니다.

• 생성된 코드에서 그룹화 변수는 중복된 값을 가질 수 없습니다.

• "GroupingVariables" 이름-값 인수를 지정했고 "InputVariables"로 지정된 각 변수에 대해 함수가 서로 다른 데이터형을 반환하는 경우에는 "OutputFormat"의 값을 "cell"로 지정할 수 없습니다.

• 입력값이 timetable형이고 "GroupingVariables"를 지정하는 경우 출력값은 항상 불규칙적인 타임테이블입니다.

• 그룹을 지정했고 컴파일 시점에는 그룹의 수를 알지 못하며 그룹 수가 0이면 생성된 코드에서 출력값의 빈 double형 변수는 크기가 1×0일 수 있습니다. 이러한 변수는 MATLAB에서 크기가 0×0입니다.

스레드 기반 환경
MATLAB®의 backgroundPool을 사용해 백그라운드에서 코드를 실행하거나 Parallel Computing Toolbox™의 ThreadPool을 사용해 코드 실행 속도를 높일 수 있습니다.

버전 내역

R2013b에 개발됨

R2023a: "OutputFormat" 이름-값 인수는 "auto"를 값으로 받을 수 있음

"OutputFormat" 이름-값 인수는 "auto"를 값으로 받을 수 있습니다. 이 값은 디폴트 값입니다. 이 경우 varfun은 데이터형이 입력값 A의 데이터형과 일치하는 출력값을 반환합니다.

참고 항목

rowfun | cellfun | structfun | arrayfun | findgroups | splitapply | groupsummary | convertvars | vartype

도움말 항목

• 테이블에 숫자형 데이터와 숫자형이 아닌 데이터가 모두 있는 경우의 계산
• 익명 함수
• Perform Calculations by Group in Table
• Data Cleaning and Calculations in Tables
• Grouped Calculations in Tables and Timetables