$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 wantto represent and do not wish to generalize about a largerpopulation. $stdDevPop ignores non-numeric values.

If the values represent only a sample of a population of data fromwhich to generalize about the population, use $stdDevSampinstead.

$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 expressionWhen used in the $group stage, $stdDevPop returnsthe population standard deviation of the specified expression for agroup of documents that share the same group by key and has thefollowing syntax:

  • $stdDevPop has one specified expression as itsoperand:

  1. { $stdDevPop: <expression> }

When used in the other supported stages,$stdDevPop returns the standard deviation of thespecified expression or list of expressions for each document andhas one of two syntaxes:

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

The argument for $stdDevPop can be anyexpression as long as it resolvesto an array. For more information on expressions, seeExpressions

Behavior

Non-numeric Values

$stdDevPop ignores non-numeric values. If all operands for a$stdDevPop are non-numeric, $stdDevPop returnsnull.

Single Value

If the sample consists of a single numeric value, $stdDevPopreturns 0.

Array Operand

In the $group stage, if the expression resolves to anarray, $stdDevPop treats the operand as a non-numerical value.

In the other supported stages:

  • With a single expression as its operand, if the expression resolvesto an array, $stdDevPop traverses into the array to operate on thenumerical elements of the array to return a single value.
  • With a list of expressions as its operand, if any of the expressionsresolves to an array, $stdDevPop does not traverse into thearray but instead treats the array as a non-numerical value.

Examples

Use in $group Stage

A collection named users contains the following documents:

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

The following example calculates the standard deviation of each quiz:

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

The operation returns the following results:

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

Use in $project Stage

Create an example collection named quizzes with the followingdocuments:

  1. db.quizzes.insertMany([
  2.    {
  3.       "_id" : 1,
  4.       "scores" : [
  5.          { "name" : "dave123", "score" : 85 },
  6.          { "name" : "dave2", "score" : 90 },
  7.          { "name" : "ahn", "score" : 71 }
  8.       ]
  9.    },
  10.    {
  11.       "_id" : 2,
  12.       "scores" : [
  13.          { "name" : "li", "quiz" : 2, "score" : 96 },
  14.          { "name" : "annT", "score" : 77 },
  15.          { "name" : "ty", "score" : 82 }
  16.       ]
  17.    }
  18. ])

The following example calculates the standard deviation of each quiz:

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

The operation returns the following results:

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