The $atanh operator returns the inverse hyperbolic tangent of a number in MongoDB aggregation pipelines. It is the reverse of $tanh and is commonly used for data transforms and statistical modeling.
Reverse of hyperbolic tangent.
One expression inside $atanh.
Values between -1 and 1.
Add computed fields easily.
Stats, ML, transforms.
atanh(0) = 0
In MongoDB’s aggregation framework, the $atanh operator computes the inverse hyperbolic tangent of a numeric expression. If tanh(y) = x, then atanh(x) = y. For example, $atanh(0.5) returns approximately 0.549, and $atanh(0) returns 0.
Do not confuse $atanh with $atan. $atanh is hyperbolic math (like Math.atanh()), while $atan is regular trigonometry. They have different input rules and meanings.
The $atanh operator takes one numeric expression:
{ $atanh: <expression> }$atanh — returns the inverse hyperbolic tangent of the expression.<expression> — must evaluate to a number strictly between -1 and 1.$project, $addFields, or $set.null, the result is null.1, -1, or outside the range return null or NaN.$atanh only accepts values between -1 and 1. The endpoints themselves are undefined.
| Question | Answer |
|---|---|
| Operator type | Aggregation expression operator (hyperbolic) |
| Syntax | { $atanh: <expression> } |
| Input range | Greater than -1 and less than 1 |
| Inverse of | $tanh |
| Common stages | $project, $addFields, $set |
{
$atanh: 0.5
}≈ 0.549
{
$atanh: -0.5
}≈ -0.549
{
$atanh: 0
}Returns 0
{
$atanh: null
}Returns null
Compute inverse hyperbolic tangent on sample values between -1 and 1, including positive, negative, and zero inputs.
Use a values collection and compute $atanh for each numeric field with $project.
Suppose you have a values collection with a numeric x field:
[
{ "_id": ObjectId("609c26812e9274a86871bc6a"), "x": 0.5 },
{ "_id": ObjectId("609c26812e9274a86871bc6b"), "x": 0.7 },
{ "_id": ObjectId("609c26812e9274a86871bc6c"), "x": 0.9 }
]Compute the inverse hyperbolic tangent for each value:
db.values.aggregate([
{
$project: {
x: 1,
inverseTanh: { $atanh: "$x" }
}
}
])atanh(0.5) ≈ 0.549.atanh(0.7) ≈ 0.867.atanh(0.9) ≈ 1.472 (values near 1 grow rapidly).Handle negative values, round results, and guard against out-of-range inputs.
$atanh is an odd function: atanh(-x) = -atanh(x):
db.values.aggregate([
{
$project: {
x: 1,
inverseTanh: { $atanh: "$x" },
inverseTanhRounded: {
$round: [ { $atanh: "$x" }, 3 ]
}
}
}
])
// Sample values: -0.5, 0, 0.5
// atanh(-0.5) ≈ -0.549
// atanh(0) = 0
// atanh(0.5) ≈ 0.549Negative inputs within (-1, 1) produce negative outputs. Use $round for cleaner display values.
The inverse hyperbolic tangent is used in statistics to transform correlation coefficients:
db.correlations.aggregate([
{
$project: {
pair: 1,
correlation: 1,
fisherZ: { $atanh: "$correlation" }
}
},
{
$group: {
_id: null,
avgFisherZ: { $avg: "$fisherZ" }
}
}
])Correlation values naturally fall between -1 and 1, making them ideal input for $atanh. The Fisher z-transform stabilizes variance before averaging.
Skip or flag values outside the valid domain before applying $atanh:
db.values.aggregate([
{
$project: {
x: 1,
inverseTanh: {
$cond: {
if: {
$and: [
{ $gt: ["$x", -1] },
{ $lt: ["$x", 1] }
]
},
then: { $atanh: "$x" },
else: null
}
}
}
}
])
// x: 0.5 → inverseTanh: 0.549 (valid)
// x: 1 → inverseTanh: null (guarded)
// x: 1.2 → inverseTanh: null (guarded)Use $cond with $gt and $lt to check the domain before calling $atanh. This prevents unexpected null or NaN results in production pipelines.
$tanh scaling step to recover original magnitudes.$atanh WorksThe pipeline evaluates the input — a field like "$x" or a numeric expression between -1 and 1.
MongoDB applies the inverse hyperbolic tangent function. Values outside (-1, 1) return null or NaN.
The computed value is written to the field you define in $project or $addFields.
Use the result for grouping, averaging, or further pipeline stages.
The $atanh operator is a useful hyperbolic math tool in MongoDB aggregation pipelines. It reverses $tanh scaling, supports the Fisher z-transform in statistics, and handles negative values naturally within its valid domain.
For beginners, remember: input must be between -1 and 1 (not including the endpoints), atanh(0) = 0, and do not confuse $atanh with the trigonometric $atan operator.
atanh(0) = 0 when checking results$round for readable output values$tanh to verify round-trip calculations$cond in production pipelines$atanh with $atan (different functions)$atanh as a query filter outside expressions$atanhUse these points when working with hyperbolic math in MongoDB.
Reverse of $tanh.
{ $atanh: expr }
Between -1 and 1.
Domainatanh(-x) = -atanh(x).
PropertyHyperbolic, not trig.
ImportantMove on to $binarySize or review $asinh for another hyperbolic inverse operator.
5 people found this page helpful