Main Content

yumaread

Read data from YUMA almanac file

Since R2023a

collapse all in page

    Syntax

    data = yumaread(filename)
    data = yumaread(filename,GPSWeekEpoch=refdate)

    Description

    data = yumaread(filename) reads data from the YUMA almanac file specified by filename, and returns the parameters of each associated satellite as a timetable.

    example

    data = yumaread(filename,GPSWeekEpoch=refdate) specifies the reference date from which the YUMA almanac file counts the Global Positioning System (GPS) week number.

    Examples

    collapse all

    Open Live Script

    Download the YUMA almanac file from the NAVCEN website and parse it. Specify the date for which to download the file.

    d = datetime("today") - 2;

    Create the URL.

    baseURL = "https://www.navcen.uscg.gov/sites/default/files/gps/almanac/";
almanacType = "/yuma/";
almanacExtension = ".alm";
url = baseURL + d.Year + almanacType + num2str(day(d,"dayofyear"),'%03d') + ...
      almanacExtension;

    Specify a filename for the saved almanac file.

    filename = "yumaAlmanac" + "_" + d.Year + "-" + ...
           d.Month + "-" + d.Day + ".alm";

    Save the file.

    websave(filename,url);

    Get the orbital parameters from the downloaded YUMA almanac file.

    data = yumaread(filename)
    data=31×13 timetable
            Time            PRN    Health    Eccentricity    TimeOfApplicability    OrbitalInclination    RateOfRightAscen    SQRTA     RightAscenAtWeek    ArgumentOfPerigee    MeanAnom         Af0            Af1        Week
    ____________________    ___    ______    ____________    ___________________    __________________    ________________    ______    ________________    _________________    _________    ___________    ___________    ____

    27-Jan-2023 19:56:30     1       0          0.012259         5.0381e+05              0.98919            -7.6575e-09       5153.6         -1.7636             0.93699           -1.3324     0.00021935     -3.638e-12    2246
    27-Jan-2023 19:56:30     2       0          0.020082         5.0381e+05              0.96693            -7.8289e-09       5153.6           -1.86             -1.3346           -2.3153    -0.00062466      3.638e-12    2246
    27-Jan-2023 19:56:30     3       0          0.004446         5.0381e+05               0.9773            -7.8746e-09       5153.7        -0.73153              1.0233           -2.4793    -0.00036907      3.638e-12    2246
    27-Jan-2023 19:56:30     4       0         0.0022964         5.0381e+05              0.96264            -7.8975e-09       5153.7         0.34944             -3.0639           0.47758    -4.0054e-05      7.276e-12    2246
    27-Jan-2023 19:56:30     5       0         0.0057855         5.0381e+05               0.9643            -8.0232e-09       5153.5        -0.77652              1.1341            1.2373    -0.00011349              0    2246
    27-Jan-2023 19:56:30     6       0         0.0028877         5.0381e+05              0.98846            -7.6346e-09       5153.6         -1.7719            -0.86284           -1.0726     0.00056458      3.638e-12    2246
    27-Jan-2023 19:56:30     7       0          0.016655         5.0381e+05              0.95017            -7.8746e-09       5153.5          1.3653             -2.2286           -1.9321     0.00025177     -7.276e-12    2246
    27-Jan-2023 19:56:30     8       0         0.0082297         5.0381e+05              0.96065            -8.0803e-09       5153.6         -2.8518             0.20048           0.91139    -0.00010586     -3.638e-12    2246
    27-Jan-2023 19:56:30     9       0         0.0025482         5.0381e+05              0.95586            -7.9889e-09       5153.6         0.29373              1.9652            1.2322    -0.00022888      7.276e-12    2246
    27-Jan-2023 19:56:30    10       0         0.0084252         5.0381e+05              0.97706            -7.8746e-09       5153.6        -0.73421             -2.4529            2.8739    -2.1935e-05              0    2246
    27-Jan-2023 19:56:30    11       0        0.00078106         5.0381e+05              0.96453            -7.8746e-09       5153.7         -1.7278             -2.6895           0.14565    -8.8692e-05    -1.0914e-11    2246
    27-Jan-2023 19:56:30    12       0         0.0088811         5.0381e+05              0.96648            -8.0003e-09       5153.6            2.48              1.3307           -2.7255    -0.00033283     -3.638e-12    2246
    27-Jan-2023 19:56:30    13       0         0.0067534         5.0381e+05              0.96972            -7.8175e-09       5153.6         0.45204             0.94145           0.42546     0.00046635      7.276e-12    2246
    27-Jan-2023 19:56:30    14       0          0.002604         5.0381e+05              0.94981            -8.1489e-09       5153.6          2.4432             -3.0813           -2.6751    -4.0054e-05      7.276e-12    2246
    27-Jan-2023 19:56:30    15       0          0.014733         5.0381e+05              0.93207            -8.2861e-09       5153.6         0.17855              1.1759         -0.076497     8.5831e-06      3.638e-12    2246
    27-Jan-2023 19:56:30    16       0          0.013348         5.0381e+05              0.96625            -8.0003e-09       5153.7          2.4984             0.75825            1.7264    -0.00052261              0    2246
      ⋮
    Open Live Script

    Read GPS and QZSS navigation message data from a YUMA almanac file. 

    gpsQzssData = yumaread("qg2022309.alm");

    Get the satellite positions, velocities, and IDs at the specified time.

    t = datetime(2022,11,10,8,12,00);
[satPos,satVel,satID] = gnssconstellation(t,gpsQzssData,GNSSFileType="YUMA");

    Specify a GNSS receiver position in geodetic coordinates (latitude, longitude, and altitude).

    recPos = [35.67 139.73 50]; % Tokyo

    Get the azimuth and elevation look angles of the satellite positions for the specified receiver position. The isVis output indicates which satellites are visible. Find the total number of visible satellites by using nnz.

    [az,el,isVis] = lookangles(recPos,satPos);
fprintf('%d satellites visible at %s.\n',nnz(isVis),t);
    12 satellites visible at 10-Nov-2022 08:12:00.

    Specify the PRN as the label for each point. Specify the categorical groups.

    prn = gpsQzssData.PRN;
GPSPrn = (prn <= 32);
group = categorical(GPSPrn,[true false],["GPS" "QZSS"]);

    Visualize the visible satellites. Show the legend.

    skyplot(az(isVis),el(isVis),satID(isVis),GroupData=group(isVis))
legend("GPS","QZSS")

    Figure contains an object of type skyplot.

    Open Live Script

    Read a YUMA almanac file containing GPS and QZSS data, downloaded from the QZSS website.

    filenameQG = "qg2022309.alm";
dataQG = yumaread(filenameQG)
    dataQG=35×13 timetable
            Time            PRN    Health    Eccentricity    TimeOfApplicability    OrbitalInclination    RateOfRightAscen    SQRTA     RightAscenAtWeek    ArgumentOfPerigee    MeanAnom        Af0           Af1        Week
    ____________________    ___    ______    ____________    ___________________    __________________    ________________    ______    ________________    _________________    ________    ___________    __________    ____

    08-Nov-2022 16:50:54     1       0           0.01204         2.3347e+05              0.98919            -7.5089e-09       5153.6        -0.38418             0.94107          0.45277     0.00025463    -7.276e-12    2235
    08-Nov-2022 16:50:54     2       0           0.02012         2.3347e+05              0.96699            -7.7603e-09       5154.9        -0.47885             -1.3867         -0.44223    -0.00063896     3.638e-12    2235
    08-Nov-2022 16:50:54     3       0         0.0044513         2.3347e+05              0.97615            -7.5889e-09       5153.7         0.64757              1.0521         -0.66094    -0.00037193    -3.638e-12    2235
    08-Nov-2022 16:50:54     4       0         0.0021377         2.3347e+05              0.96147            -8.0232e-09       5153.7          1.7292             -3.1181           2.3566    -8.9645e-05     7.276e-12    2235
    08-Nov-2022 16:50:54     5       0         0.0059276         2.3347e+05               0.9632             -7.726e-09       5153.5         0.60365              1.1404           2.9734    -0.00010395             0    2235
    08-Nov-2022 16:50:54     6       0         0.0026011         2.3347e+05              0.98847            -7.5317e-09       5153.5        -0.39246            -0.91841            0.726     0.00051308    1.0914e-11    2235
    08-Nov-2022 16:50:54     7       0          0.016459         2.3347e+05              0.95087            -7.7375e-09       5153.6          2.7459             -2.2384         -0.16947     0.00028992    -3.638e-12    2235
    08-Nov-2022 16:50:54     8       0         0.0077338         2.3347e+05              0.96113            -8.3432e-09       5153.6         -1.4706             0.16515           2.7185    -9.2506e-05    -3.638e-12    2235
    08-Nov-2022 16:50:54     9       0         0.0026331         2.3347e+05              0.95461            -8.1032e-09       5153.7          1.6741              1.9245           3.0836     -0.0002718     7.276e-12    2235
    08-Nov-2022 16:50:54    10       0         0.0081372         2.3347e+05              0.97593            -7.5546e-09       5153.6         0.64487             -2.5026           -1.554    -1.1444e-05             0    2235
    08-Nov-2022 16:50:54    11       0        0.00080109         2.3347e+05               0.9645             -7.726e-09       5153.6        -0.34663             -2.9148            2.172    -3.7193e-05    -7.276e-12    2235
    08-Nov-2022 16:50:54    12       0         0.0085993         2.3347e+05              0.96761             -7.886e-09       5153.7         -2.4237              1.3193         -0.90595    -0.00030231    -3.638e-12    2235
    08-Nov-2022 16:50:54    13       0         0.0066509         2.3347e+05              0.96872            -7.9432e-09       5153.6          1.8313             0.95082           2.2082     0.00042057     7.276e-12    2235
    08-Nov-2022 16:50:54    14       0         0.0023918         2.3347e+05              0.95102            -8.0003e-09       5153.6         -2.4592             -3.0426          -0.9278    -8.5831e-05     3.638e-12    2235
    08-Nov-2022 16:50:54    15       0          0.014719         2.3347e+05               0.9307            -8.3661e-09       5153.6          1.5609               1.157           1.7184    -1.4305e-05     3.638e-12    2235
    08-Nov-2022 16:50:54    16       0          0.012957         2.3347e+05               0.9674            -7.9089e-09       5153.7         -2.4053             0.73788          -2.6905    -0.00052643             0    2235
      ⋮

    Extract GPS data from the timetable based on valid GPS PRNs between 1 and 32.

    GPSdata = dataQG((dataQG.PRN >= 1 & dataQG.PRN <= 32),:)
    GPSdata=31×13 timetable
            Time            PRN    Health    Eccentricity    TimeOfApplicability    OrbitalInclination    RateOfRightAscen    SQRTA     RightAscenAtWeek    ArgumentOfPerigee    MeanAnom        Af0           Af1        Week
    ____________________    ___    ______    ____________    ___________________    __________________    ________________    ______    ________________    _________________    ________    ___________    __________    ____

    08-Nov-2022 16:50:54     1       0           0.01204         2.3347e+05              0.98919            -7.5089e-09       5153.6        -0.38418             0.94107          0.45277     0.00025463    -7.276e-12    2235
    08-Nov-2022 16:50:54     2       0           0.02012         2.3347e+05              0.96699            -7.7603e-09       5154.9        -0.47885             -1.3867         -0.44223    -0.00063896     3.638e-12    2235
    08-Nov-2022 16:50:54     3       0         0.0044513         2.3347e+05              0.97615            -7.5889e-09       5153.7         0.64757              1.0521         -0.66094    -0.00037193    -3.638e-12    2235
    08-Nov-2022 16:50:54     4       0         0.0021377         2.3347e+05              0.96147            -8.0232e-09       5153.7          1.7292             -3.1181           2.3566    -8.9645e-05     7.276e-12    2235
    08-Nov-2022 16:50:54     5       0         0.0059276         2.3347e+05               0.9632             -7.726e-09       5153.5         0.60365              1.1404           2.9734    -0.00010395             0    2235
    08-Nov-2022 16:50:54     6       0         0.0026011         2.3347e+05              0.98847            -7.5317e-09       5153.5        -0.39246            -0.91841            0.726     0.00051308    1.0914e-11    2235
    08-Nov-2022 16:50:54     7       0          0.016459         2.3347e+05              0.95087            -7.7375e-09       5153.6          2.7459             -2.2384         -0.16947     0.00028992    -3.638e-12    2235
    08-Nov-2022 16:50:54     8       0         0.0077338         2.3347e+05              0.96113            -8.3432e-09       5153.6         -1.4706             0.16515           2.7185    -9.2506e-05    -3.638e-12    2235
    08-Nov-2022 16:50:54     9       0         0.0026331         2.3347e+05              0.95461            -8.1032e-09       5153.7          1.6741              1.9245           3.0836     -0.0002718     7.276e-12    2235
    08-Nov-2022 16:50:54    10       0         0.0081372         2.3347e+05              0.97593            -7.5546e-09       5153.6         0.64487             -2.5026           -1.554    -1.1444e-05             0    2235
    08-Nov-2022 16:50:54    11       0        0.00080109         2.3347e+05               0.9645             -7.726e-09       5153.6        -0.34663             -2.9148            2.172    -3.7193e-05    -7.276e-12    2235
    08-Nov-2022 16:50:54    12       0         0.0085993         2.3347e+05              0.96761             -7.886e-09       5153.7         -2.4237              1.3193         -0.90595    -0.00030231    -3.638e-12    2235
    08-Nov-2022 16:50:54    13       0         0.0066509         2.3347e+05              0.96872            -7.9432e-09       5153.6          1.8313             0.95082           2.2082     0.00042057     7.276e-12    2235
    08-Nov-2022 16:50:54    14       0         0.0023918         2.3347e+05              0.95102            -8.0003e-09       5153.6         -2.4592             -3.0426          -0.9278    -8.5831e-05     3.638e-12    2235
    08-Nov-2022 16:50:54    15       0          0.014719         2.3347e+05               0.9307            -8.3661e-09       5153.6          1.5609               1.157           1.7184    -1.4305e-05     3.638e-12    2235
    08-Nov-2022 16:50:54    16       0          0.012957         2.3347e+05               0.9674            -7.9089e-09       5153.7         -2.4053             0.73788          -2.6905    -0.00052643             0    2235
      ⋮

    Extract QZSS data from the timetable based on valid QZSS PRNs between 193 and 202.

    QZSSData = dataQG((dataQG.PRN >= 193 & dataQG.PRN <= 202),:)
    QZSSData=4×13 timetable
            Time            PRN    Health    Eccentricity    TimeOfApplicability    OrbitalInclination    RateOfRightAscen    SQRTA     RightAscenAtWeek    ArgumentOfPerigee    MeanAnom        Af0        Af1    Week
    ____________________    ___    ______    ____________    ___________________    __________________    ________________    ______    ________________    _________________    ________    ___________    ___    ____

    08-Nov-2022 08:53:02    194      0          0.076374          2.048e+05               0.72544            -2.343e-09       6492.9         -2.4966             -1.5847           2.5734              0     0     2235
    08-Nov-2022 08:53:02    195      0          0.074928          2.048e+05               0.71092           -2.3772e-09       6493.5        -0.78221             -1.5662           0.8499    -3.8147e-06     0     2235
    08-Nov-2022 08:53:02    196      0          0.074762          2.048e+05               0.60598            -3.383e-09       6493.2         0.94933              -1.559         -0.93973     0.00011253     0     2235
    08-Nov-2022 08:53:02    199      0        0.00022411          2.048e+05             0.0011924            1.0286e-09       6493.4          3.1171             0.38448           1.0834              0     0     2235
    Open Live Script

    Read GPS navigation message data from a YUMA almanac file.

    gpsData = yumaread("yumaAlmanac_2022-9-27.alm");

    Use the initial GPS timestamp from the almanac data to determine the absolute GPS times for each 60 second time step across 12 hours.

    startTime = gpsData.Time(1);
numHours = 12;
secondsPerHour = 3600;
dt = 60;
timeElapsed = 0:dt:(numHours*secondsPerHour);
t = startTime + seconds(timeElapsed);

    Specify a GNSS receiver position in geodetic coordinates (latitude, longitude, and altitude).

    recPos = [42 -71 50]; % Natick, MA

    Get the azimuth and elevation look angles for the positions of all satellites for the specified receiver position.

    numSats = numel(gpsData.PRN); % Number of satellites
[allAz,allEl] = deal(NaN(numel(t),numSats));
for i = 1:numel(t)
    [satPos,~,satID] = gnssconstellation(t(i),gpsData,GNSSFileType="YUMA");
    [az,el,vis] = lookangles(recPos,satPos);
    allAz(i,:) = az;
    allEl(i,:) = el;
end

    Mark all satellites below the horizon as NaN for no visibility.

    allEl(allEl < 0) = NaN;

    Visualize the trajectories of the satellites.

    figure
skyplot(allAz,allEl,satID)

    Figure contains an object of type skyplot.

    Animate the trajectories of the satellites.

    figure
sp = skyplot(allAz(1,:),allEl(1,:),satID);
for i = 1:size(allAz,1)
    set(sp,AzimuthData=allAz(1:i,:),ElevationData=allEl(1:i,:))
    drawnow
end

    Figure contains an object of type skyplot.

    Input Arguments

    collapse all

    YUMA almanac filename, specified as a string scalar or character vector. You can specify a relative or an absolute path, but if you specify only the filename itself, the function saves the file in the current working directory. The filename can also include a file extension.

    Example: "yumaAlmanac_2022-4-20.alm"

    Example: "mydir/yumaAlmanac_2022-4-20.alm"

    Example: "C:/mydir/yumaAlmanac_2022-4-20.alm"

    Data Types: char | string

    Reference date, specified as one of these valid datetime strings that coincide with the GPS week number rollover dates:

    • "06-Jan-1980"

    • "21-Aug-1999"

    • "06-Apr-2019"

    These dates occur every 1024 weeks, starting from January 6, 1980 at 00:00 (UTC). The default value is a datetime string that coincides with the most recent GPS week number rollover date before the current day.

    Example: GPSWeekEpoch="21-Aug-1999"

    Data Types: char | string

    Output Arguments

    collapse all

    Parameters of each satellite, returned as a timetable with a row for each record and a column for each parameter in that record.

    ParameterData TypeDescription
    Timedatetime

    GPS Time, calculated using Week and TimeOfApplicability.

    PRNdouble

    Satellite pseudorandom noise number.

    Healthdouble

    Satellite vehicle health data code.

    Eccentricitydouble

    Eccentricity of the orbit.

    TimeOfApplicabilitydouble

    Number of seconds since beginning of GPS week number.

    OrbitalInclinationdouble

    Inclination angle at reference time, in radians.

    RateOfRightAscendouble

    Rate of change in measurement of angle of right ascension, in radians per second.

    SQRTAdouble

    Square root of semimajor axis, in meters1/2.

    RightAscenAtWeekdouble

    Geographic longitude of orbital plane at weekly epoch, in radians.

    ArgumentOfPerigeedouble

    Angle from equator to perigee, in radians.

    MeanAnomdouble

    Angle from position of satellite in its orbit relative to perigee, in radians.

    Af0double

    Satellite almanac zeroth-order clock correction term, in seconds.

    Af1double

    Satellite almanac first order clock correction term, in seconds per second.

    Weekdouble

    GPS week number, continuous, not mod(1024).

    Tips

    • To download YUMA almanac files from the NAVCEN website for the current date, you must specify a date two days before the current date because the GPS time of applicability is approximately 70 hours later than the transmission time of the almanac data set. See the Read GPS Navigation Message Data from YUMA Almanac File example for more details.

    References

    [1] Science Applications International Corporation. NAVSTAR GPS Space Segment/Navigation User Interfaces. IS-GPS-200M. Los Angeles, CA: United States Space Force Space Systems Command, approved May 21, 2021. https://www.navcen.uscg.gov/sites/default/files/pdf/gps/IS_GPS_200M.pdf.

    [2] Science Applications International Corporation. NAVSTAR GPS Space Segment/Navigation User Interfaces. ICD-GPS-240D. Los Angeles, CA: United States Space Force Space Systems Command, approved May 21, 2021. https://www.navcen.uscg.gov/sites/default/files/pdf/gps/ICD_GPS_240D.pdf.

    [3] United States Coast Guard. "GPS Almanacs, NANUs, and OPS Advisories Archives." US Coast Guard Navigation Center. Accessed May 6, 2022. https://www.navcen.uscg.gov/archives.

    [4] Quasi-Zenith Satellite System(QZSS). "Satellite Positioning, Navigation and Timing Service." Accessed September 20, 2022. https://qzss.go.jp/en/technical/download/pdf/ps-is-qzss/is-qzss-pnt-004.pdf.

    [5] QZSS almanac archives, Quasi-Zenith Satellite System(QZSS). "QZSS (Quasi-Zenith Satellite System) - Cabinet Office (Japan)" Accessed September 20, 2022. https://sys.qzss.go.jp/dod/en/archives/pnt.html.

    Version History

    Introduced in R2023a

    See Also

    | | |