blackmarble package

blackmarble package#

Submodules#

blackmarble.core module#

class blackmarble.core.BlackMarble(bearer: Optional[str] = None, check_all_tiles_exist: bool = True, drop_values_by_quality_flag: List[int] = [255], output_directory: Optional[Path] = None, output_skip_if_exists: bool = True)#

Bases: object

Interface for extracting and processing NASA Black Marble nighttime light products.

The BlackMarble class provides tools for downloading, extracting, and processing NASA Black Marble nighttime light data. It supports zonal statistics extraction for selected products within a user-defined region of interest (ROI).

Examples

>>> # Option 1: Class-based interface
>>> from blackmarble import BlackMarble, Product
>>>
>>> # Create a BlackMarble instance. If no bearer token is passed explicitly,
>>> # it will attempt to read from the BLACKMARBLE_TOKEN environment variable.
>>> bm = BlackMarble()  # or: BlackMarble(bearer="YOUR_BLACKMARBLE_TOKEN")
>>>
>>> # Define your region of interest as a GeoDataFrame (gdf)
>>> # For example: gdf = gpd.read_file("path_to_shapefile.geojson")
>>>
>>> # Retrieve VNP46A2 for date range into a Xarray Dataset
>>> daily = bm.raster(
>>>     gdf,
>>>     product_id=Product.VNP46A2,
>>>     date_range="2022-01-01",
>>> )

References

NASA Black Marble Products Overview:

https://viirsland.gsfc.nasa.gov/Products/NASA/BlackMarble.html

Black Marble User Guide:

https://viirsland.gsfc.nasa.gov/PDF/BlackMarbleUserGuide_v1.2_20220916.pdf

VARIABLE_DEFAULT = {<Product.VNP46A1: 'VNP46A1'>: 'DNB_At_Sensor_Radiance_500m', <Product.VNP46A2: 'VNP46A2'>: 'Gap_Filled_DNB_BRDF-Corrected_NTL', <Product.VNP46A3: 'VNP46A3'>: 'NearNadir_Composite_Snow_Free', <Product.VNP46A4: 'VNP46A4'>: 'NearNadir_Composite_Snow_Free'}#
close()#

Clean up temporary resources, if used.

collate_tiles(gdf, date_range, pathnames, variable)#

Convert HDF5 files to GeoTIFFs, load them as DataArrays, merge, clip, and combine along time.

Parameters

  • gdf (geopandas.GeoDataFrame) – Region of interest.

  • date_range (iterable) – Sequence of dates to process.

  • pathnames (list) – List of HDF5 file paths.

  • variable (str) – Name of the variable to extract from the HDF5 files.

Returns

combined – Dataset containing the processed variable, merged, clipped to the region of interest, and combined along the time dimension.

Return type

xarray.Dataset

extract(gdf: GeoDataFrame, product_id: Product, date_range: Union[date, List[date]], variable: Optional[str] = None, aggfunc: Union[str, List[str]] = ['mean']) → DataFrame#

Extract and aggregate nighttime lights zonal statistics from NASA Black Marble.

Parameters

  • gdf (geopandas.GeoDataFrame) – Region of interest

  • product_id (Product) – Identifier for the NASA Black Marble VNP46 product. For detailed product descriptions, see also https://blackmarble.gsfc.nasa.gov/#product.

  • date_range (datetime.date | List[datetime.date]) – Date range (single date or list of dates) for which to retrieve NASA Black Marble data.

  • variable (str, default = None) –

    Variable to create GeoTIFF raster. Further information, please see the NASA Black Marble User Guide for VNP46A1, see Table 3; for VNP46A2 see Table 6; for VNP46A3 and VNP46A4, see Table 9. By default, it uses the following default variables:

    • For VNP46A1, uses DNB_At_Sensor_Radiance_500m

    • For VNP46A2, uses Gap_Filled_DNB_BRDF-Corrected_NTL

    • For VNP46A3, uses NearNadir_Composite_Snow_Free.

    • For VNP46A4, uses NearNadir_Composite_Snow_Free.

  • aggfunc (str | List[str], default=["mean"]) – Which statistics to calculate for each zone. All possible choices are listed in rasterstats.utils.VALID_STATS.

Returns

Zonal statistics dataframe

Return type

pandas.DataFrame

property output_directory: Path#

Return the active output directory path.

raster(gdf: GeoDataFrame, product_id: Product, date_range: Union[date, List[date]], variable: Optional[str] = None) → Dataset#

Create a stack of nighttime lights rasters by retrieiving from NASA Black Marble data.

Parameters

  • gdf (geopandas.GeoDataFrame) – Region of interest

  • product_id (Product) – Identifier for the NASA Black Marble VNP46 product. For detailed product descriptions, see also https://blackmarble.gsfc.nasa.gov/#product.

  • date_range (datetime.date | List[datetime.date]) – Date range (single date or list of dates) for which to retrieve NASA Black Marble data.

  • variable (str, default = None) –

    Variable for which to a GeoTIFF raster. Further information, please see the NASA Black Marble User Guide for VNP46A1, see Table 3; for VNP46A2 see Table 6; for VNP46A3 and VNP46A4, see Table 9. By default, it uses the following default variables:

    • For VNP46A1, uses DNB_At_Sensor_Radiance_500m

    • For VNP46A2, uses Gap_Filled_DNB_BRDF-Corrected_NTL

    • For VNP46A3, uses NearNadir_Composite_Snow_Free.

    • For VNP46A4, uses NearNadir_Composite_Snow_Free.

Returns

xarray.Dataset containing a stack of nighttime lights rasters

Return type

xarray.Dataset

blackmarble.download module#

class blackmarble.download.BlackMarbleDownloader(bearer: str, directory: Path)#

Bases: BaseModel

A downloader to retrieve NASA Black Marble data.

bearer#

NASA EarthData bearer token

Type

str

directory#

Local directory to which download

Type

Path

URL: ClassVar[str] = 'https://ladsweb.modaps.eosdis.nasa.gov'#
bearer: str#
directory: Path#
download(gdf: GeoDataFrame, product_id: Product, date_range: List[date], skip_if_exists: bool = True)#

Downloads files asynchronously from NASA Black Marble archive.

Parameters

  • gdf (geopandas.GeoDataFrame) – Region of Interest. Converted to EPSG:4326 and intersected with Black Mable tiles

  • product (Product) – Nasa Black Marble Product Id (e.g, VNP46A1)

  • date_range (List[datetime.date]) – Date range for which to download NASA Black Marble data.

  • skip_if_exists (bool, default=True) – Whether to skip downloading data if file already exists

Returns

list – List of downloaded H5 filenames.

Return type

List[pathlib.Path]

async get_manifest(gdf: GeoDataFrame, product_id: Product, date_range: Union[date, List[date]]) → DataFrame#

Retrieve NASA Black Marble data manifest. i.d., download links.

Parameters

  • product_id (Product) – NASA Black Marble product suite (VNP46) identifier

  • date_range (datetime.date | List[datetime.date]) – Date range for which to retrieve NASA Black Marble data manifest

Returns

NASA Black Marble data manifest (i.e., downloads links)

Return type

pandas.DataFrame

model_config: ClassVar[ConfigDict] = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

exception blackmarble.download.InvalidHDF5File#

Bases: Exception

Raised when the downloaded HDF5 file is invalid or corrupted.

blackmarble.download.chunks(ls, n)#

Yield successive n-sized chunks from list.

async blackmarble.download.get_url(client: AsyncClient, url: str, params: dict) → Response#
Returns

HTTP response

Return type

httpx.Response

blackmarble.extract module#

blackmarble.extract.bm_extract(gdf: GeoDataFrame, product_id: Product, date_range: Union[date, List[date]], bearer: str, aggfunc: Union[str, List[str]] = ['mean'], variable: Optional[str] = None, drop_values_by_quality_flag: List[int] = [], check_all_tiles_exist: bool = True, output_directory: Optional[Path] = None, output_skip_if_exists: bool = True) → DataFrame#

Extract and aggregate nighttime lights zonal statistics from NASA Black Marble.

Parameters

  • gdf (geopandas.GeoDataFrame) – Region of interest

  • product_id (Product) –

    Identifier for the NASA Black Marble VNP46 product.

    Available options include:

    • VNP46A1: Daily top-of-atmosphere (TOA) radiance (raw)

    • VNP46A2: Daily moonlight-corrected nighttime lights

    • VNP46A3: Monthly gap-filled nighttime light composites

    • VNP46A4: Annual gap-filled nighttime light composites

    For detailed product descriptions, see: https://blackmarble.gsfc.nasa.gov/#product

  • date_range (datetime.date | List[datetime.date]) – Date range (single date or list of dates) for which to retrieve NASA Black Marble data.

  • bearer (str) – NASA Earthdata Bearer token. Please refer to the documentation.

  • aggfunc (str | List[str], default=["mean"]) –

    Which statistics to calculate for each zone. All possible choices are listed in rasterstats.utils.VALID_STATS.

  • variable (str, default = None) –

    Variable to create GeoTIFF raster. Further information, please see the NASA Black Marble User Guide for VNP46A1, see Table 3; for VNP46A2 see Table 6; for VNP46A3 and VNP46A4, see Table 9. By default, it uses the following default variables:

    • For VNP46A1, uses DNB_At_Sensor_Radiance_500m

    • For VNP46A2, uses Gap_Filled_DNB_BRDF-Corrected_NTL

    • For VNP46A3, uses NearNadir_Composite_Snow_Free.

    • For VNP46A4, uses NearNadir_Composite_Snow_Free.

  • drop_values_by_quality_flag (List[int], optional) –

    List of the quality flag values for which to drop data values. Each pixel has a quality flag value, where low quality values can be removed. Values are set to NA for each value in the list.

    For VNP46A1 and VNP46A2 (daily data):

    • 0: High-quality, Persistent nighttime lights

    • 1: High-quality, Ephemeral nighttime Lights

    • 2: Poor-quality, Outlier, potential cloud contamination, or other issues

    • 255: No retrieval, Fill value (masked out on ingestion)

    For VNP46A3 and VNP46A4 (monthly and annual data):

    • 0: Good-quality, The number of observations used for the composite is larger than 3

    • 1: Poor-quality, The number of observations used for the composite is less than or equal to 3

    • 2: Gap filled NTL based on historical data

    • 255: Fill value

  • check_all_tiles_exist (bool, default=True) – Check whether all Black Marble nighttime light tiles exist for the region of interest. Sometimes not all tiles are available, so the full region of interest may not be covered. By default (True), it skips cases where not all tiles are available.

  • output_directory (pathlib.Path, optional) – Directory to produce output. By default, the output will be produced onto a temporary directory.

  • output_skip_if_exists (bool, default=True) –

    Whether to skip downloading or extracting data if the data file for that date already exists.

    bearer

Returns

Zonal statistics dataframe

Return type

pandas.DataFrame

blackmarble.raster module#

blackmarble.raster.bm_raster(gdf: GeoDataFrame, product_id: Product, date_range: Union[date, List[date]], bearer: str, variable: Optional[str] = None, drop_values_by_quality_flag: List[int] = [], check_all_tiles_exist: bool = True, output_directory: Optional[Path] = None, output_skip_if_exists: bool = True)#

Create a stack of nighttime lights rasters by retrieiving from NASA Black Marble data.

Parameters

  • gdf (geopandas.GeoDataFrame) – Region of interest

  • product_id (Product) –

    Identifier for the NASA Black Marble VNP46 product.

    Available options include:

    • VNP46A1: Daily top-of-atmosphere (TOA) radiance (raw)

    • VNP46A2: Daily moonlight-corrected nighttime lights

    • VNP46A3: Monthly gap-filled nighttime light composites

    • VNP46A4: Annual gap-filled nighttime light composites

    For detailed product descriptions, see: https://blackmarble.gsfc.nasa.gov/#product

  • date_range (datetime.date | List[datetime.date]) – Date range (single date or list of dates) for which to retrieve NASA Black Marble data.

  • bearer (str) –

    NASA Earthdata Bearer token. Please refer to the documentation.

  • variable (str, default = None) –

    Variable for which to a GeoTIFF raster. Further information, please see the NASA Black Marble User Guide for VNP46A1, see Table 3; for VNP46A2 see Table 6; for VNP46A3 and VNP46A4, see Table 9. By default, it uses the following default variables:

    • For VNP46A1, uses DNB_At_Sensor_Radiance_500m

    • For VNP46A2, uses Gap_Filled_DNB_BRDF-Corrected_NTL

    • For VNP46A3, uses NearNadir_Composite_Snow_Free.

    • For VNP46A4, uses NearNadir_Composite_Snow_Free.

  • drop_values_by_quality_flag (List[int], optional) –

    List of the quality flag values for which to drop data values. Each pixel has a quality flag value, where low quality values can be removed. Values are set to NA for each value in the list.

    For VNP46A1 and VNP46A2 (daily data):

    • 0: High-quality, Persistent nighttime lights

    • 1: High-quality, Ephemeral nighttime Lights

    • 2: Poor-quality, Outlier, potential cloud contamination, or other issues

    • 255: No retrieval, Fill value (masked out on ingestion)

    For VNP46A3 and VNP46A4 (monthly and annual data):

    • 0: Good-quality, The number of observations used for the composite is larger than 3

    • 1: Poor-quality, The number of observations used for the composite is less than or equal to 3

    • 2: Gap filled NTL based on historical data

    • 255: Fill value

  • check_all_tiles_exist (bool, default=True) – Check whether all Black Marble nighttime light tiles exist for the region of interest. Sometimes not all tiles are available, so the full region of interest may not be covered. By default (True), it skips cases where not all tiles are available.

  • output_directory (pathlib.Path, optional) – Directory to produce output. By default, the output will be produced onto a temporary directory.

  • output_skip_if_exists (bool, default=True) – Whether to skip downloading or extracting data if the data file for that date already exists.

Returns

xarray.Dataset containing a stack of nighttime lights rasters

Return type

xarray.Dataset

blackmarble.types module#

class blackmarble.types.Product(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: Enum

Representing of NASA’s Black Marble VNP46 product suite.

Products:

  • VNP46A1: Daily at-sensor top-of-atmosphere (TOA) nighttime radiance.

  • VNP46A2: Daily moonlight-adjusted nighttime lights (NTL).

  • VNP46A3: Monthly-aggregated, gap-filled nighttime light composites

  • VNP46A4: Yearly-aggregated, gap-filled nighttime light composites.

For more details, see: https://blackmarble.gsfc.nasa.gov/#product

VNP46A1 = 'VNP46A1'#
VNP46A2 = 'VNP46A2'#
VNP46A3 = 'VNP46A3'#
VNP46A4 = 'VNP46A4'#

Module contents#

class blackmarble.BlackMarble(bearer: Optional[str] = None, check_all_tiles_exist: bool = True, drop_values_by_quality_flag: List[int] = [255], output_directory: Optional[Path] = None, output_skip_if_exists: bool = True)#

Bases: object

Interface for extracting and processing NASA Black Marble nighttime light products.

The BlackMarble class provides tools for downloading, extracting, and processing NASA Black Marble nighttime light data. It supports zonal statistics extraction for selected products within a user-defined region of interest (ROI).

Examples

>>> # Option 1: Class-based interface
>>> from blackmarble import BlackMarble, Product
>>>
>>> # Create a BlackMarble instance. If no bearer token is passed explicitly,
>>> # it will attempt to read from the BLACKMARBLE_TOKEN environment variable.
>>> bm = BlackMarble()  # or: BlackMarble(bearer="YOUR_BLACKMARBLE_TOKEN")
>>>
>>> # Define your region of interest as a GeoDataFrame (gdf)
>>> # For example: gdf = gpd.read_file("path_to_shapefile.geojson")
>>>
>>> # Retrieve VNP46A2 for date range into a Xarray Dataset
>>> daily = bm.raster(
>>>     gdf,
>>>     product_id=Product.VNP46A2,
>>>     date_range="2022-01-01",
>>> )

References

NASA Black Marble Products Overview:

https://viirsland.gsfc.nasa.gov/Products/NASA/BlackMarble.html

Black Marble User Guide:

https://viirsland.gsfc.nasa.gov/PDF/BlackMarbleUserGuide_v1.2_20220916.pdf

VARIABLE_DEFAULT = {<Product.VNP46A1: 'VNP46A1'>: 'DNB_At_Sensor_Radiance_500m', <Product.VNP46A2: 'VNP46A2'>: 'Gap_Filled_DNB_BRDF-Corrected_NTL', <Product.VNP46A3: 'VNP46A3'>: 'NearNadir_Composite_Snow_Free', <Product.VNP46A4: 'VNP46A4'>: 'NearNadir_Composite_Snow_Free'}#
close()#

Clean up temporary resources, if used.

collate_tiles(gdf, date_range, pathnames, variable)#

Convert HDF5 files to GeoTIFFs, load them as DataArrays, merge, clip, and combine along time.

Parameters

  • gdf (geopandas.GeoDataFrame) – Region of interest.

  • date_range (iterable) – Sequence of dates to process.

  • pathnames (list) – List of HDF5 file paths.

  • variable (str) – Name of the variable to extract from the HDF5 files.

Returns

combined – Dataset containing the processed variable, merged, clipped to the region of interest, and combined along the time dimension.

Return type

xarray.Dataset

extract(gdf: GeoDataFrame, product_id: Product, date_range: Union[date, List[date]], variable: Optional[str] = None, aggfunc: Union[str, List[str]] = ['mean']) → DataFrame#

Extract and aggregate nighttime lights zonal statistics from NASA Black Marble.

Parameters

  • gdf (geopandas.GeoDataFrame) – Region of interest

  • product_id (Product) – Identifier for the NASA Black Marble VNP46 product. For detailed product descriptions, see also https://blackmarble.gsfc.nasa.gov/#product.

  • date_range (datetime.date | List[datetime.date]) – Date range (single date or list of dates) for which to retrieve NASA Black Marble data.

  • variable (str, default = None) –

    Variable to create GeoTIFF raster. Further information, please see the NASA Black Marble User Guide for VNP46A1, see Table 3; for VNP46A2 see Table 6; for VNP46A3 and VNP46A4, see Table 9. By default, it uses the following default variables:

    • For VNP46A1, uses DNB_At_Sensor_Radiance_500m

    • For VNP46A2, uses Gap_Filled_DNB_BRDF-Corrected_NTL

    • For VNP46A3, uses NearNadir_Composite_Snow_Free.

    • For VNP46A4, uses NearNadir_Composite_Snow_Free.

  • aggfunc (str | List[str], default=["mean"]) –

    Which statistics to calculate for each zone. All possible choices are listed in rasterstats.utils.VALID_STATS.

Returns

Zonal statistics dataframe

Return type

pandas.DataFrame

property output_directory: Path#

Return the active output directory path.

raster(gdf: GeoDataFrame, product_id: Product, date_range: Union[date, List[date]], variable: Optional[str] = None) → Dataset#

Create a stack of nighttime lights rasters by retrieiving from NASA Black Marble data.

Parameters

  • gdf (geopandas.GeoDataFrame) – Region of interest

  • product_id (Product) – Identifier for the NASA Black Marble VNP46 product. For detailed product descriptions, see also https://blackmarble.gsfc.nasa.gov/#product.

  • date_range (datetime.date | List[datetime.date]) – Date range (single date or list of dates) for which to retrieve NASA Black Marble data.

  • variable (str, default = None) –

    Variable for which to a GeoTIFF raster. Further information, please see the NASA Black Marble User Guide for VNP46A1, see Table 3; for VNP46A2 see Table 6; for VNP46A3 and VNP46A4, see Table 9. By default, it uses the following default variables:

    • For VNP46A1, uses DNB_At_Sensor_Radiance_500m

    • For VNP46A2, uses Gap_Filled_DNB_BRDF-Corrected_NTL

    • For VNP46A3, uses NearNadir_Composite_Snow_Free.

    • For VNP46A4, uses NearNadir_Composite_Snow_Free.

Returns

xarray.Dataset containing a stack of nighttime lights rasters

Return type

xarray.Dataset

class blackmarble.Product(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: Enum

Representing of NASA’s Black Marble VNP46 product suite.

Products:

  • VNP46A1: Daily at-sensor top-of-atmosphere (TOA) nighttime radiance.

  • VNP46A2: Daily moonlight-adjusted nighttime lights (NTL).

  • VNP46A3: Monthly-aggregated, gap-filled nighttime light composites

  • VNP46A4: Yearly-aggregated, gap-filled nighttime light composites.

For more details, see: https://blackmarble.gsfc.nasa.gov/#product

VNP46A1 = 'VNP46A1'#
VNP46A2 = 'VNP46A2'#
VNP46A3 = 'VNP46A3'#
VNP46A4 = 'VNP46A4'#
blackmarble.bm_extract(gdf: GeoDataFrame, product_id: Product, date_range: Union[date, List[date]], bearer: str, aggfunc: Union[str, List[str]] = ['mean'], variable: Optional[str] = None, drop_values_by_quality_flag: List[int] = [], check_all_tiles_exist: bool = True, output_directory: Optional[Path] = None, output_skip_if_exists: bool = True) → DataFrame#

Extract and aggregate nighttime lights zonal statistics from NASA Black Marble.

Parameters

  • gdf (geopandas.GeoDataFrame) – Region of interest

  • product_id (Product) –

    Identifier for the NASA Black Marble VNP46 product.

    Available options include:

    • VNP46A1: Daily top-of-atmosphere (TOA) radiance (raw)

    • VNP46A2: Daily moonlight-corrected nighttime lights

    • VNP46A3: Monthly gap-filled nighttime light composites

    • VNP46A4: Annual gap-filled nighttime light composites

    For detailed product descriptions, see: https://blackmarble.gsfc.nasa.gov/#product

  • date_range (datetime.date | List[datetime.date]) – Date range (single date or list of dates) for which to retrieve NASA Black Marble data.

  • bearer (str) –

    NASA Earthdata Bearer token. Please refer to the documentation.

  • aggfunc (str | List[str], default=["mean"]) –

    Which statistics to calculate for each zone. All possible choices are listed in rasterstats.utils.VALID_STATS.

  • variable (str, default = None) –

    Variable to create GeoTIFF raster. Further information, please see the NASA Black Marble User Guide for VNP46A1, see Table 3; for VNP46A2 see Table 6; for VNP46A3 and VNP46A4, see Table 9. By default, it uses the following default variables:

    • For VNP46A1, uses DNB_At_Sensor_Radiance_500m

    • For VNP46A2, uses Gap_Filled_DNB_BRDF-Corrected_NTL

    • For VNP46A3, uses NearNadir_Composite_Snow_Free.

    • For VNP46A4, uses NearNadir_Composite_Snow_Free.

  • drop_values_by_quality_flag (List[int], optional) –

    List of the quality flag values for which to drop data values. Each pixel has a quality flag value, where low quality values can be removed. Values are set to NA for each value in the list.

    For VNP46A1 and VNP46A2 (daily data):

    • 0: High-quality, Persistent nighttime lights

    • 1: High-quality, Ephemeral nighttime Lights

    • 2: Poor-quality, Outlier, potential cloud contamination, or other issues

    • 255: No retrieval, Fill value (masked out on ingestion)

    For VNP46A3 and VNP46A4 (monthly and annual data):

    • 0: Good-quality, The number of observations used for the composite is larger than 3

    • 1: Poor-quality, The number of observations used for the composite is less than or equal to 3

    • 2: Gap filled NTL based on historical data

    • 255: Fill value

  • check_all_tiles_exist (bool, default=True) – Check whether all Black Marble nighttime light tiles exist for the region of interest. Sometimes not all tiles are available, so the full region of interest may not be covered. By default (True), it skips cases where not all tiles are available.

  • output_directory (pathlib.Path, optional) – Directory to produce output. By default, the output will be produced onto a temporary directory.

  • output_skip_if_exists (bool, default=True) –

    Whether to skip downloading or extracting data if the data file for that date already exists.

    bearer

Returns

Zonal statistics dataframe

Return type

pandas.DataFrame

blackmarble.bm_raster(gdf: GeoDataFrame, product_id: Product, date_range: Union[date, List[date]], bearer: str, variable: Optional[str] = None, drop_values_by_quality_flag: List[int] = [], check_all_tiles_exist: bool = True, output_directory: Optional[Path] = None, output_skip_if_exists: bool = True)#

Create a stack of nighttime lights rasters by retrieiving from NASA Black Marble data.

Parameters

  • gdf (geopandas.GeoDataFrame) – Region of interest

  • product_id (Product) –

    Identifier for the NASA Black Marble VNP46 product.

    Available options include:

    • VNP46A1: Daily top-of-atmosphere (TOA) radiance (raw)

    • VNP46A2: Daily moonlight-corrected nighttime lights

    • VNP46A3: Monthly gap-filled nighttime light composites

    • VNP46A4: Annual gap-filled nighttime light composites

    For detailed product descriptions, see: https://blackmarble.gsfc.nasa.gov/#product

  • date_range (datetime.date | List[datetime.date]) – Date range (single date or list of dates) for which to retrieve NASA Black Marble data.

  • bearer (str) –

    NASA Earthdata Bearer token. Please refer to the documentation.

  • variable (str, default = None) –

    Variable for which to a GeoTIFF raster. Further information, please see the NASA Black Marble User Guide for VNP46A1, see Table 3; for VNP46A2 see Table 6; for VNP46A3 and VNP46A4, see Table 9. By default, it uses the following default variables:

    • For VNP46A1, uses DNB_At_Sensor_Radiance_500m

    • For VNP46A2, uses Gap_Filled_DNB_BRDF-Corrected_NTL

    • For VNP46A3, uses NearNadir_Composite_Snow_Free.

    • For VNP46A4, uses NearNadir_Composite_Snow_Free.

  • drop_values_by_quality_flag (List[int], optional) –

    List of the quality flag values for which to drop data values. Each pixel has a quality flag value, where low quality values can be removed. Values are set to NA for each value in the list.

    For VNP46A1 and VNP46A2 (daily data):

    • 0: High-quality, Persistent nighttime lights

    • 1: High-quality, Ephemeral nighttime Lights

    • 2: Poor-quality, Outlier, potential cloud contamination, or other issues

    • 255: No retrieval, Fill value (masked out on ingestion)

    For VNP46A3 and VNP46A4 (monthly and annual data):

    • 0: Good-quality, The number of observations used for the composite is larger than 3

    • 1: Poor-quality, The number of observations used for the composite is less than or equal to 3

    • 2: Gap filled NTL based on historical data

    • 255: Fill value

  • check_all_tiles_exist (bool, default=True) – Check whether all Black Marble nighttime light tiles exist for the region of interest. Sometimes not all tiles are available, so the full region of interest may not be covered. By default (True), it skips cases where not all tiles are available.

  • output_directory (pathlib.Path, optional) – Directory to produce output. By default, the output will be produced onto a temporary directory.

  • output_skip_if_exists (bool, default=True) – Whether to skip downloading or extracting data if the data file for that date already exists.

Returns

xarray.Dataset containing a stack of nighttime lights rasters

Return type

xarray.Dataset

Contents