Dataset
Handling of processed AQG data
AQGDataCollection
Bases: AQGDataset
A sequence of processed AQG datasets one one location
Attributes:
| Name | Type | Description |
|---|---|---|
datasets |
list of AQGDataset List of processed datasets that make up the collection |
columns
property
List of data columns
comment
property
Comment text
duration
property
Total duration of measurement
h
property
Measurement reference height, in meters
metadata
property
Dataset metadata
meter
property
Instrument identifier
name
property
Dataset identifier
num_drops
property
Total number of drops
num_outliers
property
Number of drops marked as outliers
point
property
Measurement point identifier
syst_uncertainty
property
Systematic uncertainty of the instrument
temperature_columns
property
List of temperature data columns
time_span
property
Measurement start and end time
vgg
property
Vertical gravity gradient used for height transfer
adev(t0=None, t1=None, incl_outliers=False)
Calculate the Allan deviation
Note
The Allan deviation assumes a fixed-interval time series. AQG data is nominally in 540 ms intervals, but can have gaps due to calibrations. This calculation assumes an interval of 540 ms, i. e. the gaps are pulled together.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
t0
|
str | Timestamp
|
Start of time range for calculation. |
None
|
t1
|
str | Timestamp
|
End of time range for calculation. |
None
|
incl_outliers
|
bool
|
Include drops marked as outliers. |
False
|
Returns:
| Type | Description |
|---|---|
Series
|
Allan deviation. |
compare(g_ref, h=STANDARD_HEIGHT, incl_outliers=False)
Compare gravity time series to a reference function
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
g_ref
|
Series
|
Gravity reference function. |
required |
incl_outliers
|
bool
|
Include drops marked as outliers. |
False
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
Dataframe of AQG signal, reference and difference. |
full_g(h=STANDARD_HEIGHT, incl_outliers=False, **kwargs)
Full gravity signal
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
h
|
float
|
Transfer height. Pass None to use original height. |
STANDARD_HEIGHT
|
incl_outliers
|
bool
|
Include drops marked as outliers. |
False
|
Returns:
| Type | Description |
|---|---|
GravityTimeSeries
|
Time series of gravity values |
g(h=STANDARD_HEIGHT, incl_outliers=False, min_count=0.5, **kwargs)
Gravity signal resampled to 10 sec intervals
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
h
|
float
|
Height (in meters) to transfer gravity signal to using gravity gradient. |
STANDARD_HEIGHT
|
incl_outliers
|
bool
|
Include drops marked as outliers. |
False
|
min_count
|
bool
|
Minimum number of drops required in an interval to be valid. |
0.5
|
Returns:
| Type | Description |
|---|---|
GravityTimeSeries
|
Time series of gravity values. |
get(column)
Get a combined data column
get_statistics(t0=None, t1=None, h=STANDARD_HEIGHT, adev_threshold=3600, adev_wn_tau0=20.0, adev_wn_tau1=200.0, incl_outliers=False)
Compute several statistics of the dataset: SEM, SD_h, TAV, sensitivity.
Basically, these are different statistical measures for judging the instrument stability. For a detailed explanation, see Reich et al. [2026].
If t0 and t1 are unspecified (None), the entire time series is used.
If adev_wn_tau0 or adev_wn_tau1 is unspecified (None), automatically selected values from the get_adev_wn_range() method are used.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
t0
|
(str, Timestamp)
|
Start of time range. |
None
|
t1
|
(str, Timestamp)
|
End of time range. |
None
|
h
|
float
|
Transfer height, in meters. Pass None for original height. |
STANDARD_HEIGHT
|
adev_threshold
|
float
|
Threshold value (in sec) where to sampel the Allan Deviation for its current uncertainty value. |
3600
|
adev_wn_tau0
|
float
|
Start of averaging time range of white noise section of Allan Deviation (slope of -0.5 in log-log plot) |
20.0
|
adev_wn_tau1
|
float
|
End of averaging time range of white noise section of Allan Deviation (slope of -0.5 in log-log plot) |
200.0
|
incl_outliers
|
bool
|
Include drops marked as outliers. |
False
|
Returns:
| Name | Type | Description |
|---|---|---|
g_err_sem |
float
|
Standard error of the mean in nm/s². |
g_err_SDh |
float
|
Weighted standard deviation of hourly means in nm/s². |
g_err_TAV |
float
|
Threshold Allan Value (extracted at certain interval of the Allan Deviation Curve) in nm/s². |
sensitivity |
float
|
Instruments measurement sensitivity (related to measurement site quality/noise) in nm/s²/sqrt(Hz). |
mean(t0=None, t1=None, h=STANDARD_HEIGHT, incl_outliers=False)
Mean gravity value.
Note
Estimating the AQG's statistical error is not trivial because the signal does not follow a normal distribution. Moreover, the noise characteristic can depend on location. This procedure is intended as a standard workflow that errs on the side of overestimating the uncertainty.
The mean value is calculated from the unweighted mean of all accepted drops.
For the calculation of the statistical error, the full signal is first downsampled to 10 second intervals (see method g()) because the AQG signal does not show a normal distribution below this time scale.
For short measurements (< 2 hours), the statistical error is then calculated by the standard error of the mean (SEM) of the 10s-interval means.
For longer (> 2 hours) measurements, the AQG signal typically does not show a normal distribution anymore (flicker noise), so the SEM would be an underestimation. Instead, the statistical error is estimated from the standard deviation of 1 hour interval means, i. e. the error will not decrease with measurement duration.
If t0 and t1 are unspecified (None), the entire time series is
used.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
t0
|
(str, Timestamp)
|
Start of time range. |
None
|
t1
|
(str, Timestamp)
|
End of time range. |
None
|
h
|
float
|
Transfer height, in meters. Pass None for original height. |
STANDARD_HEIGHT
|
incl_outliers
|
bool
|
Include drops marked as outliers. |
False
|
Returns:
| Type | Description |
|---|---|
AbsGValue
|
Mean absolute gravity value. |
plot_adev(t0=None, t1=None, incl_outliers=False, sens=True, spec=True, ax=None, errors=True, **kwargs)
Plot of the Allan deviation
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
t0
|
str | Timestamp
|
Start of time range to select for calculation. |
None
|
t1
|
str | Timestamp
|
End of time range to select for calculation. |
None
|
incl_outliers
|
bool
|
Include drops marked as outliers. |
False
|
sens
|
bool
|
Plot estimated sensitivity. |
True
|
spec
|
bool
|
Plot sensitivity specification, to serve as visual reference. |
True
|
ax
|
Axes
|
Plot axes. |
None
|
errors
|
bool
|
Plot uncertainty bands. |
True
|
**kwargs
|
dict
|
Additional arguments to pass to |
{}
|
Returns:
| Type | Description |
|---|---|
Line2D
|
Plot line as returned by |
plot_full(t0=None, t1=None, height=None, incl_outliers=True, density=True, g0=None, ylim=(-2000, 2000), ax=None, **kwargs)
Plot full gravity time series
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
t0
|
str | Timestamp
|
Start of time range to select. |
None
|
t1
|
str | Timestamp
|
End of time range to select. |
None
|
height
|
float
|
Transfer height, in meters. Pass |
None
|
incl_outliers
|
bool
|
Include drops marked as outliers. |
True
|
density
|
bool
|
Visualize sample density. |
True
|
g0
|
float
|
Offset on y-axis. Pass |
None
|
ylim
|
tuple
|
Y-axis plot range, in nm/s². |
(-2000, 2000)
|
ax
|
Axes
|
Plot axes. |
None
|
**kwargs
|
dict
|
Additional arguments to pass to |
{}
|
Returns:
| Type | Description |
|---|---|
Line2D
|
Plot line as returned by |
AQGDataset
Processed AQG dataset
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ds
|
Dataset
|
Dataset of processed AQG data |
required |
columns
property
List of data columns
comment
property
Comment text
duration
property
Total duration of measurement
h
property
Measurement reference height, in meters
metadata
property
Metadata attributes
meter
property
Instrument identifier
name
property
Dataset identifier
num_drops
property
Total number of drops
num_outliers
property
Number of drops marked as outliers
point
property
Measurement point identifier
syst_uncertainty
property
Systematic uncertainty of the instrument
temperature_columns
property
List of temperature data columns
time_span
property
Measurement start and end time
vgg
property
Vertical gravity gradient used for height transfer
adev(t0=None, t1=None, incl_outliers=False)
Calculate the Allan deviation
Note
The Allan deviation assumes a fixed-interval time series. AQG data is nominally in 540 ms intervals, but can have gaps due to calibrations. This calculation assumes an interval of 540 ms, i. e. the gaps are pulled together.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
t0
|
str | Timestamp
|
Start of time range for calculation. |
None
|
t1
|
str | Timestamp
|
End of time range for calculation. |
None
|
incl_outliers
|
bool
|
Include drops marked as outliers. |
False
|
Returns:
| Type | Description |
|---|---|
Series
|
Allan deviation. |
compare(g_ref, h=STANDARD_HEIGHT, incl_outliers=False)
Compare gravity time series to a reference function
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
g_ref
|
Series
|
Gravity reference function. |
required |
incl_outliers
|
bool
|
Include drops marked as outliers. |
False
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
Dataframe of AQG signal, reference and difference. |
full_g(h=STANDARD_HEIGHT, incl_outliers=False, **kwargs)
Full gravity signal
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
h
|
float
|
Transfer height. Pass None to use original height. |
STANDARD_HEIGHT
|
incl_outliers
|
bool
|
Include drops marked as outliers. |
False
|
Returns:
| Type | Description |
|---|---|
GravityTimeSeries
|
Time series of gravity values |
g(h=STANDARD_HEIGHT, incl_outliers=False, min_count=0.5, **kwargs)
Gravity signal resampled to 10 sec intervals
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
h
|
float
|
Height (in meters) to transfer gravity signal to using gravity gradient. |
STANDARD_HEIGHT
|
incl_outliers
|
bool
|
Include drops marked as outliers. |
False
|
min_count
|
bool
|
Minimum number of drops required in an interval to be valid. |
0.5
|
Returns:
| Type | Description |
|---|---|
GravityTimeSeries
|
Time series of gravity values. |
get(column)
Retrieve a data column as Pandas series
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
column
|
str
|
Column name. |
required |
Returns:
| Type | Description |
|---|---|
Series
|
Time series. |
get_statistics(t0=None, t1=None, h=STANDARD_HEIGHT, adev_threshold=3600, adev_wn_tau0=20.0, adev_wn_tau1=200.0, incl_outliers=False)
Compute several statistics of the dataset: SEM, SD_h, TAV, sensitivity.
Basically, these are different statistical measures for judging the instrument stability. For a detailed explanation, see Reich et al. [2026].
If t0 and t1 are unspecified (None), the entire time series is used.
If adev_wn_tau0 or adev_wn_tau1 is unspecified (None), automatically selected values from the get_adev_wn_range() method are used.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
t0
|
(str, Timestamp)
|
Start of time range. |
None
|
t1
|
(str, Timestamp)
|
End of time range. |
None
|
h
|
float
|
Transfer height, in meters. Pass None for original height. |
STANDARD_HEIGHT
|
adev_threshold
|
float
|
Threshold value (in sec) where to sampel the Allan Deviation for its current uncertainty value. |
3600
|
adev_wn_tau0
|
float
|
Start of averaging time range of white noise section of Allan Deviation (slope of -0.5 in log-log plot) |
20.0
|
adev_wn_tau1
|
float
|
End of averaging time range of white noise section of Allan Deviation (slope of -0.5 in log-log plot) |
200.0
|
incl_outliers
|
bool
|
Include drops marked as outliers. |
False
|
Returns:
| Name | Type | Description |
|---|---|---|
g_err_sem |
float
|
Standard error of the mean in nm/s². |
g_err_SDh |
float
|
Weighted standard deviation of hourly means in nm/s². |
g_err_TAV |
float
|
Threshold Allan Value (extracted at certain interval of the Allan Deviation Curve) in nm/s². |
sensitivity |
float
|
Instruments measurement sensitivity (related to measurement site quality/noise) in nm/s²/sqrt(Hz). |
mean(t0=None, t1=None, h=STANDARD_HEIGHT, incl_outliers=False)
Mean gravity value.
Note
Estimating the AQG's statistical error is not trivial because the signal does not follow a normal distribution. Moreover, the noise characteristic can depend on location. This procedure is intended as a standard workflow that errs on the side of overestimating the uncertainty.
The mean value is calculated from the unweighted mean of all accepted drops.
For the calculation of the statistical error, the full signal is first downsampled to 10 second intervals (see method g()) because the AQG signal does not show a normal distribution below this time scale.
For short measurements (< 2 hours), the statistical error is then calculated by the standard error of the mean (SEM) of the 10s-interval means.
For longer (> 2 hours) measurements, the AQG signal typically does not show a normal distribution anymore (flicker noise), so the SEM would be an underestimation. Instead, the statistical error is estimated from the standard deviation of 1 hour interval means, i. e. the error will not decrease with measurement duration.
If t0 and t1 are unspecified (None), the entire time series is
used.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
t0
|
(str, Timestamp)
|
Start of time range. |
None
|
t1
|
(str, Timestamp)
|
End of time range. |
None
|
h
|
float
|
Transfer height, in meters. Pass None for original height. |
STANDARD_HEIGHT
|
incl_outliers
|
bool
|
Include drops marked as outliers. |
False
|
Returns:
| Type | Description |
|---|---|
AbsGValue
|
Mean absolute gravity value. |
plot_adev(t0=None, t1=None, incl_outliers=False, sens=True, spec=True, ax=None, errors=True, **kwargs)
Plot of the Allan deviation
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
t0
|
str | Timestamp
|
Start of time range to select for calculation. |
None
|
t1
|
str | Timestamp
|
End of time range to select for calculation. |
None
|
incl_outliers
|
bool
|
Include drops marked as outliers. |
False
|
sens
|
bool
|
Plot estimated sensitivity. |
True
|
spec
|
bool
|
Plot sensitivity specification, to serve as visual reference. |
True
|
ax
|
Axes
|
Plot axes. |
None
|
errors
|
bool
|
Plot uncertainty bands. |
True
|
**kwargs
|
dict
|
Additional arguments to pass to |
{}
|
Returns:
| Type | Description |
|---|---|
Line2D
|
Plot line as returned by |
plot_full(t0=None, t1=None, height=None, incl_outliers=True, density=True, g0=None, ylim=(-2000, 2000), ax=None, **kwargs)
Plot full gravity time series
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
t0
|
str | Timestamp
|
Start of time range to select. |
None
|
t1
|
str | Timestamp
|
End of time range to select. |
None
|
height
|
float
|
Transfer height, in meters. Pass |
None
|
incl_outliers
|
bool
|
Include drops marked as outliers. |
True
|
density
|
bool
|
Visualize sample density. |
True
|
g0
|
float
|
Offset on y-axis. Pass |
None
|
ylim
|
tuple
|
Y-axis plot range, in nm/s². |
(-2000, 2000)
|
ax
|
Axes
|
Plot axes. |
None
|
**kwargs
|
dict
|
Additional arguments to pass to |
{}
|
Returns:
| Type | Description |
|---|---|
Line2D
|
Plot line as returned by |
read_aqg_dataset(path)
Read processed AQG dataset from an .nc-file
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
(str, Path)
|
Path to .nc file. |
required |
Returns:
| Type | Description |
|---|---|
AQGDataset
|
|