CVS: phpweather/docs/src/latex decoded.tex,NONE,1.1

[Martin G. <gim...@us...>]

Update of /cvsroot/phpweather/phpweather/docs/src/latex
In directory usw-pr-cvs1:/tmp/cvs-serv2613

Added Files:
	decoded.tex 
Log Message:
A description of the decoded METAR array.


--- NEW FILE ---

\chapter{The Decoded METAR}

When \pw has fetched a METAR is has to decode it before you can use it
for anything interesting. This is done as needed when you call the
\func{pretty_print} method or if you call the \func{decode_metar}
method explicitly.

\section{Structure of the Decoded METAR Array}

The return value of the \func{decode_metar} method is an array that
contains the decoded METAR. The array is a multidimensional
associative array, which means that each key either refers to a value
or to another associative array.

If the METAR lacks a given part, then the corresponding entry in the
array will be left out. This means, that you'll have to check each
entry with \func{empty} before you use it, otherwise you see warnings
from PHP, if you've set the error reporting level high enough.

The following entries is always part of a METAR report, and is
therefore always part of the decoded METAR array:
\begin{description}

\item[\code{type}] This can either be \code{METAR} or \code{SPECI} and
  denotes the type of the report. This isn't used for anything.

\item[\code{metar}] The raw METAR report.

\item[\code{icao}] The ICAO of the station which made the report.

\item[\code{location}] The English name of the station.

\item[\code{time}] A UNIX timestamp corresponding to the time of the
  report.

\end{description}

The following entries are optional:
\begin{description}
\item[\code{report_mod}] A report modifier which gives information
  about how the report was made: \code{AUTO} for a fully automated
  report with no human intervention or \code{COR} for a corrected
  report. It's supposed to be part of all METARs, but experience shows
  that it's not.

\item[\code{wind}] This is an array with information about the wind.
  The \code{deg} entry tells you the direction of the wind as
  compass-direction. If the wind came from variable directions, then
  will be the string \code{VRB}.

  The \code{meters_per_second}, \code{miles_per_hour}, and
  \code{knots} entries tells you the wind speed in various units.

  If gust was observer, there will be three extra entries:
  \code{gust_meters_per_second}, \code{gust_miles_per_hour}, and
  \code{gust_knots}.

  If the wind was varying, then two extra entries are present:
  \code{var_beg} and \code{var_end}. Both of these entries contain a
  compass-direction

\item[\code{visibility}] This is an array with visibility information.
  Each entry in the array is a separate visibility group.

  Each visibility group contains a \code{prefix} which can be
  \code{-1}, \code{0}, or \code{1} which tells you if the visibility
  reported is ``less than'', ``normal'', or ``greater than''
  respectively.

  The visibility itself is stored in the \code{meter}, \code{km},
  \code{ft}, and \code{miles} entries. There is an optional entry
  \code{dir} for a direction --- if there's no direction, then the
  visibility refers to the overall visibility.

\item[\code{runway}] This is an array of runway groups. Each entry is
  a separate group.

  The groups contain an \code{nr} entry and an optional
  \code{approach} entry which tells you the runway-number and the
  approach respectively. The approach is one of \code{L}, \code{C}, or
  \code{R} for ``left'', ``center'', or ``right'' respectively.

  The visibility information can either be a single value or a pair of
  values in case of varying conditions. If there's only a single
  value, then \code{meter} and \code{ft} holds the visibility, an
  optional \code{prefix} can be \code{-1} if range is less than the
  lowest reportable value or \code{1} if greater than the greatest
  reportable value. A \code{tendency} entry holds either \code{D},
  \code{N} or \code{U} for ``downward tendency'', ``no distinct
  tendency'', or ``upward tendency'' respectively. (Why can't I find
  this information any longer in Chapter 12 of the Federal
  Meteorological Handbook No.~1?)

\item[\code{weather}] This holds the current weather phenomena and is
  one of the most interesting groups. It's an array of weather groups.

  Each group contains a \code{proximity} entry which can be either
  \code{VC} for phenomena in the vicinity or the empty string
  otherwise.

  Next comes the \code{intensity}. This can be \code{-} for light
  phenomena, the empty string for moderate phenomena, or \code{+} for
  heavy phenomena.

  This is followed by a \code{descriptor}, a \code{precipitation}, a
  \code{obscuration}, and finally a \code{other} entry. These entries
  contain the actual data found in the METAR. This means that it's up
  to the application to decode these symbols further, so that
  \code{RA} becomes ``rain'' and so on.

\item[\code{clouds}] This is an array of cloud groups. Each group has
  a \code{condition} entry which can be either \code{CAVOK} for no
  clouds and no significant weather, \code{VV} for ``vertical
  visibility'', \code{FEW} for ``few clouds'', \code{SCT} for
  ``scattered clouds'', \code{BKN} for ``broken clouds'', \code{OVC}
  for ``overcast'', and \code{SKC} and \code{CLR} for ``clear sky''.
  The condition \code{CAVOK} is a bit special, because if it's
  present, then the \code{condition} entry will be the only entry in
  the cloud group.

  The other conditions will be part of a larger array with an optional
  \code{cumulus} entry denoting the presence of cumulonimbus
  (\code{CB}) or towering cumulus (\code{TCU}) clouds. There will also
  be \code{meter} and \code{ft} entries with the height of the clouds.
  If the clouds are below the station, then the height will be stored
  as \code{nil}. Theres an optional \code{prefix} with the usual
  meaning.

  \item[\code{temperature}] This is the temperature group. It's an
  array with two or four entries: \code{temp_c} and \code{temp_f} is
  always present and is the temperature in degrees Celsius and
  Fahrenheit respectively. If information about the dew-point is
  present, then \code{dew_c} and \code{dew_f} will be added to the
  array.
  
  \item[\code{temp_min_max}] Some stations report the minimum and
  maximum temperature over various timescales. The temperatures are
  stored in \code{min6h_c}, \code{min6h_f}, \code{max6h_c} and
  \code{max6h_f} for the temperatures in the last 6~hours, and in
  \code{min24h_c}, \code{min24h_f}, \code{max24h_c} and
  \code{max24h_f} for the temperatures in the last 24~hours

  \item[\code{altimeter}] This is the air pressure measured in various
  units. The array has these entries: \code{inhg}, \code{mmhg},
  \code{hpa}, and \code{atm}.

  \item[\code{precipitation}] This is an array which stores the
  precipitation measured over various timescales. The entries
  \code{mm} and \code{in} contains the precipitation during the last
  hour, entries \code{mm_h6} and \code{in_6h} store the amount of
  precipitation in the last 3--6~hours and finally there's
  \code{mm_24h} and \code{in_24h} with the precipitation measured over
  the last 24~hours. If there has been snowfall, then that will be
  reported in the \code{snow_mm} and \code{snow_in} entries.

  All the entries can contain the special value \code{-1} which means
  that there was only a trace of precipitation.

\item[\code{remarks}] Anything which isn't recognized is added to this
  entry.


\end{description}