> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

<!--
Tab options on this page. Append to the .md URL to filter:
  ?tabs=<id,...>   select specific tabs (e.g. ?tabs=nodejs,shell)
  ?allTabs=true    include every tab
  (no param)       default: one tab per tabset

Available tabs:
  other tabs: degrees, radians
-->

# $atanh (expression operator)

Returns the inverse hyperbolic tangent (hyperbolic arc tangent) of a value.

[`$atanh`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/atanh.md#mongodb-expression-exp.-atanh) has the following syntax:

```javascript
{ $atanh: <expression> }
```

[`$atanh`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/atanh.md#mongodb-expression-exp.-atanh) takes any valid [expression](https://www.mongodb.com/docs/manual/reference/mql/expressions.md#std-label-aggregation-expressions) that resolves to a number  between `-1` and `1`, e.g. `-1 <= value <= 1`.

[`$atanh`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/atanh.md#mongodb-expression-exp.-atanh) returns values in radians. Use [`$radiansToDegrees`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/radianstodegrees.md#mongodb-expression-exp.-radiansToDegrees) operator to convert the output value from radians to degrees.

By default [`$atanh`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/atanh.md#mongodb-expression-exp.-atanh) returns values as a `double`. [`$atanh`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/atanh.md#mongodb-expression-exp.-atanh) can also return values as a [128-bit decimal](https://www.mongodb.com/docs/mongodb-shell/reference/data-types.md#std-label-shell-type-decimal) as long as the `<expression>` resolves to a 128-bit decimal value.

For more information on expressions, see [Expressions.](https://www.mongodb.com/docs/manual/reference/mql/expressions.md#std-label-aggregation-expressions)

## Behavior

### `null`, `NaN`, and `+/- Infinity`

If the argument resolves to a value of `null` or refers to a field that is missing, [`$atanh`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/atanh.md#mongodb-expression-exp.-atanh) returns `null`. If the argument resolves to `NaN`, [`$atanh`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/atanh.md#mongodb-expression-exp.-atanh) returns `NaN`. If the argument resolves to negative or positive infinity, [`$atanh`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/atanh.md#mongodb-expression-exp.-atanh) throws an error. If the argument resolves to `+1` or `-1`, [`$atanh`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/atanh.md#mongodb-expression-exp.-atanh) returns `Infinity` and `-Infinity` respectively.

| Example | Results |
| --- | --- |
| `{ $atanh: NaN }` | `NaN` |
| `{ $atanh: null }` | `null` |
| `{ $atanh: 1 }` | `Infinity` |
| `{ $atanh: -1}` | `-Infinity` |
| `{ $atanh : Infinity}` *or* `{ $atanh : -Infinity }` | Throws an error message resembling the following formatted output: `"errmsg" :
  "Failed to optimize pipeline :: caused by :: cannot
  apply $atanh to -inf, value must in (-inf,inf)"` |

## Example

### Inverse Hyperbolic Tangent in Degrees

The `trigonometry` collection contains a document that stores a value along the `x` axis of a 2-D graph:

```bash
{
  "_id" : ObjectId("5c50782193f833234ba90d85"),
  "x-coordinate" : Decimal128("0.5")
}
```

The following aggregation operation uses the [`$atanh`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/atanh.md#mongodb-expression-exp.-atanh) expression to calculate inverse hyperbolic tangent of `x-coordinate` and add it to the input document using the [`$addFields`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/addfields.md#mongodb-pipeline-pipe.-addFields) pipeline stage.

```bash
db.trigonometry.aggregate([
  {
    $addFields : {
      "y-coordinate" : {
        $radiansToDegrees : { $atanh : "$x-coordinate" }
      }
    }
  }
])
```

The [`$radiansToDegrees`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/radianstodegrees.md#mongodb-expression-exp.-radiansToDegrees) expression converts the radian value returned by [`$atanh`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/atanh.md#mongodb-expression-exp.-atanh) to the equivalent value in degrees.

The command returns the following output:

```bash
{
  "_id" : ObjectId("5c50782193f833234ba90d85"),
  "x-coordinate" : Decimal128("0.5"),
  "y-coordinate" : Decimal128("31.47292373094538001977241539068589")
}
```

Since `x-coordinate` is stored as a [128-bit decimal](https://www.mongodb.com/docs/mongodb-shell/reference/data-types.md#std-label-shell-type-decimal), the output of [`$atanh`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/atanh.md#mongodb-expression-exp.-atanh) is a 128-bit decimal.