# $stdDevPop (aggregation)¶

## Definition¶

`$stdDevPop`

¶*New in version 3.2*.Calculates the population standard deviation of the input values. Use if the values encompass the entire population of data you want to represent and do not wish to generalize about a larger population.

`$stdDevPop`

ignores non-numeric values.If the values represent only a sample of a population of data from which to generalize about the population, use

`$stdDevSamp`

instead.`$stdDevPop`

is available in the in the following stages:`$group`

`$project`

`$addFields`

(Available starting in MongoDB 3.4)`$set`

(Available starting in MongoDB 4.2)`$replaceRoot`

(Available starting in MongoDB 3.4)`$replaceWith`

(Available starting in MongoDB 4.2)`$match`

stage that includes an`$expr`

expression

When used in the

`$group`

stage,`$stdDevPop`

returns the population standard deviation of the specified expression for a group of documents that share the same group by key and has the following syntax:`$stdDevPop`

has one specified expression as its operand:{ $stdDevPop: <expression> }

When used in the other supported stages,

`$stdDevPop`

returns the standard deviation of the specified expression or list of expressions for each document and has one of two syntaxes:`$stdDevPop`

has one specified expression as its operand:{ $stdDevPop: <expression> } `$stdDevPop`

has a list of specified expressions as its operand:{ $stdDevPop: [ <expression1>, <expression2> ... ] }

The argument for

`$stdDevPop`

can be any expression as long as it resolves to an array. For more information on expressions, see Expressions

## Behavior¶

### Non-numeric Values¶

`$stdDevPop`

ignores non-numeric values. If all operands for a
`$stdDevPop`

are non-numeric, `$stdDevPop`

returns
`null`

.

### Single Value¶

If the sample consists of a single numeric value, `$stdDevPop`

returns `0`

.

### Array Operand¶

In the `$group`

stage, if the expression resolves to an
array, `$stdDevPop`

treats the operand as a non-numerical value.

In the other supported stages:

- With a single expression as its operand, if the expression resolves
to an array,
`$stdDevPop`

traverses into the array to operate on the numerical elements of the array to return a single value. - With a list of expressions as its operand, if any of the expressions
resolves to an array,
`$stdDevPop`

does**not**traverse into the array but instead treats the array as a non-numerical value.

## Examples¶

### Use in `$group`

Stage¶

A collection named `users`

contains the following documents:

{ "_id" : 1, "name" : "dave123", "quiz" : 1, "score" : 85 } { "_id" : 2, "name" : "dave2", "quiz" : 1, "score" : 90 } { "_id" : 3, "name" : "ahn", "quiz" : 1, "score" : 71 } { "_id" : 4, "name" : "li", "quiz" : 2, "score" : 96 } { "_id" : 5, "name" : "annT", "quiz" : 2, "score" : 77 } { "_id" : 6, "name" : "ty", "quiz" : 2, "score" : 82 }

The following example calculates the standard deviation of each quiz:

db.users.aggregate([ { $group: { _id: "$quiz", stdDev: { $stdDevPop: "$score" } } } ])

The operation returns the following results:

{ "_id" : 2, "stdDev" : 8.04155872120988 } { "_id" : 1, "stdDev" : 8.04155872120988 }

### Use in `$project`

Stage¶

Create an example collection named `quizzes`

with the following
documents:

db.quizzes.insertMany([ { "_id" : 1, "scores" : [ { "name" : "dave123", "score" : 85 }, { "name" : "dave2", "score" : 90 }, { "name" : "ahn", "score" : 71 } ] }, { "_id" : 2, "scores" : [ { "name" : "li", "quiz" : 2, "score" : 96 }, { "name" : "annT", "score" : 77 }, { "name" : "ty", "score" : 82 } ] } ])

The following example calculates the standard deviation of each quiz:

db.quizzes.aggregate([ { $project: { stdDev: { $stdDevPop: "$scores.score" } } } ])

The operation returns the following results:

{ "_id" : 1, "stdDev" : 8.04155872120988 } { "_id" : 2, "stdDev" : 8.04155872120988 }