You downloaded this. Here is what it is.

First, the unit you are holding

One file is a slice, not a dataset

A dataset is the record. A granule is one file out of it. Almost every confusing thing about Earthdata follows from that distinction.

NASA does not hand you a dataset. It hands you granules — the smallest slice it is willing to distribute. Download a year of this product and you have 87,600 files that are individually meaningless and collectively a scientific record.

This is the first thing that trips people up. You go looking for data and you get a file with a name like the one above, which is one slice out of a record running for years. The collection identifier names the whole record; the granule is one slice of it.

Second, the container

What kind of file is this, really?

HDF5, netCDF-4, HDF4 and GeoTIFF are containers, not data. Which one you have decides which software will open it.

The file extension is a label someone typed. It is not enforced by anything, and renaming a file does not change what is inside it. So the honest first question is: what container is this actually written in, and what will open it?

Third, and most important

This is a pass, not a map

Level 1 means the data is still organised the way the instrument collected it. That shapes everything you can and cannot do with it.

Here is the idea that changes how you read every array in this file.

This is not a map. It is a record of one pass, laid out the way the instrument scanned it.

The satellite orbits pole to pole while the Earth turns underneath. A mirror sweeps side to side, and each sweep writes one row into the array. So the rows are consecutive sweeps and the columns are positions along a sweep. Neither axis is latitude and neither is longitude. The strip of ground this traces out is called a swath, and it is curved, tilted, and different on every orbit.

NASA labels how far a product has travelled from the raw signal. The number appears in the filename of almost every Earthdata product, and it is the fastest way to know what you are dealing with.

The practical consequence is that this file has to carry a latitude and a longitude for every single pixel, as two full-size arrays. A gridded product gets away with two short vectors — one list of latitudes, one of longitudes — because its geometry is regular. Here there is no regularity to exploit and no vector that could describe it.

It also means you cannot crop by index to get a region. Rows near the top of the array might be over Greenland or over the Pacific depending on the orbit. To find your area of interest you have to search the coordinate arrays themselves, or use the archive’s spatial search before you download anything.

Fourth, how it was made

Your file shows its working

Every array in here is the output of a step. Knowing the steps is how you know what the numbers mean.

This file contains no measurement. Not a temperature, not a reflectance, nothing the instrument sensed. What it contains is where every pixel was — the latitude, longitude and ground elevation under each detector reading, plus the angles between the pixel, the satellite and the sun.

This is the part worth slowing down for, because the steps below are not background reading — several of them left their output in your file, in the arrays named beside them. Most people take the headline variable and never look. But if you want to know why a value is what it is, the working is right there.

1. Spacecraft ephemeris and attitude

   Where the satellite was and which way it was pointing, from onboard GPS and star trackers, at every moment of the scan.

2. Scan geometry

   VIIRS sweeps a mirror across the track. Knowing the mirror angle and the detector layout turns “detector 12 of scan 340” into a direction in space.

3. Ellipsoid intersection

   That direction is projected down until it meets a smooth mathematical model of the Earth. This gives a first latitude and longitude — correct at sea level, wrong everywhere else.

4. Terrain correction

   The real ground is not smooth. Looking at a mountain from an angle, the peak appears displaced from where the ellipsoid calculation put it — the same parallax that makes your thumb jump when you close one eye. This step intersects the view direction with an actual elevation model instead. The “terrain-corrected” in the product name is this step, and it is why this file exists rather than the uncorrected one.

   visible in your file asheight

5. Angle computation

   Finally, the four angles that every downstream correction needs: where the satellite was relative to the pixel, and where the sun was.

   visible in your file assensor_zenithsensor_azimuthsolar_zenithsolar_azimuth

Fifth, the label on the outside

The filename is a fingerprint

Every character is doing a job. Nothing in the name is arbitrary and nothing repeats by accident.

An Earthdata filename is not decoration. It is a structured record, and it is the only part of the file you can read without opening anything. Once you can decode it you can sort, filter and sanity-check a directory of ten thousand granules from the shell.

The catch: the key to reading it is not inside the file. It lives in a specification document on a different server, nowhere linked from the download page. That is the gap this whole exercise exists to close.

Sixth, the stamp inside

The extension can lie; the opening bytes cannot

Renaming a file changes its label and nothing else. Formats identify themselves from the inside.

Every file format stamps its identity into its opening bytes. The stamp is written by whatever program created the file, and unlike the extension, it does not survive being renamed. Reading it is how a program knows what it is holding before it commits to a parser.

Bytes two through four spell HDF in plain ASCII, so a damaged file often still announces what it was trying to be. The bytes either side are deliberate traps: they are chosen to get mangled if the file crosses a connection that “helpfully” converts line endings, which turns a silent corruption into an obvious one.

Seventh, what else you need

One file is rarely the whole answer

Products come in families. The one you downloaded may be a piece of a set, and useless on its own.

This file does not stand alone. NASA splits products along lines that make sense to the production system and are invisible from the download page. Knowing which sibling you actually want saves more time than any amount of clever code.

Distributed by LAADS DAAC rather than GES DISC, which is worth knowing because the two archives have different search interfaces and different download tooling even though both sit behind the same Earthdata login.

Opening it up

Inside is a folder tree

Groups, arrays and notes. Once you can see the shape of it, the file stops being opaque.

Open the container and you find something laid out like the folders on your computer. A group is a folder. Inside it are arrays. Attached to each array are attributes — short labelled notes saying what the array is and what to watch out for.

• data The actual values. This is what you came for.
• axis Coordinate values. Row 400, column 900 of a data array means nothing until you look up what position those indices point at.
• bounds The edges of each cell rather than its centre. You need edges to compute an area correctly.

The notes on the arrays

The sticky notes are the documentation

Units, descriptions, missing-data markers. This is the metadata everyone tells you to read, and here is what is in it.

The notes attached to an array are where a self-describing file earns the name. They are also where the traps are, because a note that is missing does not raise an error — software just carries on without it.

The one that catches everybody

Adjacent cells in the array are not adjacent on the ground

Every product has a way of being silently wrong. This is this product’s.

VIIRS scans by sweeping a mirror side to side. Near the middle of the sweep the footprints line up neatly. Toward the edges, where the instrument is looking out at a shallow angle, each footprint stretches and consecutive scans start to overlap — a pattern called the bow-tie effect. VIIRS suppresses it onboard — aggregating detectors and deleting the most-overlapped edge pixels — but it does not vanish.

The consequence for you: the array is a rectangle, but the ground it covers is not. Two neighbouring cells near the swath edge may cover overlapping patches of ground, and some ground is covered twice. Treating the array as if it were a regular grid — taking a mean over a box, or handing it to something that assumes even spacing — double-counts. This is why the latitude and longitude arrive as full-size arrays rather than as two coordinate vectors: there is no vector that describes this geometry.

fill = ds[path].attrs['_FillValue']
a = ds[path][:]
a = np.where(np.isclose(a, fill, rtol=0, atol=0.01), np.nan, a)
mean = np.nanmean(a)

Onto a real map

The map program shows you nothing — correctly

Without a projection, GIS renders the array as-is. That blank, unlocated rectangle is the honest answer.

Sooner or later this file meets a map program, and for a swath product the result is the whole lesson of chapter three made visible: a rectangle in index space, with no projection and no coordinate system, because the array does not know where it is. The knowledge lives in the coordinate arrays — in this product’s case, in this very file.

Drag this granule — or its VNP02 measurement partner — into a map program and you get a rectangle in index space: no projection, no coordinate system, coastlines nowhere near where they belong. That is not a broken file. The coordinates live in this geolocation file as full-size arrays, and mainstream tools can use them: GDAL calls them geolocation arrays (gdalwarp -geoloc), and QGIS can build a georeferenced layer from the pair. One further trap on that route: these files are netCDF-4, and readers that assume rows run bottom-up will hand you an upside-down result — a known stumble with exactly this workflow.

The rescue is that mainstream tools know this pattern. Point them at the coordinate arrays and they will resample the pass onto a real map — slower than opening a gridded product, but correct. What never works is pretending the array is already a map.

When

The clock does not start in 1970

Time is a count of seconds since a reference date, and the reference is rarely the one your language assumes.

Time in a science data file is almost never a date. It is a count of seconds since some reference moment, and the reference is written in the array’s units string. Read the wrong reference and every timestamp you produce is confidently, consistently wrong. The one everyone assumes is 1 January 1970, the Unix epoch. Earth science products frequently do not use it.

Two more things to internalise while you are here. Everything is UTC, never local — a granule labelled 20:48 covers the evening in Lagos and the afternoon in Denver. And every product picks a convention for its end stamp: the last instant inside the window, or the first instant of the next one. Get it wrong and you double-count or drop a slice everywhere two granules meet. Where this guide knows the product’s convention it has already applied it — the times and durations shown above describe the true window, and the filename chapter explains the raw stamp.

One more, specific to this product: the end of the granule’s window is not in the filename, so this guide computed it. If the file carries time_coverage_end as a global attribute, trust that over anything computed here.

House rules

Conventions, and which ones matter to you

Conformance checking sounds like paperwork. Some of it is. Some of it is the difference between a right and a wrong answer.

Now that you know what an attribute is, this will make sense. NASA publishes house rules — the DIWG recommendations — about how a data file should be built, so that software written by someone who has never seen your product can still read it. Alongside those sit the CF conventions, which fix the exact spelling of common attributes.

Files break these rules all the time, including files produced by NASA. That is not a scandal. What matters is which rule, because the consequences run from “a catalogue lists this slightly wrong” to “your average is off by three orders of magnitude.” Sorted that way, not by rule number:

One habit worth taking away: when a tool says a file is non-conformant, the useful question is never is this bad. It is what would I have got wrong if nobody had told me. Most of the time the answer is nothing. Occasionally it is everything.