yumaread

Read data from YUMA almanac file

Since R2023a

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.

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

Examples

Read GPS Navigation Message Data from YUMA Almanac File

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
      ⋮

View Satellite Positions Visible from Receiver Position Using YUMA Almanac File

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")

Extract GPS and QZSS Data from YUMA Almanac File

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

Plot Trajectories of Satellites over Time from YUMA Almanac File

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)

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

Input Arguments

filename — YUMA almanac filename

string scalar | character vector

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

refdate — Reference date

"06-Jan-1980" | "21-Aug-1999" | "06-Apr-2019"

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

data — Parameters of each satellite

timetable

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

Parameter	Data Type	Description
Time	datetime	GPS Time, calculated using Week and TimeOfApplicability.
PRN	double	Satellite pseudorandom noise number.
Health	double	Satellite vehicle health data code.
Eccentricity	double	Eccentricity of the orbit.
TimeOfApplicability	double	Number of seconds since beginning of GPS week number.
OrbitalInclination	double	Inclination angle at reference time, in radians.
RateOfRightAscen	double	Rate of change in measurement of angle of right ascension, in radians per second.
SQRTA	double	Square root of semimajor axis, in meters1/2.
RightAscenAtWeek	double	Geographic longitude of orbital plane at weekly epoch, in radians.
ArgumentOfPerigee	double	Angle from equator to perigee, in radians.
MeanAnom	double	Angle from position of satellite in its orbit relative to perigee, in radians.
Af0	double	Satellite almanac zeroth-order clock correction term, in seconds.
Af1	double	Satellite almanac first order clock correction term, in seconds per second.
Week	double	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