load_vmdb: Loading visual meteor observations via the imo-vmdb REST API
In vismeteor: Analysis of Visual Meteor Data

load_vmdb

R Documentation

Loading visual meteor observations via the imo-vmdb REST API

Description

Loads visual meteor observations from an imo-vmdb web server via its REST API.

Usage

load_vmdb_rates(
  base_url,
  shower = NULL,
  period = NULL,
  sl = NULL,
  lim_magn = NULL,
  sun_alt_max = NULL,
  moon_alt_max = NULL,
  session_id = NULL,
  rate_id = NULL,
  with_sessions = FALSE,
  with_magnitudes = FALSE
)

load_vmdb_magnitudes(
  base_url,
  shower = NULL,
  period = NULL,
  sl = NULL,
  lim_magn = NULL,
  session_id = NULL,
  magn_id = NULL,
  with_sessions = FALSE,
  with_magnitudes = TRUE
)

Arguments

`base_url`	character; base URL of the imo-vmdb API, e.g. `"http://localhost:8000/api/v1"`.
`shower`	character; selects by meteor shower codes. `NA` loads sporadic meteors.
`period`	selects an observation time range by minimum/maximum. Accepts `POSIXct`, `Date`, or character. Character elements may be `"YYYY-MM-DDTHH:MM:SS"`, `"YYYY-MM-DD HH:MM:SS"`, or date-only `"YYYY-MM-DD"`. Date-only inputs are expanded to midnight (lower bound) and 23:59:59 (upper bound) of the given day, in UTC. IMO data is UTC by convention; the timezone marker is omitted on the wire.
`sl`	numeric; selects a range of solar longitudes by minimum/maximum.
`lim_magn`	numeric; selects a range of limiting magnitudes by minimum/maximum.
`sun_alt_max`	numeric; selects the maximum altitude of the sun (rates only).
`moon_alt_max`	numeric; selects the maximum altitude of the moon (rates only).
`session_id`	integer; selects by session ids.
`rate_id`	integer; selects rate observations by ids.
`with_sessions`	logical; if `TRUE`, also load the corresponding session data.
`with_magnitudes`	logical; if `TRUE`, also load the corresponding magnitude observations.
`magn_id`	integer; selects magnitude observations by ids.

Details

sl, period and lim_magn expect a vector with successive minimum and maximum values. sun_alt_max and moon_alt_max are expected to be scalar values.

Note: Unlike the previous DBI-based version, only a single range per filter parameter is supported. If you previously passed a matrix with multiple rows to period, sl, or lim_magn, flatten them to a single min/max pair or issue multiple calls and combine with rbind().

Value

Both functions return a list, with

`observations`	data frame, rate or magnitude observations,
`sessions`	data frame; session data of observations,
`magnitudes`	table; contingency table of meteor magnitude frequencies.

observations depends on the function call. load_vmdb_rates returns a data frame with columns:

`rate_id`	unique identifier of the rate observation,
`shower`	IAU code of the shower. `NA` for sporadic.
`period_start`	`POSIXct` (UTC); start of observation,
`period_end`	`POSIXct` (UTC); end of observation,
`sl_start`	solar longitude at start,
`sl_end`	solar longitude at end,
`session_id`	reference to the session,
`freq`	count of observed meteors,
`lim_magn`	limiting magnitude,
`t_eff`	net observed time in hours,
`f`	correction factor of cloud cover,
`sidereal_time`	sidereal time,
`sun_alt`	altitude of the sun,
`sun_az`	azimuth of the sun,
`moon_alt`	altitude of the moon,
`moon_az`	azimuth of the moon,
`moon_illum`	illumination of the moon (`0.0 .. 1.0`),
`field_alt`	altitude of the field of view (optional),
`field_az`	azimuth of the field of view (optional),
`rad_alt`	altitude of the radiant (optional),
`rad_az`	azimuth of the radiant (optional),
`magn_id`	reference to the magnitude observations (optional),
`magn_solo`	`TRUE` if this rate is the sole contributor to its linked magnitude observation; `FALSE` if the magnitude aggregates this rate with others; `NA` when `magn_id` is `NA` (optional).

load_vmdb_magnitudes returns an observations data frame with:

`magn_id`	unique identifier of the magnitude observation,
`shower`	IAU code of the shower. `NA` for sporadic.
`period_start`	`POSIXct` (UTC); start of observation,
`period_end`	`POSIXct` (UTC); end of observation,
`sl_start`	solar longitude at start,
`sl_end`	solar longitude at end,
`session_id`	reference to the session,
`freq`	count of observed meteors,
`magn_mean`	mean magnitude,
`lim_magn`	limiting magnitude (optional).

The sessions data frame contains

`session_id`	unique identifier of the session,
`longitude`	location's longitude,
`latitude`	location's latitude,
`elevation`	height above mean sea level in km,
`country`	country name,
`location_name`	location name,
`observer_id`	observer id (optional),
`observer_name`	observer name (optional).

magnitudes is a contingency table of meteor magnitude frequencies. Row names are magnitude observation IDs; column names are magnitude classes.

Note

Angle values are expected and returned in degrees.

References

https://pypi.org/project/imo-vmdb/

Examples

## Not run: 
# Load rate observations including session and magnitude data
data <- load_vmdb_rates(
    base_url       = "http://localhost:8000/api/v1",
    shower         = "PER",
    sl             = c(135.5, 145.5),
    period         = c("2015-08-01", "2015-08-31"),
    lim_magn       = c(5.3, 6.7),
    with_magnitudes = TRUE,
    with_sessions   = TRUE
)

# Load magnitude observations
data <- load_vmdb_magnitudes(
    base_url     = "http://localhost:8000/api/v1",
    shower       = "PER",
    sl           = c(135.5, 145.5),
    period       = c("2015-08-01", "2015-08-31"),
    lim_magn     = c(5.3, 6.7),
    with_sessions = TRUE
)

# Period can also be given as POSIXct or as full ISO 8601 datetime
# strings — useful for narrowing to a specific time window within a day.
data <- load_vmdb_rates(
    base_url = "http://localhost:8000/api/v1",
    shower   = "PER",
    period   = c("2015-08-12T20:00:00", "2015-08-13T04:00:00")
)

## End(Not run)

vismeteor documentation built on May 20, 2026, 1:07 a.m.