### Get Charge Excess Strength Parameter 'a'

Source: https://context7.com/nu-radio/radiotools/llms.txt

Calculates the charge excess strength parameter 'a' based on the atmospheric density at Xmax. The density should be provided in kg/m^3.

```python
# Get charge excess strength parameter 'a' for density at Xmax
a = re.get_a(rho=0.5)  # density in kg/m^3
# Output: relative charge excess strength (~0.14 typical)
```

--------------------------------

### Get Average Atmospheric Density

Source: https://context7.com/nu-radio/radiotools/llms.txt

Retrieves the average atmospheric density at Xmax for a given shower zenith angle and Xmax value. Requires specifying the atmospheric model.

```python
import numpy as np
from radiotools.analyses import radiationenergy as re

# Get average atmospheric density at Xmax for a given zenith angle
zenith = np.deg2rad(45)
xmax = 750  # g/cm^2
density = re.get_average_density(model=17, zenith=zenith, xmax=xmax)
# Output: density in kg/m^3
```

--------------------------------

### coordinatesystems.cstrafo Class Initialization

Source: https://github.com/nu-radio/radiotools/blob/master/radiotools/doc/coordinatesystems.md

Initializes the `cstrafo` class with signal/air-shower direction and magnetic field configuration.

```APIDOC
## coordinatesystems.cstrafo

### Description
Class to perform coordinate transformations typically used in air shower radio detection.

### Method
__init__

### Parameters
#### Path Parameters
- **zenith** (float) - Required - Zenith angle of the incoming signal/air-shower direction (0 deg is pointing to the zenith).
- **azimuth** (float) - Required - Azimuth angle of the incoming signal/air-shower direction (0 deg is North, 90 deg is South).
- **magnetic_field_vector** (list[float] or tuple[float]) - Optional - The magnetic field vector in the cartesian ground coordinate system.
- **site** (str) - Optional - The site for which the magnetic field vector should be used. Currently, default values for the sites ‘auger’ and ‘arianna’ are available. If `magnetic_field_vector` is None, this argument is used to determine the default magnetic field vector.

### Request Example
```python
from radiotools import coordinatesystems

trafo = coordinatesystems.cstrafo(zenith=30.0, azimuth=45.0, site='auger')
```

### Response
#### Success Response (200)
- **cstrafo object** - An initialized `cstrafo` object.

#### Response Example
```python
# No direct response example, object is created in memory
```
```

--------------------------------

### Refractivity Integration with RefractivityTable

Source: https://context7.com/nu-radio/radiotools/llms.txt

Use RefractivityTable for efficient refractivity lookups and integration. Supports tabulated and numerical calculations for flat or curved atmospheres.

```python
import numpy as np
from radiotools.atmosphere.refractivity import RefractivityTable, get_refractivity_between_two_points_numerical
from radiotools.atmosphere import models as atm

# Create refractivity table for fast lookups
table = RefractivityTable(
    atm_model=17,
    refractivity_at_sea_level=312e-6,
    curved=True,  # Account for Earth curvature
    number_of_zenith_bins=1000
)

# Get refractivity at a given height
h = 5000  # meters
N = table.get_refractivity_for_height_tabulated(h)
# Output: N = n - 1 at height h

# Get integrated refractivity between two altitudes (flat atmosphere)
h1, h2 = 1400, 8000  # meters
N_int = table.get_refractivity_between_two_altitudes(h1, h2)
# Output: average refractivity along vertical path

# Get integrated refractivity between two 3D positions (curved atmosphere)
p1 = np.array([0, 0, 8000])  # Xmax position (meters)
p2 = np.array([150, 100, 1400])  # Antenna position
N_avg = table.get_refractivity_between_two_points_tabulated(p1, p2)
# Output: path-averaged refractivity

# Direct numerical calculation (slower but more accurate)
N_numerical = get_refractivity_between_two_points_numerical(
    p1, p2, atm_model=17, refractivity_at_sea_level=312e-6
)
```

--------------------------------

### Get Geomagnetic Field Vector

Source: https://context7.com/nu-radio/radiotools/llms.txt

Retrieves the magnetic field vector for specified detector sites. The output is an array [Bx, By, Bz] representing East, North, and vertical components in Gauss.

```python
import numpy as np
from radiotools import helper as hp

# Get magnetic field vector for a site (in Gauss)
B_auger = hp.get_magnetic_field_vector(site='auger')
B_lofar = hp.get_magnetic_field_vector(site='lofar')
B_southpole = hp.get_magnetic_field_vector(site='southpole')
# Output: array([Bx, By, Bz]) where x=East, y=North
```

--------------------------------

### Time Conversions (GPS/UTC/TAI)

Source: https://context7.com/nu-radio/radiotools/llms.txt

Utilities for converting between GPS, UTC, and TAI time systems, accounting for leap seconds. Includes conversions to and from datetime objects.

```python
from datetime import datetime
from radiotools import leapseconds
from radiotools import helper as hp

# Convert GPS seconds to datetime
gps_seconds = 1234567890
dt = hp.gps_to_datetime(gps_seconds)
# Output: datetime object in UTC

# Convert datetime to GPS seconds
dt = datetime(2023, 6, 15, 12, 0, 0)
gps = hp.datetime_to_gps(dt)
# Output: GPS seconds since Jan 6, 1980

# Direct UTC/TAI/GPS conversions
utc_time = datetime(2023, 6, 15, 12, 0, 0)

tai_time = leapseconds.utc_to_tai(utc_time)
# Output: TAI time (UTC + leap seconds)

gps_time = leapseconds.utc_to_gps(utc_time)
# Output: GPS time

# Convert back
utc_recovered = leapseconds.tai_to_utc(tai_time)
utc_from_gps = leapseconds.gps_to_utc(gps_time)

# Get TAI-UTC difference (leap seconds) for a given time
dTAI = leapseconds.dTAI_UTC_from_utc(utc_time)
# Output: timedelta with current leap second count
```

--------------------------------

### Statistical Functions

Source: https://context7.com/nu-radio/radiotools/llms.txt

Provides weighted statistics and binned analysis functions, including quantiles, mean, variance, and profile-like binning.

```python
import numpy as np
from radiotools import stats

# Weighted quantile calculation
data = np.random.randn(1000)
weights = np.abs(np.random.randn(1000))
q16 = stats.quantile_1d(data, weights, 0.16)
q84 = stats.quantile_1d(data, weights, 0.84)
med = stats.median(data, weights)
# Output: 16%, 84% quantiles and median

# Weighted mean and variance
mean, variance = stats.mean_and_variance(data, weights)

# Binned statistics (like ROOT TProfile)
x = np.random.uniform(0, 10, 500)
y = 2 * x + np.random.randn(500)
bins = np.linspace(0, 10, 11)

y_mean = stats.binned_mean(x, y, bins)
# Output: mean of y in each x bin

y_mean, y_var = stats.binned_mean_and_variance(x, y, bins)
# Output: mean and variance per bin

# Array midpoints helper
bin_centers = stats.mid(bins)
# Output: midpoints between bin edges
```

--------------------------------

### Unit Conversions (dB/Linear)

Source: https://context7.com/nu-radio/radiotools/llms.txt

Helper functions for converting between linear power ratios and decibel (dB) values. Supports scalar and array inputs.

```python
from radiotools import helper as hp
import numpy as np

# Convert linear power ratio to decibels
power_ratio = 100
dB_value = hp.linear_to_dB(power_ratio)
# Output: 20.0 dB

# Convert decibels to linear scale
dB_value = 30
linear = hp.dB_to_linear(dB_value)
# Output: 1000.0

# Works with arrays
powers = np.array([1, 10, 100, 1000])
dB_values = hp.linear_to_dB(powers)
# Output: array([0, 10, 20, 30])
```

--------------------------------

### Plotting Helpers for Histograms

Source: https://context7.com/nu-radio/radiotools/llms.txt

Utilities for creating publication-quality histograms with automatic statistics display using Matplotlib. Supports single and multiple histograms.

```python
import numpy as np
import matplotlib.pyplot as plt
from radiotools import plthelpers as ph

# Create histogram with statistics box
data = np.random.randn(1000) * 2 + 5
fig, ax = ph.get_histogram(
    data, bins=30,
    xlabel='Value', ylabel='Counts',
    title='Sample Distribution',
    stats=True
)
plt.show()

# Multiple histograms in grid
datasets = [np.random.randn(500) + i for i in range(4)]
fig, axes = ph.get_histograms(
    datasets, bins=20,
    xlabels=['Set 1', 'Set 2', 'Set 3', 'Set 4'],
    titles=['A', 'B', 'C', 'D'],
    stats=True
)
plt.tight_layout()
plt.show()
```

--------------------------------

### Spherical to Cartesian Conversions with radiotools.helper

Source: https://context7.com/nu-radio/radiotools/llms.txt

Helper functions for converting between spherical (zenith, azimuth) and Cartesian coordinates, and calculating angles between vectors. Essential for shower axis and vector calculations.

```python
import numpy as np
from radiotools import helper as hp

# Convert zenith/azimuth to Cartesian unit vector
zenith = np.deg2rad(30)
azimuth = np.deg2rad(45)
direction = hp.spherical_to_cartesian(zenith, azimuth)
# Output: array([x, y, z]) unit vector pointing in that direction

# Convert Cartesian vector to spherical coordinates
x, y, z = 0.5, 0.5, 0.707
zenith_out, azimuth_out = hp.cartesian_to_spherical(x, y, z)
# Output: zenith and azimuth angles in radians

# Calculate angle between two vectors
v1 = np.array([1, 0, 0])
v2 = np.array([0, 1, 0])
angle = hp.get_angle(v1, v2)
# Output: angle in radians (pi/2 for perpendicular vectors)

# Get zenith angle of a vector
zenith = hp.get_zenith(np.array([0.5, 0.5, 0.707]))
# Output: zenith angle in radians
```

--------------------------------

### Radiotools Coordinate Systems

Source: https://github.com/nu-radio/radiotools/blob/master/radiotools/doc/index.md

Documentation for coordinate system transformations within the radiotools library.

```APIDOC
## Radiotools Coordinate Systems

This section covers coordinate system transformations provided by the radiotools library.

### Module: coordinatesystems

- **cstrafo**: A function or class for coordinate system transformations. (Specific details not provided in the source text).
```

--------------------------------

### Atmospheric Models with radiotools.atmosphere

Source: https://context7.com/nu-radio/radiotools/llms.txt

Provides a 5-layer parametric atmosphere model compatible with CORSIKA/CoREAS, supporting flat and curved Earth approximations. Use to calculate atmospheric depth, vertical height, density, and refractive index.

```python
import numpy as np
from radiotools.atmosphere import models as atm

# Initialize atmosphere model (model 17 = US standard after Keilhauer)
atmosphere = atm.Atmosphere(model=17, curved=True)

# Get atmospheric depth along shower axis
zenith = np.deg2rad(60)
h_low = 1400  # observation level in meters
atm_depth = atmosphere.get_atmosphere(zenith, h_low=h_low, h_up=np.inf, observation_level=h_low)
# Output: atmospheric depth in g/cm^2

# Get vertical height for a given slant depth (e.g., Xmax)
xmax = 750  # g/cm^2
height = atmosphere.get_vertical_height(zenith, xmax, observation_level=1400)
# Output: height above sea level in meters

# Get geometric distance to Xmax
distance = atmosphere.get_distance_xmax_geometric(zenith, xmax=750, observation_level=1400)
# Output: distance to shower maximum in meters

# Calculate atmospheric density at Xmax
density = atmosphere.get_density(zenith, xmax=750, observation_level=1400)
# Output: density in g/m^3

# Get refractive index at a height
n = atmosphere.get_n(h=5000)  # height above sea level
# Output: refractive index (e.g., ~1.00025)

# Calculate viewing angle from observer to Xmax
viewing_angle = atmosphere.get_viewing_angle(zenith, r=150, xmax=750, observation_level=1400)
# Output: viewing angle in radians
```

--------------------------------

### Probability and Equality Checks

Source: https://github.com/nu-radio/radiotools/blob/master/radiotools/doc/helper.md

Functions for calculating 2D probability distributions and checking for equality between values.

```APIDOC
## GET /helper/get_2d_probability

### Description
Calculates the probability density for a 2D Gaussian distribution.

### Method
GET

### Endpoint
/helper/get_2d_probability

### Parameters
#### Query Parameters
- **x** (float) - Required - x-coordinate
- **y** (float) - Required - y-coordinate
- **xx** (float) - Required - Mean x-coordinate
- **yy** (float) - Required - Mean y-coordinate
- **xx_error** (float) - Required - Standard deviation in x
- **yy_error** (float) - Required - Standard deviation in y
- **xy_correlation** (float) - Required - Correlation coefficient between x and y
- **sigma** (bool) - Optional - If True, returns log probability, defaults to False

### Response
#### Success Response (200)
- **probability** (float) - The calculated probability density

### Response Example
```json
{
  "probability": 0.012
}
```
```

```APIDOC
## GET /helper/is_equal

### Description
Checks if two values are approximately equal within a given relative precision.

### Method
GET

### Endpoint
/helper/is_equal

### Parameters
#### Query Parameters
- **a** (float) - Required - First value
- **b** (float) - Required - Second value
- **rel_precision** (float) - Optional - Relative precision for comparison, defaults to 1e-05

### Response
#### Success Response (200)
- **result** (bool) - True if values are equal within precision, False otherwise

### Response Example
```json
{
  "result": true
}
```
```

```APIDOC
## GET /helper/has_same_direction

### Description
Checks if two directions (defined by zenith and azimuth) are the same within a given distance cut.

### Method
GET

### Endpoint
/helper/has_same_direction

### Parameters
#### Query Parameters
- **zenith1** (float) - Required - Zenith angle of the first direction
- **azimuth1** (float) - Required - Azimuth angle of the first direction
- **zenith2** (float) - Required - Zenith angle of the second direction
- **azimuth2** (float) - Required - Azimuth angle of the second direction
- **distancecut** (float) - Optional - Maximum angular distance for directions to be considered the same, defaults to 20

### Response
#### Success Response (200)
- **result** (bool) - True if directions are the same, False otherwise

### Response Example
```json
{
  "result": true
}
```
```

--------------------------------

### analyses.radiationenergy.get_average_density

Source: https://github.com/nu-radio/radiotools/blob/master/radiotools/doc/analyses.md

Calculates the average air density for a given atmospheric model, zenith angle, and shower maximum (xmax).

```APIDOC
## analyses.radiationenergy.get_average_density

### Description
get average density

### Method
GET

### Endpoint
/analyses/radiationenergy/average_density

### Parameters
#### Query Parameters
- **model** (int) - Optional - atmospheric model
- **zenith** (float) - Optional - zenith angle in radians
- **xmax** (float) - Optional - shower maximum in g/cm^2

### Response
#### Success Response (200)
- **density** (float) - air density for a mean xmax and zenith angle

#### Response Example
{
  "density": 0.7
}
```

--------------------------------

### analyses.radiationenergy.get_a

Source: https://github.com/nu-radio/radiotools/blob/master/radiotools/doc/analyses.md

Calculates the relative charge excess strength 'a' based on the density at shower maximum.

```APIDOC
## analyses.radiationenergy.get_a

### Description
get relative charge excess strength

### Method
GET

### Endpoint
/analyses/radiationenergy/a

### Parameters
#### Query Parameters
- **rho** (float) - Required - density at shower maximum in kg/m^3

### Response
#### Success Response (200)
- **a** (float) - relative charge excess strength a

#### Response Example
{
  "a": 0.1
}
```

--------------------------------

### Calculate Basic Cherenkov Angle

Source: https://context7.com/nu-radio/radiotools/llms.txt

Computes the basic Cherenkov angle directly from the refractive index 'n'. The result is in radians.

```python
# Basic Cherenkov angle from refractive index
n = 1.0002
theta_c = cr.cherenkov_angle(n)
# Output: arccos(1/n) in radians
```

--------------------------------

### Coordinate Transformation Methods

Source: https://github.com/nu-radio/radiotools/blob/master/radiotools/doc/coordinatesystems.md

Methods for transforming coordinates between different systems.

```APIDOC
## Coordinate Transformation Methods

### transform_from_ground_to_onsky

#### Description
Transforms coordinates from the ground system to the on-sky system (eR, eTheta, ePhi).

#### Method
GET

#### Endpoint
`/transform_from_ground_to_onsky`

#### Parameters
##### Query Parameters
- **positions** (list[list[float]] or list[tuple[float]]) - Required - A list of positions in the ground coordinate system.

#### Response
##### Success Response (200)
- **positions** (list[list[float]]) - A list of positions in the on-sky coordinate system (eR, eTheta, ePhi).

### transform_from_onsky_to_ground

#### Description
Transforms coordinates from the on-sky system (eR, eTheta, ePhi) to the ground system.

#### Method
GET

#### Endpoint
`/transform_from_onsky_to_ground`

#### Parameters
##### Query Parameters
- **positions** (list[list[float]] or list[tuple[float]]) - Required - A list of positions in the on-sky coordinate system (eR, eTheta, ePhi).

#### Response
##### Success Response (200)
- **positions** (list[list[float]]) - A list of positions in the ground coordinate system.

### transform_from_magnetic_to_geographic

#### Description
Transforms coordinates from the magnetic ground system to the geographic ground system.

#### Method
GET

#### Endpoint
`/transform_from_magnetic_to_geographic`

#### Parameters
##### Query Parameters
- **positions** (list[list[float]] or list[tuple[float]]) - Required - A list of positions in the magnetic ground coordinate system.

#### Response
##### Success Response (200)
- **positions** (list[list[float]]) - A list of positions in the geographic ground coordinate system.

### transform_from_geographic_to_magnetic

#### Description
Transforms coordinates from the geographic ground system to the magnetic ground system.

#### Method
GET

#### Endpoint
`/transform_from_geographic_to_magnetic`

#### Parameters
##### Query Parameters
- **positions** (list[list[float]] or list[tuple[float]]) - Required - A list of positions in the geographic ground coordinate system.

#### Response
##### Success Response (200)
- **positions** (list[list[float]]) - A list of positions in the magnetic ground coordinate system.

### transform_from_azimuth_to_geographic

#### Description
Transforms coordinates from azimuth-based ground system to the geographic ground system.

#### Method
GET

#### Endpoint
`/transform_from_azimuth_to_geographic`

#### Parameters
##### Query Parameters
- **positions** (list[list[float]] or list[tuple[float]]) - Required - A list of positions in the azimuth-based ground coordinate system.

#### Response
##### Success Response (200)
- **positions** (list[list[float]]) - A list of positions in the geographic ground coordinate system.

### transform_from_geographic_to_azimuth

#### Description
Transforms coordinates from the geographic ground system to the azimuth-based ground system.

#### Method
GET

#### Endpoint
`/transform_from_geographic_to_azimuth`

#### Parameters
##### Query Parameters
- **positions** (list[list[float]] or list[tuple[float]]) - Required - A list of positions in the geographic ground coordinate system.

#### Response
##### Success Response (200)
- **positions** (list[list[float]]) - A list of positions in the azimuth-based ground coordinate system.

### transform_from_early_late

#### Description
Transforms station positions back to the x,y,z Cartesian coordinate system from the early-late system.

#### Method
GET

#### Endpoint
`/transform_from_early_late`

#### Parameters
##### Query Parameters
- **positions** (list[list[float]] or list[tuple[float]]) - Required - A list of station positions in the early-late coordinate system.
- **core** (list[float] or tuple[float]) - Optional - The core position.

#### Response
##### Success Response (200)
- **positions** (list[list[float]]) - A list of station positions in the x,y,z Cartesian coordinate system.

### transform_to_early_late

#### Description
Transforms station positions into the shower plane system (early-late coordinates).

#### Method
GET

#### Endpoint
`/transform_to_early_late`

#### Parameters
##### Query Parameters
- **positions** (list[list[float]] or list[tuple[float]]) - Required - A list of station positions.
- **core** (list[float] or tuple[float]) - Optional - The core position.

#### Response
##### Success Response (200)
- **positions** (list[list[float]]) - A list of station positions in the shower plane system.

### transform_to_vxB_vxvxB

#### Description
Transforms station positions into the vxB, vxvxB shower plane coordinate system.

#### Method
GET

#### Endpoint
`/transform_to_vxB_vxvxB`

#### Parameters
##### Query Parameters
- **station_position** (list[list[float]] or list[tuple[float]]) - Required - A list of station positions.
- **core** (list[float] or tuple[float]) - Optional - The core position.

#### Response
##### Success Response (200)
- **positions** (list[list[float]]) - A list of station positions in the vxB, vxvxB shower plane coordinate system.

### transform_from_vxB_vxvxB

#### Description
Transforms station positions back to the x,y,z Cartesian coordinate system from the vxB, vxvxB shower plane system.

#### Method
GET

#### Endpoint
`/transform_from_vxB_vxvxB`

#### Parameters
##### Query Parameters
- **station_position** (list[list[float]] or list[tuple[float]]) - Required - A list of station positions in the vxB, vxvxB shower plane coordinate system.
- **core** (list[float] or tuple[float]) - Optional - The core position.

#### Response
##### Success Response (200)
- **positions** (list[list[float]]) - A list of station positions in the x,y,z Cartesian coordinate system.

### transform_from_vxB_vxvxB_2D

#### Description
Transforms station positions back to the x,y,z Cartesian coordinate system from the 2D vxB, vxvxB shower plane system.

#### Method
GET

#### Endpoint
`/transform_from_vxB_vxvxB_2D`

#### Parameters
##### Query Parameters
- **station_position** (list[list[float]] or list[tuple[float]]) - Required - A list of station positions in the 2D vxB, vxvxB shower plane coordinate system.
- **core** (list[float] or tuple[float]) - Optional - The core position.

#### Response
##### Success Response (200)
- **positions** (list[list[float]]) - A list of station positions in the x,y,z Cartesian coordinate system.

### transform_from_onsky_to_vxB_vxvxB

#### Description
Transforms a single trace or list of traces from on-sky coordinates (eR, eTheta, ePhi) to the vxB, vxvxB shower plane coordinate system.

#### Method
GET

#### Endpoint
`/transform_from_onsky_to_vxB_vxvxB`

#### Parameters
##### Query Parameters
- **trace** (list or object) - Required - A single trace or a list of traces in on-sky coordinates.

#### Response
##### Success Response (200)
- **traces** (list or object) - Traces transformed to the vxB, vxvxB shower plane coordinate system.

### transform_from_vxB_vxvxB_to_onsky

#### Description
Transforms a single trace or list of traces from vxB, vxvxB shower plane coordinates back to on-sky coordinates (eR, eTheta, ePhi).

#### Method
GET

#### Endpoint
`/transform_from_vxB_vxvxB_to_onsky`

#### Parameters
##### Query Parameters
- **trace** (list or object) - Required - A single trace or a list of traces in vxB, vxvxB shower plane coordinates.

#### Response
##### Success Response (200)
- **traces** (list or object) - Traces transformed back to on-sky coordinates.

### get_height_in_showerplane

#### Description
Calculates the height in the shower plane.

#### Method
GET

#### Endpoint
`/get_height_in_showerplane`

#### Parameters
##### Query Parameters
- **x** (float) - Required - x-coordinate.
- **y** (float) - Required - y-coordinate.

#### Response
##### Success Response (200)
- **height** (float) - The calculated height in the shower plane.

### get_euler_angles

#### Description
Retrieves the Euler angles.

#### Method
GET

#### Endpoint
`/get_euler_angles`

#### Response
##### Success Response (200)
- **euler_angles** (list[float]) - The Euler angles.

```

--------------------------------

### Radiotools Analyses

Source: https://github.com/nu-radio/radiotools/blob/master/radiotools/doc/index.md

Documentation for analysis tools within the radiotools library.

```APIDOC
## Radiotools Analyses

This section outlines the analysis tools available in the radiotools library.

### Analysis: Radiation Energy

- **radiation energy**: Details related to the analysis of radiation energy. (Specific details not provided in the source text).
```

--------------------------------

### helper.pretty_time_delta

Source: https://github.com/nu-radio/radiotools/blob/master/radiotools/doc/helper.md

Formats a time duration in seconds into a human-readable string.

```APIDOC
## helper.pretty_time_delta

### Description
Formats a time duration in seconds into a human-readable string.

### Method
Not specified (assumed function call)

### Endpoint
Not applicable (helper function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **formatted_time** (string) - The human-readable representation of the time duration.

#### Response Example
None
```

--------------------------------

### Cherenkov Radiation Calculations

Source: https://github.com/nu-radio/radiotools/blob/master/radiotools/doc/helper.md

Functions for calculating Cherenkov angles and ellipse parameters.

```APIDOC
## GET /helper/get_cherenkov_angle

### Description
Returns the Cherenkov angle for a given atmospheric density profile.

### Method
GET

### Endpoint
/helper/get_cherenkov_angle

### Parameters
#### Query Parameters
- **h** (float) - Required - Height above ground
- **model** (int) - Optional - Atmospheric model to use, defaults to 1

### Response
#### Success Response (200)
- **cherenkov_angle** (float) - The calculated Cherenkov angle in radians

### Response Example
```json
{
  "cherenkov_angle": 0.02
}
```
```

```APIDOC
## GET /helper/get_cherenkov_ellipse

### Description
Returns the major and minor axes of the Cherenkov cone projected onto the ground plane.

### Method
GET

### Endpoint
/helper/get_cherenkov_ellipse

### Parameters
#### Query Parameters
- **zenith** (float) - Required - Zenith angle of the shower axis
- **xmax** (float) - Required - Maximum shower development depth
- **model** (int) - Optional - Atmospheric model to use, defaults to 1

### Response
#### Success Response (200)
- **major_axis** (float) - The length of the major axis
- **minor_axis** (float) - The length of the minor axis

### Response Example
```json
{
  "major_axis": 500.0,
  "minor_axis": 450.0
}
```
```

--------------------------------

### Radiotools Helper Functions

Source: https://github.com/nu-radio/radiotools/blob/master/radiotools/doc/index.md

This section details the various mathematical and utility functions available in the radiotools.helper module.

```APIDOC
## Radiotools Helper Functions

This module contains a comprehensive set of helper functions for various calculations in radio astronomy.

### Functions

- **linear_to_dB()**: Converts linear scale values to decibels (dB).
- **dB_to_linear()**: Converts decibel (dB) values to linear scale.
- **gps_to_datetime()**: Converts GPS time to a datetime object.
- **datetime_to_gps()**: Converts a datetime object to GPS time.
- **GPS_to_UTC()**: Converts GPS time to UTC.
- **UTC_to_GPS()**: Converts UTC to GPS time.
- **datetime_to_UTC()**: Converts a datetime object to UTC.
- **get_local_zenith()**: Calculates the local zenith.
- **get_local_altitude()**: Calculates the local altitude.
- **get_local_zenith_angle()**: Calculates the local zenith angle.
- **get_intersection_between_circle_and_line()**: Finds the intersection points between a circle and a line.
- **get_zenith_angle_at_sea_level()**: Calculates the zenith angle at sea level.
- **spherical_to_cartesian()**: Converts spherical coordinates to Cartesian coordinates.
- **cartesian_to_spherical()**: Converts Cartesian coordinates to spherical coordinates.
- **get_angle()**: Calculates the angle between two vectors.
- **get_zenith()**: Calculates the zenith vector.
- **get_rotation()**: Calculates the rotation matrix.
- **get_normalized_angle()**: Normalizes an angle to a specific range.
- **get_declination()**: Calculates the declination.
- **get_magnetic_field_vector()**: Calculates the magnetic field vector.
- **get_angle_to_magnetic_field_vector()**: Calculates the angle to the magnetic field vector.
- **get_magneticfield_azimuth()**: Calculates the magnetic field azimuth.
- **get_inclination()**: Calculates the magnetic field inclination.
- **get_magneticfield_zenith()**: Calculates the magnetic field zenith.
- **get_magnetic_field_vector_from_inc()**: Calculates the magnetic field vector from inclination.
- **get_lorentzforce_vector()**: Calculates the Lorentz force vector.
- **get_sine_angle_to_lorentzforce()**: Calculates the sine of the angle to the Lorentz force.
- **get_chargeexcess_vector()**: Calculates the charge excess vector.
- **get_chargeexcess_correction_factor()**: Calculates the charge excess correction factor.
- **get_polarization_vector_max()**: Calculates the maximum polarization vector.
- **get_interval()**: Calculates the interval.
- **get_interval_hilbert()**: Calculates the interval using the Hilbert transform.
- **get_FWHM_hilbert()**: Calculates the Full Width at Half Maximum (FWHM) using the Hilbert transform.
- **get_polarization_vector_FWHM()**: Calculates the polarization vector FWHM.
- **get_expected_efield_vector()**: Calculates the expected electric field vector.
- **get_expected_efield_vector_vxB_vxvxB()**: Calculates the expected electric field vector in v x B and v x v x B coordinates.
- **get_angle_to_efieldexpectation_in_showerplane()**: Calculates the angle to the electric field expectation in the shower plane.
- **get_distance_to_showeraxis()**: Calculates the distance to the shower axis.
- **get_position_at_height()**: Calculates the position at a given height.
- **get_2d_probability()**: Calculates the 2D probability.
- **is_equal()**: Checks if two values are equal.
- **has_same_direction()**: Checks if two vectors have the same direction.
- **get_cherenkov_angle()**: Calculates the Cherenkov angle.
- **get_cherenkov_ellipse()**: Calculates the Cherenkov ellipse.
- **gaisser_hillas1_parametric()**: Implements the Gaisser-Hillas 1 parametric model.
- **gaisser_hillas()**: Implements the Gaisser-Hillas model.
- **is_confined()**: Checks if a value is confined within a range.
- **is_confined_weak()**: Checks for weak confinement.
- **in_hull()**: Checks if a point is inside a hull.
- **is_confined2()**: Checks for confinement in a 2D space.
- **get_efield_in_shower_plane()**: Calculates the electric field in the shower plane.
- **get_dirac_pulse()**: Generates a Dirac pulse.
- **rotate_vector_in_2d()**: Rotates a vector in 2D.
- **get_sd_core_error_ellipse()**: Calculates the shower detection core error ellipse.
- **transform_error_ellipse_into_vxB_vxvxB()**: Transforms an error ellipse into v x B and v x v x B coordinates.
- **is_in_quantile()**: Checks if a value is within a specified quantile.
- **get_ellipse_tangents_through_point()**: Finds the tangents to an ellipse passing through a point.
- **covariance_to_correlation()**: Converts a covariance matrix to a correlation matrix.
- **get_normalized_xcorr()**: Calculates the normalized cross-correlation.
- **linreg()**: Performs linear regression.
- **pretty_time_delta()**: Formats a time difference into a human-readable string.
- **FC_limits()**: Calculates F.C. limits.
```

--------------------------------

### Chi-squared Fitting with Line

Source: https://context7.com/nu-radio/radiotools/llms.txt

Performs a chi-squared fit for linear data and plots the fit results. Requires radiotools.plthelpers.fit_line and plot_fit_stats. Ensure x_data, y_data, and y_err are defined.

```python
from radiotools.plthelpers import fit_line, plot_fit_stats

popt, cov, chi2ndf, func = fit_line(x_data, y_data, y_err)
ax.plot(x_data, func(x_data), 'r-', label='Fit')
plot_fit_stats(ax, popt, cov, chi2ndf)
```

--------------------------------

### Calculate Cherenkov Radius from Depth

Source: https://context7.com/nu-radio/radiotools/llms.txt

Determines the Cherenkov cone radius at ground level from the shower maximum depth (Xmax), observer level, zenith angle, and atmospheric properties.

```python
# Calculate Cherenkov radius from shower maximum depth
zenith = np.deg2rad(45)
xmax = 750  # g/cm^2
obs_level = 1400  # meters
n0 = 1 + 292e-6

radius = cr.get_cherenkov_radius_from_depth(
    zenith, xmax, obs_level, n0, model=17
)
```

--------------------------------

### Coordinate System Transformations with cstrafo

Source: https://context7.com/nu-radio/radiotools/llms.txt

Performs coordinate transformations for air shower radio detection, including conversions to/from shower plane, on-sky, and magnetic/geographic systems. Initialize with shower direction and site.

```python
import numpy as np
from radiotools.coordinatesystems import cstrafo

# Initialize with shower direction (zenith and azimuth angles in radians)
zenith = np.deg2rad(45)  # 45 degrees from vertical
azimuth = np.deg2rad(90)  # Coming from East

# Create coordinate transformation object
cs = cstrafo(zenith, azimuth, site='auger')

# Transform ground coordinates (x=East, y=North, z=up) to vxB-vxvxB system
station_positions = np.array([[100, 200, 0], [150, -100, 0], [-50, 300, 0]])
vxB_positions = cs.transform_to_vxB_vxvxB(station_positions, core=np.array([0, 0, 0]))
# Output: array of positions in shower plane coordinates

# Transform electric field traces to on-sky coordinates (eR, eTheta, ePhi)
efield_ground = np.array([0.5, 0.3, 0.1])  # V/m in ground coordinates
efield_onsky = cs.transform_from_ground_to_onsky(efield_ground)
# Output: array([eR, eTheta, ePhi])

# Transform back from vxB-vxvxB to ground coordinates
ground_positions = cs.transform_from_vxB_vxvxB(vxB_positions, core=np.array([0, 0, 0]))

# Get height in shower plane for 2D position
height = cs.get_height_in_showerplane(x=100, y=200)
```

--------------------------------

### Conversion Functions

Source: https://github.com/nu-radio/radiotools/blob/master/radiotools/doc/helper.md

Functions for converting between different scales and time formats.

```APIDOC
## helper.linear_to_dB(linear)

### Description
Converts a quantity from linear units to the decibel scale.

### Method
N/A (Function)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
N/A

## helper.dB_to_linear(dB)

### Description
Converts a quantity from the decibel scale to linear units.

### Method
N/A (Function)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
N/A

## helper.gps_to_datetime(gps)

### Description
Converts GPS seconds to a Python datetime object, accounting for leap seconds.

### Method
N/A (Function)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
N/A

## helper.datetime_to_gps(date)

### Description
Converts a Python datetime object to GPS seconds.

### Method
N/A (Function)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
N/A

## helper.GPS_to_UTC(gps)

### Description
Converts GPS seconds to UTC time.

### Method
N/A (Function)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

## helper.UTC_to_GPS(utc)

### Description
Converts UTC time to GPS seconds.

### Method
N/A (Function)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

## helper.datetime_to_UTC(dt)

### Description
Converts a Python datetime object to UTC time.

### Method
N/A (Function)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

--------------------------------

### Calculate Energy Fluence for Multiple Antennas

Source: https://context7.com/nu-radio/radiotools/llms.txt

Computes energy fluence for multiple antennas, where input traces have a shape of (n_antennas x n_samples x 3 polarizations).

```python
# For multiple antennas (shape: n_antennas x n_samples x 3)
multi_traces = np.random.randn(10, n_samples, 3) * 1e-6
multi_times = np.tile(times, (10, 1))
multi_fluence = calculate_energy_fluence(multi_traces, multi_times)
# Output: array of 10 energy fluence values
```

--------------------------------

### Calculate Cherenkov Angle at Height

Source: https://context7.com/nu-radio/radiotools/llms.txt

Calculates the Cherenkov angle at a specific height above sea level using a specified atmospheric model and sea-level refractive index.

```python
import numpy as np
from radiotools.atmosphere import cherenkov_radius as cr
from radiotools.atmosphere import models as atm

# Calculate Cherenkov angle at a given height
height = 8000  # meters above sea level
n0 = 1 + 292e-6  # refractive index at sea level
angle = cr.get_cherenkov_angle(height, n0, model=17)
# Output: Cherenkov angle in radians (~1 degree)
```

--------------------------------

### Vector and Field Calculations

Source: https://github.com/nu-radio/radiotools/blob/master/radiotools/doc/helper.md

Functions for calculating magnetic field properties, Lorentz force, and related vectors.

```APIDOC
## GET /helper/get_inclination

### Description
Returns the inclination of a vector.

### Method
GET

### Endpoint
/helper/get_inclination

### Parameters
#### Query Parameters
- **magnetic_field_vector** (np.ndarray or list) - Required - Vector in cartesian coordinates

### Response
#### Success Response (200)
- **inclination** (float) - The inclination of the vector

### Response Example
```json
{
  "inclination": 0.5
}
```
```

```APIDOC
## GET /helper/get_magneticfield_zenith

### Description
Convert an inclination to a local zenith.

### Method
GET

### Endpoint
/helper/get_magneticfield_zenith

### Parameters
#### Query Parameters
- **magnetic_field_inclination** (float) - Required - The magnetic field inclination

### Response
#### Success Response (200)
- **zenith** (float) - The local zenith angle

### Response Example
```json
{
  "zenith": 1.2
}
```
```

```APIDOC
## GET /helper/get_magnetic_field_vector_from_inc

### Description
Get the magnetic field from its inclination and declination. Returns the (normalized) magnetic field direction from its inclination and declination.

### Method
GET

### Endpoint
/helper/get_magnetic_field_vector_from_inc

### Parameters
#### Query Parameters
- **inclination** (float) - Required - The inclination of the magnetic field
- **declination** (float) - Required - The declination of the magnetic field

### Response
#### Success Response (200)
- **magnetic_field_vector** (list) - The normalized magnetic field vector

### Response Example
```json
{
  "magnetic_field_vector": [0.1, 0.2, 0.9]
}
```
```

```APIDOC
## GET /helper/get_lorentzforce_vector

### Description
Calculates the Lorentz force vector.

### Method
GET

### Endpoint
/helper/get_lorentzforce_vector

### Parameters
#### Query Parameters
- **zenith** (float) - Required - Zenith angle
- **azimuth** (float) - Required - Azimuth angle
- **magnetic_field_vector** (list) - Optional - Magnetic field vector in cartesian coordinates

### Response
#### Success Response (200)
- **lorentzforce_vector** (list) - The calculated Lorentz force vector

### Response Example
```json
{
  "lorentzforce_vector": [0.5, -0.2, 0.1]
}
```
```