# $stdDevPop (aggregation)¶

On this page

## Definition¶

`$stdDevPop`

¶

*Changed in version 5.0*.

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 these stages:

`$addFields`

(Available starting in MongoDB 3.4)`$group`

`$match`

stage that includes an`$expr`

expression`$project`

`$replaceRoot`

(Available starting in MongoDB 3.4)`$replaceWith`

(Available starting in MongoDB 4.2)`$set`

(Available starting in MongoDB 4.2)`$setWindowFields`

(Available starting in MongoDB 5.0)

## Syntax¶

When used in the `$bucket`

, `$bucketAuto`

,
`$group`

, and `$setWindowFields`

stages,
`$stdDevPop`

has this syntax:

{ $stdDevPop: <expression> }

When used in other supported stages, `$stdDevPop`

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`

and `$setWindowFields`

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

treats the
operand as a non-numerical value and has no effect on the calculation.

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.

### Window Values¶

Behavior with values in a `$setWindowFields`

stage
window:

- Ignores non-numeric values,
`null`

values, and missing fields in a window. - If the window is empty, returns
`null`

. - If the window contains a
`NaN`

value, returns`null`

. - If the window contains
`Infinity`

values, returns`null`

. - If none of the previous points apply, returns a
`double`

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 }

### Use in `$setWindowFields`

Stage¶

*New in version 5.0*.

Create a `cakeSales`

collection that contains cake sales in the states
of California (`CA`

) and Washington (`WA`

):

db.cakeSales.insertMany( [ { _id: 0, type: "chocolate", orderDate: new Date("2020-05-18T14:10:30Z"), state: "CA", price: 13, quantity: 120 }, { _id: 1, type: "chocolate", orderDate: new Date("2021-03-20T11:30:05Z"), state: "WA", price: 14, quantity: 140 }, { _id: 2, type: "vanilla", orderDate: new Date("2021-01-11T06:31:15Z"), state: "CA", price: 12, quantity: 145 }, { _id: 3, type: "vanilla", orderDate: new Date("2020-02-08T13:13:23Z"), state: "WA", price: 13, quantity: 104 }, { _id: 4, type: "strawberry", orderDate: new Date("2019-05-18T16:09:01Z"), state: "CA", price: 41, quantity: 162 }, { _id: 5, type: "strawberry", orderDate: new Date("2019-01-08T06:12:03Z"), state: "WA", price: 43, quantity: 134 } ] )

This example uses `$stdDevPop`

in the
`$setWindowFields`

stage to output the population standard
deviation of the cake sales `quantity`

for each `state`

:

db.cakeSales.aggregate( [ { $setWindowFields: { partitionBy: "$state", sortBy: { orderDate: 1 }, output: { stdDevPopQuantityForState: { $stdDevPop: "$quantity", window: { documents: [ "unbounded", "current" ] } } } } } ] )

In the example:

`partitionBy: "$state"`

partitions the documents in the collection by`state`

. There are partitions for`CA`

and`WA`

.`sortBy: { orderDate: 1 }`

sorts the documents in each partition by`orderDate`

in ascending order (`1`

), so the earliest`orderDate`

is first.

`output`

sets the`stdDevPopQuantityForState`

field to the`quantity`

population standard deviation value using`$stdDevPop`

that is run in a documents window.The window contains documents between an

`unbounded`

lower limit and the`current`

document in the output. This means`$stdDevPop`

returns the`quantity`

population standard deviation value for the documents between the beginning of the partition and the current document.

In this example output, the `quantity`

population standard deviation
value for `CA`

and `WA`

is shown in the
`stdDevPopQuantityForState`

field:

{ "_id" : 4, "type" : "strawberry", "orderDate" : ISODate("2019-05-18T16:09:01Z"), "state" : "CA", "price" : 41, "quantity" : 162, "stdDevPopQuantityForState" : 0 } { "_id" : 0, "type" : "chocolate", "orderDate" : ISODate("2020-05-18T14:10:30Z"), "state" : "CA", "price" : 13, "quantity" : 120, "stdDevPopQuantityForState" : 21 } { "_id" : 2, "type" : "vanilla", "orderDate" : ISODate("2021-01-11T06:31:15Z"), "state" : "CA", "price" : 12, "quantity" : 145, "stdDevPopQuantityForState" : 17.249798710580816 } { "_id" : 5, "type" : "strawberry", "orderDate" : ISODate("2019-01-08T06:12:03Z"), "state" : "WA", "price" : 43, "quantity" : 134, "stdDevPopQuantityForState" : 0 } { "_id" : 3, "type" : "vanilla", "orderDate" : ISODate("2020-02-08T13:13:23Z"), "state" : "WA", "price" : 13, "quantity" : 104, "stdDevPopQuantityForState" : 15 } { "_id" : 1, "type" : "chocolate", "orderDate" : ISODate("2021-03-20T11:30:05Z"), "state" : "WA", "price" : 14, "quantity" : 140, "stdDevPopQuantityForState" : 15.748015748023622 }