% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/load_data.R
\name{load_vmdb}
\alias{load_vmdb}
\alias{load_vmdb_rates}
\alias{load_vmdb_magnitudes}
\title{Loading visual meteor observations via the imo-vmdb 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{
\item{base_url}{character; base URL of the imo-vmdb API, e.g.
\code{"http://localhost:8000/api/v1"}.}

\item{shower}{character; selects by meteor shower codes.
\code{NA} loads sporadic meteors.}

\item{period}{selects an observation time range by minimum/maximum.
Accepts \code{POSIXct}, \code{Date}, or character.  Character
elements may be \code{"YYYY-MM-DDTHH:MM:SS"},
\code{"YYYY-MM-DD HH:MM:SS"}, or date-only \code{"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.}

\item{sl}{numeric; selects a range of solar longitudes by minimum/maximum.}

\item{lim_magn}{numeric; selects a range of limiting magnitudes by
minimum/maximum.}

\item{sun_alt_max}{numeric; selects the maximum altitude of the sun
(rates only).}

\item{moon_alt_max}{numeric; selects the maximum altitude of the moon
(rates only).}

\item{session_id}{integer; selects by session ids.}

\item{rate_id}{integer; selects rate observations by ids.}

\item{with_sessions}{logical; if \code{TRUE}, also load the corresponding
session data.}

\item{with_magnitudes}{logical; if \code{TRUE}, also load the corresponding
magnitude observations.}

\item{magn_id}{integer; selects magnitude observations by ids.}
}
\value{
Both functions return a list, with

\tabular{ll}{
\code{observations} \tab data frame, rate or magnitude observations,\cr
\code{sessions} \tab data frame; session data of observations,\cr
\code{magnitudes} \tab table; contingency table of meteor magnitude
frequencies.
}

\code{observations} depends on the function call.
\code{load_vmdb_rates} returns a data frame with columns:

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

\code{load_vmdb_magnitudes} returns an \code{observations} data frame with:

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

The \code{sessions} data frame contains

\tabular{ll}{
\code{session_id} \tab unique identifier of the session,\cr
\code{longitude} \tab location's longitude,\cr
\code{latitude} \tab location's latitude,\cr
\code{elevation} \tab height above mean sea level in km,\cr
\code{country} \tab country name,\cr
\code{location_name} \tab location name,\cr
\code{observer_id} \tab observer id (optional),\cr
\code{observer_name} \tab observer name (optional).
}

\code{magnitudes} is a contingency table of meteor magnitude frequencies.
Row names are magnitude observation IDs; column names are magnitude classes.
}
\description{
Loads visual meteor observations from an
\href{https://pypi.org/project/imo-vmdb/}{imo-vmdb} web server via its
REST API.
}
\details{
\code{sl}, \code{period} and \code{lim_magn} expect a vector with
successive minimum and maximum values.
\code{sun_alt_max} and \code{moon_alt_max} are expected to be scalar values.

\strong{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 \code{period}, \code{sl}, or \code{lim_magn}, flatten
them to a single min/max pair or issue multiple calls and combine with
\code{rbind()}.
}
\note{
Angle values are expected and returned in degrees.
}
\examples{
\dontrun{
# 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")
)
}
}
\references{
\url{https://pypi.org/project/imo-vmdb/}
}
