gpw datasets

.isort.cfg

@@ -0,0 +1,3 @@
+[isort]
+multi_line_output = 3
+include_trailing_comma = true

README.md

@@ -1,18 +1,98 @@
-# stactools-package
-
-Template repostitory for [stactools](https://github.com/stac-utils/stactools) packages.
-
-## How to use
-
-1. Clone this template repository as your package name, e.g. `landsat`.
-   This name should be short, memorable, and a valid Python package name (i.e. it shouldn't start with a number, etc).
-   It can, however, include a hyphen, in which case the name for Python imports will be the underscored version, e.g. `landsat-8` goes to `stactools.landsat_8`.
-   Your name will be used on PyPI to publish the package in the stactools namespace, e.g. `stactools-landsat`.
-2. Change into the top-level directory of your package and run `scripts/rename`.
-   This will update _most_ of the files in the repository with your new package name.
-   You'll have to manually update `setup.cfg` and `README.md`.
-3. Update `setup.cfg` with your package name, description, and such.
-4. Rewrite this README to provide information about how to use your package.
-5. Update the LICENSE with your company's information (or whomever holds the copyright).
-6. Run `sphinx-quickstart` in the `docs` directory to create the documentation template.
-7. Update `docs/installation_and_basic_usage.ipynb` to provide an interactive notebook to help users get started. Include the following badge at the top of the README to launch the notebook: [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/stactools-packages/template/main?filepath=docs/installation_and_basic_usage.ipynb). Be sure to modify the badge href to match your package repo.
+# stactools-package gpw
+
+- Name: Gridded Population of the World (GPW) v4, Population Count, v4.11
+- Package: `stactools.gpw`
+- PyPI: https://pypi.org/project/stactools-gpw/
+- Owner: @sparkgeo
+- Dataset homepage: https://sedac.ciesin.columbia.edu/data/collection/gpw-v4/sets/browse
+- STAC extensions used:
+  - [file](https://github.com/stac-extensions/file/)
+  - [item-assets](https://github.com/stac-extensions/item-assets/)
+  - [proj](https://github.com/stac-extensions/projection/)
+  - [raster](https://github.com/stac-extensions/raster/)
+  - [scientific](https://github.com/stac-extensions/scientific/)
+
+The Gridded Population of the World, Version 4 (GPWv4) Revision 11 Population Datasets (population count, UN WPP-adjusted population count, population density, and UN WPP-adjusted population density) consist of estimates of human population (number of persons per pixel) and population density (number of persons per square kilometer), consistent with national censuses and population registers, for the years 2000, 2005, 2010, 2015, and 2020. Where indicated by name, values have been adjusted to match the 2015 Revision of the United Nation's World Population Prospects (UN WPP) country totals.
+
+The Gridded Population of the World, Version 4 (GPWv4) Revision 11 Ancillary Datasets (data quality indicators, basic demographic characteristics, land and water area, and national identifier grid) provide context for the population count and density rasters found within the Gridded Population of the World Population Collection.
+
+## Usage
+
+### Using the CLI
+
+```bash
+mkdir example_output
+# Create a COG - creates example_output/gpw_v4_population_count_rev11_2000_30_sec_cog.tif
+stac gpw create-cog -d example_output -s tests/data-files/raw/population/gpw_v4_population_count_rev11_2000_30_sec.tif
+# Create a COG - first expanding the dataset bbox, then retiling to 10000 x 10000 pixel COG files. Creates several tif files within example_output.
+stac gpw create-cog -d example_output -s tests/data-files/raw/population/gpw_v4_population_count_rev11_2000_30_sec.tif -t -e -180 -90 180 90
+# Create a population STAC Item - creates example_output/gpw_v4_rev11_2000_30_sec_2_1.json
+stac gpw create-pop-item \
+  -d example_output \
+  -c \
+  tests/data-files/tiles/population/gpw_v4_population_count_rev11_2000_30_sec_2_1_cog.tif \
+  tests/data-files/tiles/population/gpw_v4_population_count_adjusted_to_2015_unwpp_country_totals_rev11_2000_30_sec_2_1_cog.tif \
+  tests/data-files/tiles/population/gpw_v4_population_density_rev11_2000_30_sec_2_1_cog.tif \
+  tests/data-files/tiles/population/gpw_v4_population_density_adjusted_to_2015_unwpp_country_totals_rev11_2000_30_sec_2_1_cog.tif
+# Create an ancillary STAC Item - creates example_output/gpw_v4_rev11_30_sec_2_1.json
+stac gpw create-anc-item \
+  -d example_output \
+  -c \
+  tests/data-files/tiles/ancillary/gpw_v4_data_quality_indicators_rev11_context_30_sec_2_1_cog.tif \
+  tests/data-files/tiles/ancillary/gpw_v4_data_quality_indicators_rev11_mean_adminunitarea_30_sec_2_1_cog.tif \
+  tests/data-files/tiles/ancillary/gpw_v4_data_quality_indicators_rev11_watermask_30_sec_2_1_cog.tif \
+  tests/data-files/tiles/ancillary/gpw_v4_basic_demographic_characteristics_rev11_atotpopbt_2010_cntm_30_sec_2_1_cog.tif \
+  tests/data-files/tiles/ancillary/gpw_v4_basic_demographic_characteristics_rev11_atotpopbt_2010_dens_30_sec_2_1_cog.tif \
+  tests/data-files/tiles/ancillary/gpw_v4_basic_demographic_characteristics_rev11_atotpopft_2010_cntm_30_sec_2_1_cog.tif \
+  tests/data-files/tiles/ancillary/gpw_v4_basic_demographic_characteristics_rev11_atotpopft_2010_dens_30_sec_2_1_cog.tif \
+  tests/data-files/tiles/ancillary/gpw_v4_basic_demographic_characteristics_rev11_atotpopmt_2010_cntm_30_sec_2_1_cog.tif \
+  tests/data-files/tiles/ancillary/gpw_v4_basic_demographic_characteristics_rev11_atotpopmt_2010_dens_30_sec_2_1_cog.tif \
+  tests/data-files/tiles/ancillary/gpw_v4_land_water_area_rev11_landareakm_30_sec_2_1_cog.tif \
+  tests/data-files/tiles/ancillary/gpw_v4_land_water_area_rev11_waterareakm_30_sec_expanded_2_1_cog.tif \
+  tests/data-files/tiles/ancillary/gpw_v4_national_identifier_grid_rev11_30_sec_2_1_cog.tif
+
+# Create a population STAC Collection - creates example_output/collection.json
+stac gpw create-pop-collection -d example_output/collection.json
+
+# Create a population STAC Collection - creates example_output/collection.json
+stac gpw create-anc-collection -d example_output/collection.json
+```
+
+### As a python module
+
+```python
+from stactools.gpw import cog, stac
+
+# Create a population (or ancillary) STAC Collection
+stac.create_pop_collection("example_output/collection.json")
+# stac.create_anc_collection("example_output/collection.json")
+
+# Create a COG (optional parameters to retile or expand tiled output)
+cog.create_cog("/path/to/local.tif", "/path/to/output_directory")
+
+# Create a population STAC Item
+cog_list = [
+    Path to population count COG
+    Path to adjusted population count COG
+    Path to population density COG
+    Path to adjusted population density COG
+]
+stac.create_pop_item(*cog_list)
+
+# Create an ancillary STAC Item
+cog_list = [
+    Path to Data Quality Indicators - Data Context COG
+    Path to Data Quality Indicators - Mean Administrative Unit Area COG
+    Path to Data Quality Indicators - Water Mask COG
+    Path to Basic Demographic Characteristics - Ttl Pop Count
+    Path to Basic Demographic Characteristics - Ttl Pop Density
+    Path to Basic Demographic Characteristics - Female Count
+    Path to Basic Demographic Characteristics - Female Density
+    Path to Basic Demographic Characteristics - Male Count
+    Path to Basic Demographic Characteristics - Male Density
+    Path to Land Area COG
+    Path to Water Area COG
+    Path to National Identifier Grid COG
+]
+stac.create_anc_item(*cog_list)
+```

examples/ancillary/collection.json

@@ -0,0 +1,142 @@
+{
+  "type": "Collection",
+  "id": "GPW-ancillary",
+  "stac_version": "1.0.0",
+  "description": "The Gridded Population of the World, Version 4 (GPWv4) Revision 11 Ancillary Datasets (data quality indicators, basic demographic characteristics, land and water area, and national identifier grid) provide context for the population count and density rasters found within the Gridded Population of the World Population Collection.",
+  "links": [
+    {
+      "rel": "root",
+      "href": "./collection.json",
+      "type": "application/json"
+    },
+    {
+      "rel": "license",
+      "href": "https://creativecommons.org/licenses/by/4.0/legalcode",
+      "title": "Creative Commons Attribution 4.0 International"
+    },
+    {
+      "rel": "self",
+      "href": "path/to/stactools-packages/gpw/examples/ancillary/collection.json",
+      "type": "application/json"
+    }
+  ],
+  "stac_extensions": [
+    "https://stac-extensions.github.io/item-assets/v1.0.0/schema.json",
+    "https://stac-extensions.github.io/scientific/v1.0.0/schema.json"
+  ],
+  "item_assets": {
+    "anc_dqi_context": {
+      "title": "Data Quality Indicators - Data Context",
+      "description": "Gridded Population of the World, Version 4 (GPWv4): Data Quality Indicators - Data Context, 30 arc-seconds, 1km resolution",
+      "type": "image/tiff; application=geotiff; profile=cloud-optimized",
+      "roles": ["data"],
+      "sci:doi": "10.7927/H42Z13KG",
+      "sci:citation": "Center for International Earth Science Information Network - CIESIN - Columbia University. 2018. Gridded Population of the World, Version 4 (GPWv4): Data Quality Indicators, Revision 11. Palisades, NY: NASA Socioeconomic Data and Applications Center (SEDAC). https://doi.org/10.7927/H42Z13KG. Accessed 22 Octover 2021."
+    },
+    "anc_dqi_admin": {
+      "title": "Data Quality Indicators - Mean Administrative Unit Area",
+      "description": "Gridded Population of the World, Version 4 (GPWv4): Data Quality Indicators - Mean Administrative Unit Area, 30 arc-seconds, 1km resolution",
+      "type": "image/tiff; application=geotiff; profile=cloud-optimized",
+      "roles": ["data"],
+      "sci:doi": "10.7927/H42Z13KG",
+      "sci:citation": "Center for International Earth Science Information Network - CIESIN - Columbia University. 2018. Gridded Population of the World, Version 4 (GPWv4): Data Quality Indicators, Revision 11. Palisades, NY: NASA Socioeconomic Data and Applications Center (SEDAC). https://doi.org/10.7927/H42Z13KG. Accessed 22 October 2021."
+    },
+    "anc_dqi_watermask": {
+      "title": "Data Quality Indicators - Water Mask",
+      "description": "Gridded Population of the World, Version 4 (GPWv4): Data Quality Indicators - Water Mask, 30 arc-seconds, 1km resolution",
+      "type": "image/tiff; application=geotiff; profile=cloud-optimized",
+      "roles": ["data"],
+      "sci:doi": "10.7927/H42Z13KG",
+      "sci:citation": "Center for International Earth Science Information Network - CIESIN - Columbia University. 2018. Gridded Population of the World, Version 4 (GPWv4): Data Quality Indicators, Revision 11. Palisades, NY: NASA Socioeconomic Data and Applications Center (SEDAC). https://doi.org/10.7927/H42Z13KG. Accessed 22 October 2021."
+    },
+    "anc_bdc_bt_count": {
+      "title": "Basic Demographic Characteristics - Total Population Count",
+      "description": "Gridded Population of the World, Version 4 (GPWv4): Basic Demographic Characteristics - Total Population Count, 30 arc-seconds, 1km resolution",
+      "type": "image/tiff; application=geotiff; profile=cloud-optimized",
+      "roles": ["data"],
+      "sci:doi": "10.7927/H46M34XX",
+      "sci:citation": "Center for International Earth Science Information Network - CIESIN - Columbia University. 2018. Gridded Population of the World, Version 4 (GPWv4): Basic Demographic Characteristics, Revision 11. Palisades, NY: NASA Socioeconomic Data and Applications Center (SEDAC). https://doi.org/10.7927/H46M34XX. Accessed 22 October 2021."
+    },
+    "anc_bdc_bt_density": {
+      "title": "Basic Demographic Characteristics - Total Population Density",
+      "description": "Gridded Population of the World, Version 4 (GPWv4): Basic Demographic Characteristics - Total Population Density, 30 arc-seconds, 1km resolution",
+      "type": "image/tiff; application=geotiff; profile=cloud-optimized",
+      "roles": ["data"],
+      "sci:doi": "10.7927/H46M34XX",
+      "sci:citation": "Center for International Earth Science Information Network - CIESIN - Columbia University. 2018. Gridded Population of the World, Version 4 (GPWv4): Basic Demographic Characteristics, Revision 11. Palisades, NY: NASA Socioeconomic Data and Applications Center (SEDAC). https://doi.org/10.7927/H46M34XX. Accessed 22 October 2021."
+    },
+    "anc_bdc_ft_count": {
+      "title": "Basic Demographic Characteristics - Female Count",
+      "description": "Gridded Population of the World, Version 4 (GPWv4): Basic Demographic Characteristics - Female Count, 30 arc-seconds, 1km resolution",
+      "type": "image/tiff; application=geotiff; profile=cloud-optimized",
+      "roles": ["data"],
+      "sci:doi": "10.7927/H46M34XX",
+      "sci:citation": "Center for International Earth Science Information Network - CIESIN - Columbia University. 2018. Gridded Population of the World, Version 4 (GPWv4): Basic Demographic Characteristics, Revision 11. Palisades, NY: NASA Socioeconomic Data and Applications Center (SEDAC). https://doi.org/10.7927/H46M34XX. Accessed 22 October 2021."
+    },
+    "anc_bdc_ft_density": {
+      "title": "Basic Demographic Characteristics - Female Density",
+      "description": "Gridded Population of the World, Version 4 (GPWv4): Basic Demographic Characteristics - Female Density, 30 arc-seconds, 1km resolution",
+      "type": "image/tiff; application=geotiff; profile=cloud-optimized",
+      "roles": ["data"],
+      "sci:doi": "10.7927/H46M34XX",
+      "sci:citation": "Center for International Earth Science Information Network - CIESIN - Columbia University. 2018. Gridded Population of the World, Version 4 (GPWv4): Basic Demographic Characteristics, Revision 11. Palisades, NY: NASA Socioeconomic Data and Applications Center (SEDAC). https://doi.org/10.7927/H46M34XX. Accessed 22 October 2021."
+    },
+    "anc_bdc_mt_count": {
+      "title": "Basic Demographic Characteristics - Male Count",
+      "description": "Gridded Population of the World, Version 4 (GPWv4): Basic Demographic Characteristics - Male Count, 30 arc-seconds, 1km resolution",
+      "type": "image/tiff; application=geotiff; profile=cloud-optimized",
+      "roles": ["data"],
+      "sci:doi": "10.7927/H46M34XX",
+      "sci:citation": "Center for International Earth Science Information Network - CIESIN - Columbia University. 2018. Gridded Population of the World, Version 4 (GPWv4): Basic Demographic Characteristics, Revision 11. Palisades, NY: NASA Socioeconomic Data and Applications Center (SEDAC). https://doi.org/10.7927/H46M34XX. Accessed 22 October 2021."
+    },
+    "anc_bdc_mt_density": {
+      "title": "Basic Demographic Characteristics - Male Density",
+      "description": "Gridded Population of the World, Version 4 (GPWv4): Basic Demographic Characteristics - Male Density, 30 arc-seconds, 1km resolution",
+      "type": "image/tiff; application=geotiff; profile=cloud-optimized",
+      "roles": ["data"],
+      "sci:doi": "10.7927/H46M34XX",
+      "sci:citation": "Center for International Earth Science Information Network - CIESIN - Columbia University. 2018. Gridded Population of the World, Version 4 (GPWv4): Basic Demographic Characteristics, Revision 11. Palisades, NY: NASA Socioeconomic Data and Applications Center (SEDAC). https://doi.org/10.7927/H46M34XX. Accessed 22 October 2021."
+    },
+    "anc_land_area": {
+      "title": "Land Area",
+      "description": "Gridded Population of the World, Version 4 (GPWv4): Land Area, 30 arc-seconds, 1km resolution",
+      "type": "image/tiff; application=geotiff; profile=cloud-optimized",
+      "roles": ["data"],
+      "sci:doi": "10.7927/H4Z60M4Z",
+      "sci:citation": "Center for International Earth Science Information Network - CIESIN - Columbia University. 2018. Gridded Population of the World, Version 4 (GPWv4): Land and Water Area, Revision 11. Palisades, NY: NASA Socioeconomic Data and Applications Center (SEDAC). https://doi.org/10.7927/H4Z60M4Z. Accessed 22 October 2021."
+    },
+    "anc_water_area": {
+      "title": "Water Area",
+      "description": "Gridded Population of the World, Version 4 (GPWv4): Water Area, 30 arc-seconds, 1km resolution",
+      "type": "image/tiff; application=geotiff; profile=cloud-optimized",
+      "roles": ["data"],
+      "sci:doi": "10.7927/H4Z60M4Z",
+      "sci:citation": "Center for International Earth Science Information Network - CIESIN - Columbia University. 2018. Gridded Population of the World, Version 4 (GPWv4): Land and Water Area, Revision 11. Palisades, NY: NASA Socioeconomic Data and Applications Center (SEDAC). https://doi.org/10.7927/H4Z60M4Z. Accessed 22 October 2021."
+    },
+    "anc_nat_id_grid": {
+      "title": "National Identifier Grid",
+      "description": "Gridded Population of the World, Version 4 (GPWv4): UN WPP-Adjusted Population Density, 30 arc-seconds, 1km resolution",
+      "type": "image/tiff; application=geotiff; profile=cloud-optimized",
+      "roles": ["data"],
+      "sci:doi": "10.7927/H4TD9VDP",
+      "sci:citation": "Center for International Earth Science Information Network - CIESIN - Columbia University. 2018. Gridded Population of the World, Version 4 (GPWv4): National Identifier Grid, Revision 11. Palisades, NY: NASA Socioeconomic Data and Applications Center (SEDAC). https://doi.org/10.7927/H4TD9VDP. Accessed 22 October 2021."
+    }
+  },
+  "title": "Gridded Population of the World (GPW) v4.11, Ancillary Datasets",
+  "extent": {
+    "spatial": {
+      "bbox": [[-180.0, 90.0, 180.0, -90.0]]
+    },
+    "temporal": {
+      "interval": [["2010-01-01T00:00:00Z", "2011-01-01T00:00:00Z"]]
+    }
+  },
+  "license": "CC-BY-4.0",
+  "providers": [
+    {
+      "name": "Center for International Earth Science Information Network - CIESIN - Columbia University",
+      "roles": ["producer", "processor", "host"],
+      "url": "https://sedac.ciesin.columbia.edu/data/set/gpw-v4-population-count-rev11"
+    }
+  ]
+}