histcounts

Recuentos de bins de un histograma

Sintaxis

[N,edges] = histcounts(X)

[N,edges] = histcounts(X,nbins)

[N,edges] = histcounts(X,edges)

[N,edges,bin] = histcounts(___)

N = histcounts(C)

N = histcounts(C,Categories)

[N,Categories] = histcounts(___)

[___] = histcounts(___,Name,Value)

Descripción

[N,edges] = histcounts(X) divide los valores de X en bins y devuelve los recuentos de bins y los bordes de los bins. La función histcounts usa un algoritmo de discretización automático que devuelve bins uniformes elegidos para cubrir el intervalo de elementos en X y revelar la forma subyacente de la distribución.

[N,edges] = histcounts(X,nbins) utiliza un número de bins especificado por el escalar, nbins.

[N,edges] = histcounts(X,edges) clasifica X en bins con los bordes de los bins especificados por el vector, edges.

[N,edges,bin] = histcounts(___) también devuelve un arreglo de índices, bin, usando cualquiera de las sintaxis anteriores. bin es un arreglo del mismo tamaño que X cuyos elementos son los índices de bin para los elementos correspondientes de X. El número de elementos del k-ésimo bin es nnz(bin==k), que es igual que N(k).

N = histcounts(C), donde C es un arreglo categórico, devuelve un vector, N, que indica el número de elementos de C cuyo valor es igual a cada categoría de C. N tiene un elemento para cada categoría de C.

N = histcounts(C,Categories) solo cuenta los elementos de C cuyo valor es igual al subconjunto de categorías especificado por Categories.

[N,Categories] = histcounts(___) también devuelve las categorías que corresponden a cada recuento de N usando cualquiera de las sintaxis anteriores para arreglos categóricos.

[___] = histcounts(___,Name,Value) especifica parámetros adicionales con uno o más argumentos nombre-valor. Por ejemplo, puede especificar BinWidth como escalar para ajustar la anchura de los bins para datos numéricos.

Ejemplos

Recuentos de bins y bordes de los bins

Distribuya 100 valores aleatorios en bins. histcounts elige automáticamente una anchura de bin adecuada para revelar la distribución subyacente de los datos.

X = randn(100,1);
[N,edges] = histcounts(X)

N = 1×7

     2    17    28    32    16     3     2

edges = 1×8

    -3    -2    -1     0     1     2     3     4

Especificar la cantidad de bins

Distribuya 10 números en 6 bins equidistantes.

X = [2 3 5 7 11 13 17 19 23 29];
[N,edges] = histcounts(X,6)

N = 1×6

     2     2     2     2     1     1

edges = 1×7

         0    4.9000    9.8000   14.7000   19.6000   24.5000   29.4000

Especificar los bordes de los bins

Distribuya 1.000 números aleatorios en bins. Defina los bordes de los bins con un vector, donde el primer elemento es el borde izquierdo del primer bin, y el último elemento es el borde derecho del último bin.

X = randn(1000,1);
edges = [-5 -4 -2 -1 -0.5 0 0.5 1 2 4 5];
N = histcounts(X,edges)

N = 1×10

     0    24   149   142   195   200   154   111    25     0

Recuentos de bins normalizados

Distribuya todos los números primos menores que 100 en bins. Especifique 'Normalization' como 'probability' para normalizar los recuentos de bins para que sum(N) sea 1. Es decir, cada recuento de bin representa la probabilidad de que una observación esté dentro de ese bin.

X = primes(100);
[N,edges] = histcounts(X, 'Normalization', 'probability')

N = 1×4

    0.4000    0.2800    0.2800    0.0400

edges = 1×5

     0    30    60    90   120

Determinar la ubicación de un bin

Distribuya 100 enteros aleatorios entre -5 y 5 en bins y especifique 'BinMethod' como 'integers' para usar bins de anchura unitaria centrados en enteros. Especifique una tercera salida para que histcounts devuelva un vector que represente los índices de bin de los datos.

X = randi([-5,5],100,1);
[N,edges,bin] = histcounts(X,'BinMethod','integers');

Encuentre el recuento de bin para el tercer bin contando las instancias del número 3 en el vector de índices del bin, bin. El resultado es el mismo que N(3).

count = nnz(bin==3)

count = 
8

Recuentos de bins categóricos

Cree un vector categórico que represente votos. Las categorías del vector son 'yes', 'no' o 'undecided'.

A = [0 0 1 1 1 0 0 0 0 NaN NaN 1 0 0 0 1 0 1 0 1 0 0 0 1 1 1 1];
C = categorical(A,[1 0 NaN],{'yes','no','undecided'})

C = 1×27 categorical
     no      no      yes      yes      yes      no      no      no      no      undecided      undecided      yes      no      no      no      yes      no      yes      no      yes      no      no      no      yes      yes      yes      yes 

Determine el número de elementos que encajan en cada categoría.

[N,Categories] = histcounts(C)

N = 1×3

    11    14     2

Categories = 1×3 cell
    {'yes'}    {'no'}    {'undecided'}

Argumentos de entrada

X — Datos para distribuir entre los bins

vector | matriz | arreglo multidimensional

Datos que se desea distribuir entre los bins, especificados como vector, matriz o arreglo multidimensional. Si X no es un vector, histcounts lo trata como un único vector columna, X(:).

histcounts ignora todos los valores NaN. De igual modo, histcounts ignora los valores Inf y -Inf, a menos que los bordes de los bins especifiquen explícitamente Inf o -Inf como borde de bin.

Tipos de datos: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical | datetime | duration

C — Datos categóricos

arreglo categórico

Datos categóricos, especificados como arreglo categórico. histcounts ignora los valores categóricos sin definir.

Tipos de datos: categorical

nbins — Número de bins

entero positivo

Número de bins, especificado como entero positivo. Si no especifica nbins, histcounts calcula automáticamente cuántos bins deben utilizarse a partir de los valores de X.

Ejemplo: [N,edges] = histcounts(X,15) utiliza 15 bins.

edges — Bordes de los bins

vector

Bordes de los bins, especificados como vector. edges(1) es el borde inicial del primer bin y edges(end) es el borde final del último bin.

Cada bin incluye el borde inicial, pero no incluye el borde final, excepto el último bin que incluye ambos bordes.

Para los datos datetime y duration, edges debe ser un vector datetime o duration en un orden que aumente monótonamente.

Categories — Categorías incluidas en el recuento

todas las categorías (predeterminado) | vector de cadenas | vector de celdas de vectores de caracteres | Escalar pattern | vector categórico

Categorías incluidas en el recuento, especificadas como vector de cadenas, vector de celdas de vectores de caracteres, escalar pattern o vector categórico. De forma predeterminada, histcounts utiliza un bin para cada categoría del arreglo categórico C. Use Categories para especificar un subconjunto único de las categorías.

Ejemplo: h = histcounts(C,["Large","Small"]) solo cuenta los datos categóricos en las categorías Large y Small.

Ejemplo: h = histcounts(C,"Y" + wildcardPattern) cuenta datos categóricos en todas las categorías cuyos nombres empiezan por la letra Y.

Tipos de datos: string | cell | pattern | categorical

Argumentos de par nombre-valor

Especifique pares opcionales de argumentos como Name1=Value1,...,NameN=ValueN, donde Name es el nombre del argumento y Value es el valor correspondiente. Los argumentos nombre-valor deben aparecer después de otros argumentos, pero el orden de los pares no importa.

En las versiones anteriores a R2021a, utilice comas para separar cada nombre y valor, y encierre Name entre comillas.

Ejemplo: [N,edges] = histcounts(X,'Normalization','probability') normaliza los recuentos de bins de N, de forma que sum(N) es 1.

BinWidth — Anchura de los bins

escalar positivo

Anchura de los bins, especificada como escalar positivo. Si especifica BinWidth, histcounts puede usar un máximo de 65.536 bins (o 2¹⁶). Si la anchura de los bins especificada requiere más bins, histcounts usa una anchura de bins más grande, correspondiente al número máximo de bins.

• Para datos datetime y duration, BinWidth puede ser una duración escalar o de calendario.

• Si especifica BinWidth con BinMethod, NumBins o BinEdges, histcounts solo respeta el último parámetro.

• Esta opción no se aplica a datos categóricos.

Ejemplo: histcounts(X,'BinWidth',5) usa bins con una anchura de 5.

BinEdges — Bordes de bins

vector numérico

Bordes de bins, especificados como un vector numérico. El primer elemento especifica el borde inicial del primer bin. El último elemento especifica el borde final del último bin. El borde final solo se incluye para el último bin.

Si no especifica los bordes de los bins, histcounts los determina automáticamente.

Si BinCountsMode es "manual", BinEdges debe ser un vector fila.

• Si especifica BinEdges con BinMethod, BinWidth, NumBins o BinLimits, histcounts solo respeta BinEdges y BinEdges debe especificarse al final.

• Esta opción no se aplica a datos categóricos.

BinLimits — Límites de bins

vector de dos elementos

Límites de bins, especificados como un vector de dos elementos, [bmin,bmax]. El primer elemento indica el primer borde del bin. El segundo elemento indica el último borde del bin.

Esta opción realiza el cálculo utilizando solo los datos que se encuentran dentro de los límites de los bins, ambos incluidos, X>=bmin & X<=bmax.

Esta opción no se aplica a datos categóricos.

Ejemplo: histcounts(X,'BinLimits',[1,10]) agrupa solamente los valores de X que se encuentran entre 1 y 10, ambos incluidos.

BinMethod — Algoritmo de discretización

'auto' (predeterminado) | 'scott' | 'fd' | 'integers' | 'sturges' | 'sqrt' | ...

Algoritmo de discretización, especificado como uno de los valores de esta tabla.

Valor	Descripción
'auto'	El algoritmo predeterminado 'auto' elige un ancho de bin para cubrir el intervalo de datos y revelar la forma de la distribución subyacente.
'scott'	La regla de Scott es óptima si los datos están cerca de distribuirse de manera normal. Esta regla también es adecuada para la mayoría de las otras distribuciones. Utiliza una anchura de bin de 3.5*std(X(:))*numel(X)^(-1/3).
'fd'	La regla de Freedman-Diaconis es menos sensible a valores atípicos en los datos y podría ser más adecuada para datos con distribuciones de cola pesada. Utiliza una anchura de bin de 2*iqr(X(:))*numel(X)^(-1/3), o cuando X contiene valores atípicos extremos, 0.2*(max(X(:))-min(X(:)))*numel(X)^(-1/3).
'integers'	La regla de enteros es útil con datos enteros, ya que crea un bin para cada entero. Utiliza una anchura de bin de 1 y coloca bordes de bins a una distancia media entre los enteros. Para evitar crear accidentalmente demasiados bins, puede usar esta regla para crear un límite de 65.536 bins (216). Si el intervalo de datos es superior a 65.536, la regla de enteros usa bins más anchos. 'integers' no admite datos de marca horaria ni de duración.
'sturges'	La regla de Sturges es popular por su sencillez. Elige el número de bins para que sean ceil(1 + log2(numel(X))) o 1, el que sea mayor.
'sqrt'	La regla de la raíz cuadrada se usa ampliamente en otros paquetes de software. Elige el número de bins para que sean ceil(sqrt(numel(X))) o 1, el que sea mayor.

histcounts ajusta ligeramente el número de bins, de manera que los bordes de los bins caigan en "buenos" números, en lugar de usar estas fórmulas exactas.

Para datos datetime o duration, especifique el algoritmo de discretización como una de estas unidades de tiempo.

Valor	Descripción	Tipo de datos
"second"	Cada bin es de 1 segundo.	datetime y duration
"minute"	Cada bin es de 1 minuto.	datetime y duration
"hour"	Cada bin es de 1 hora.	datetime y duration
"day"	Cada bin es de 1 día natural. Este valor tiene en cuenta los cambios de horario de verano.	datetime y duration
"week"	Cada bin es de 1 semana natural.	Solo datetime
"month"	Cada bin es de 1 mes natural.	Solo datetime
"quarter"	Cada bin es de 1 trimestre natural.	Solo datetime
"year"	Cada bin es de 1 año natural. Este valor tiene en cuenta los años bisiestos.	datetime y duration
"decade"	Cada bin es de 1 década (10 años naturales).	Solo datetime
"century"	Cada bin es de 1 siglo (100 años naturales).	Solo datetime

• Si especifica BinMethod con datos datetime o duration, histcounts puede usar un máximo de 65.536 bins (o 2¹⁶). Si la duración de bins especificada requiere más bins, histcounts usa una anchura de bin más grande, correspondiente al número máximo de bins.

• Si especifica BinLimits, NumBins, BinEdges o BinWidth, BinMethod se establece en 'manual'.

• Si especifica BinMethod con BinWidth, NumBins o BinEdges, histcounts solo respeta el último parámetro.

• Esta opción no se aplica a datos categóricos.

Ejemplo: histcounts(X,'BinMethod','integers') centra los bins en enteros.

Normalization — Tipo de normalización

'count' (predeterminado) | 'probability' | 'percentage' | 'countdensity' | 'cumcount' | 'pdf' | 'cdf'

Tipo de normalización, especificado como uno de los valores de esta tabla. Para cada bin i:

• $$v_i$$ es el valor del bin.

• $$c_i$$ es el número de elementos del bin.

• $$w_i$$ es la anchura del bin.

• $$N$$ es el número de elementos de los datos de entrada. Este valor puede ser superior a los datos incluidos en el bin si estos contienen valores faltantes, como NaN, o si algunos de los datos se encuentran fuera de los límites del bin.

Valor	Valores del bin	Notas
'count' (valor predeterminado)	$$v_i=c_i$$	Número o frecuencia de las observaciones. La suma de los valores de los bins es como máximo numel(X), o sum(ismember(X(:),'Categories')) para datos categóricos. La suma es inferior solo cuando algunos de los datos de entrada no están incluidos en los bins.
'probability'	$$v_i=\frac{c_i}{N}$$	Probabilidad relativa. El número de elementos en cada bin con respecto al número total de elementos en los datos de entrada es como máximo 1.
'percentage'	$$v_i=100*\frac{c_i}{N}$$	Porcentaje relativo. El porcentaje de elementos en cada bin es como máximo 100.
'countdensity'	$$v_i=\frac{c_i}{w_i}$$	Frecuencia o número escalado por anchura del bin. Para datos categóricos, esto es igual que 'count'. 'countdensity' no es compatible con datos datetime o duration. La suma de las áreas de los bins es como máximo numel(X).
'cumcount'	$$v_i={\displaystyle \sum _{j=1}^i{c}_j}$$	Recuento acumulado o número de observaciones de cada bin y de todos los bins anteriores. N(end) es como máximo numel(X), o sum(ismember(X(:),'Categories')) para datos categóricos.
'pdf'	$$v_i=\frac{c_i}{N\cdot w_i}$$	Cálculo de la función de densidad de la probabilidad. Para datos categóricos, esto es igual que 'probability'. 'pdf' no es compatible con datos datetime o duration. La suma de las áreas de los bins es como máximo 1.
'cdf'	$$v_i={\displaystyle \sum _{j=1}^i\frac{c_j}{N}}$$	Cálculo de la función de distribución acumulada. El recuento de cada bin equivale al número relativo acumulado de observaciones del bin y de todos los bins anteriores. N(end) es como máximo 1.

Ejemplo: histcounts(X,'Normalization','pdf') agrupa los datos usando una estimación de la función de densidad de probabilidad.

NumBins — Número de bins

entero positivo

Número de bins, especificado como entero positivo. Si no especifica NumBins, histcounts calcula automáticamente cuántos bins deben utilizarse a partir de los datos de entrada.

• Si especifica NumBins con BinMethod, BinWidth o BinEdges, histcounts solo respeta el último parámetro.

• Esta opción no se aplica a datos categóricos.

Argumentos de salida

N — Recuentos de bins

vector fila

Recuentos de bins, devueltos como vector fila.

edges — Bordes de los bins

vector

Bordes de los bins, devueltos como vector. El primer elemento es el borde inicial del primer bin. El último elemento es el borde final del último bin.

bin — Índices de los bins

arreglo

Índices de los bins, devueltos como arreglo del mismo tamaño que X. Cada elemento de bin describe qué bin numerado contiene el elemento correspondiente de X.

Un valor de 0 en bin indica un elemento que no pertenece a ninguno de los bins (por ejemplo, un valor NaN).

Categories — Categorías incluidas en el recuento

vector de celdas de vectores de caracteres

Categorías incluidas en el recuento, devueltas como vector de celdas de vectores de caracteres. Categories contiene las categorías de C que corresponden a cada recuento de N.

Sugerencias

• El comportamiento de histcounts es similar al de la función discretize. Utilice histcounts para encontrar el número de elementos de cada bin. A la inversa, use discretize para descubrir a qué bin pertenece cada elemento (sin contar).

Capacidades ampliadas

Arreglos altos

Realice cálculos con arreglos que tienen más filas de las que caben en la memoria.

La función histcounts es compatible con arreglos altos con las siguientes notas y limitaciones de uso:

• No se admiten algunas opciones de entradas. Entre las opciones permitidas se encuentran:

  • BinWidth

  • BinLimits

  • Normalization

  • BinMethod: los métodos de bin 'auto' y 'scott' son los mismos. No se admite el método de bin 'fd'.

Para obtener más información, consulte Arreglos altos.

Generación de código C/C++

Genere código C y C++ mediante MATLAB® Coder™.

Notas y limitaciones de uso:

• La generación de código no es compatible con entradas de matrices dispersas en esta función.

• Si no proporciona bordes de los bins, la generación de código puede requerir arreglos de tamaño variable y asignación de memoria dinámica.

• El argumento de entrada Categories no es compatible con las expresiones de patrones.

Generación de código de GPU

Genere código CUDA® para GPU NVIDIA® mediante GPU Coder™.

Notas y limitaciones de uso:

• La generación de código no es compatible con entradas de matrices dispersas en esta función.

• Si no proporciona bordes de los bins, la generación de código puede requerir arreglos de tamaño variable y asignación de memoria dinámica.

• El argumento de entrada Categories no es compatible con las expresiones de patrones.

Entorno basado en subprocesos

Ejecute código en segundo plano con MATLAB® backgroundPool o acelere código con Parallel Computing Toolbox™ ThreadPool.

Esta función es totalmente compatible con entornos basados en subprocesos. Para obtener más información, consulte Ejecutar funciones de MATLAB en entornos basados en subprocesos.

Arreglos GPU

Acelere código mediante la ejecución en una unidad de procesamiento gráfico (GPU) mediante Parallel Computing Toolbox™.

La función histcounts es compatible con entradas de arreglos de GPU con estas notas y limitaciones de uso:

• No se admiten valores enteros de 64 bits.

Para obtener más información, consulte Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Historial de versiones

Introducido en R2014b

R2023b: Normalizar con porcentajes

Puede normalizar los valores del histograma como porcentajes especificando el argumento nombre-valor Normalization como 'percentage'.

R2023a: Rendimiento mejorado con datos de entrada numéricos y lógicos pequeños

La función histcounts muestra un rendimiento mejorado para datos numéricos y lógicos debido al análisis de entrada más rápido. La mejora del rendimiento es más significativa cuando el análisis de entrada supone una fracción mayor del tiempo de cálculo. Esta situación se produce cuando el tamaño de los datos que se desean distribuir entre los bins es inferior a 2.000 elementos.

Por ejemplo, este código calcula recuentos de bins del histograma para un vector de 1.000 elementos. El código es aproximadamente 3 veces más rápido que en la versión anterior.

function timingHistcounts
X = rand(1,1000);
for k = 1:3e3
    histcounts(X,"BinMethod","auto");
end
end

Los tiempos de ejecución aproximados son:

R2022b: 0,62 s

R2023a: 0,21 s

El código se cronometró en un sistema de prueba Windows^® 10, Intel^® Xeon^® CPU E5-1650 v4 con 3,60 GHz utilizando la función timeit.

timeit(@timingHistcounts)

Consulte también

histogram | histogram2 | discretize | histcounts2 | kde

Temas

• Reemplazar las instancias no recomendadas de hist e histc