Merge pull request #19 from openearthplatforminitiative/feat/text-abo…

…ut-flood-api

feat: add flood description and examples

app/code-examples/flood-detailed.js

@@ -0,0 +1,13 @@
+const response = await fetch(
+  'https://api-test.openepi.io/flood/summary?' +
+    new URLSearchParams({
+      lon: '33.575897',
+      lat: '-1.375532',
+    })
+);
+const json = await response.json();
+
+// Get the minimum forecasted discharge
+const minDischarge = json.queried_location.features[0].properties.min_dis;
+
+console.log(`Minimum forecasted discharge: ${minDischarge}`);

app/code-examples/flood-detailed.py

@@ -0,0 +1,13 @@
+from httpx import Client
+
+with Client() as client:
+    response = client.get(
+        url="https://api-test.openepi.io/flood/detailed",
+        params={"lon": 33.575897, "lat": -1.375532},
+    )
+
+    # Get the minimum forecasted discharge
+    json = response.json()
+    peak_day = json["queried_location"]["features"][0]["properties"]["min_dis"]
+
+    print(f"Minimum forecasted discharge: {peak_day}")

app/code-examples/flood-summary.js

@@ -0,0 +1,13 @@
+const response = await fetch(
+  'https://api-test.openepi.io/flood/summary?' +
+    new URLSearchParams({
+      lon: '33.575897',
+      lat: '-1.375532',
+    })
+);
+const json = await response.json();
+
+// Get the forecasted peak day
+const peakDay = json.queried_location.features[0].properties.peak_day;
+
+console.log(`Forecasted peak day: ${peakDay}`);

app/code-examples/flood-summary.py

@@ -0,0 +1,13 @@
+from httpx import Client
+
+with Client() as client:
+    response = client.get(
+        url="https://api-test.openepi.io/flood/summary",
+        params={"lon": 33.575897, "lat": -1.375532},
+    )
+
+    # Get the forecasted peak day
+    json = response.json()
+    peak_day = json["queried_location"]["features"][0]["properties"]["peak_day"]
+
+    print(f"Forecasted peak day: {peak_day}")

app/code-examples/flood-threshold.js

@@ -0,0 +1,13 @@
+const response = await fetch(
+  'https://api-test.openepi.io/flood/threshold?' +
+    new URLSearchParams({
+      lon: '33.575897',
+      lat: '-1.375532',
+    })
+);
+const json = await response.json();
+
+// Get the 2-year return period threshold
+const threshold2y = json.queried_location.features[0].properties.threshold_2y;
+
+console.log(`2-year return period threshold in m^3/s: ${threshold2y} m^3/s`);

app/code-examples/flood-threshold.py

@@ -0,0 +1,13 @@
+from httpx import Client
+
+with Client() as client:
+    response = client.get(
+        url="https://api-test.openepi.io/flood/threshold",
+        params={"lon": 33.575897, "lat": -1.375532},
+    )
+
+    # Get the 2-year return period threshold
+    json = response.json()
+    threshold_2y = json["queried_location"]["features"][0]["properties"]["threshold_2y"]
+
+    print(f"2-year return period threshold: {threshold_2y} m^3/s")

app/data-catalog/flood/page.tsx

@@ -23,20 +23,30 @@ const Home = () => {
 
       <Box className={'flex flex-col gap-8 mt-14'}>
         <Typography className={'text-5xl'}>Flood API</Typography>
-        <Typography className={'text-2xl'}>Sub header</Typography>
+        <Typography className={'text-2xl'}>
+          Flood forecasting based on the{' '}
+          <a
+            href={'https://www.globalfloods.eu/'}
+            className={'underline hover:no-underline'}
+          >
+            Global Flood Awareness System (GloFAS)
+          </a>
+        </Typography>
       </Box>
       <Box className={'flex lg:flex-row flex-col gap-6 mt-20'}>
         <InfoCard
           externalLink={true}
           header={'OpenAPI Spec'}
-          subHeader={'Some text about the OpenAPI spec.'}
+          subHeader={
+            'Specification of all endpoints available in the flood api.'
+          }
           CardIcon={OpenApiIcon}
           href={'https://api-test.openepi.io/flood/redoc'}
         />
         <InfoCard
           externalLink={true}
           header={'Github'}
-          subHeader={'Some text about the Github repository.'}
+          subHeader={'Explore the source code behind the flood api.'}
           CardIcon={GithubIconBlack}
           href={'https://github.com/openearthplatforminitiative/flood-api'}
         />
@@ -45,40 +55,101 @@ const Home = () => {
         <Typography className={'text-4xl'}>More info</Typography>
         <Typography className={'text-3xl mt-8'}>Data sources</Typography>
         <Typography className={'text-base mt-6'}>
-          There is a need for a robust and accessible digital infrastructure for
-          open data and algorithms on weather, water, earth, and vegetation,
-          across projects, sectors, and contexts – providing a base for the
-          necessary local technology innovation. The Open Earth Platform
-          (OpenEPI) is an initiative to prepare for such an infrastructure.
-        </Typography>
-        <Typography className={'text-3xl mt-14'}>Methods</Typography>
-        <Typography className={'text-base mt-6'}>
-          There is a need for a robust and accessible digital infrastructure for
-          open data and algorithms on weather, water, earth, and vegetation,
-          across projects, sectors, and contexts – providing a base for the
-          necessary local technology innovation. The Open Earth Platform
-          (OpenEPI) is an initiative to prepare for such an infrastructure.
+          Part of the data for this Flood API consists of the 30-day forecasted
+          river discharge data retrieved on a daily basis from the Copernicus{' '}
+          <a
+            href={
+              'https://cds.climate.copernicus.eu/cdsapp#!/dataset/cems-glofas-forecast?tab=overview'
+            }
+            className={'underline hover:no-underline'}
+          >
+            Climate Data Store (CDS)
+          </a>
+          . Upstream area data was retrieved from the{' '}
+          <a
+            href={
+              'https://confluence.ecmwf.int/display/CEMS/Auxiliary+Data#AuxiliaryData-GloFASAuxiliaryData'
+            }
+            className={'underline hover:no-underline'}
+          >
+            auxilairy data page
+          </a>{' '}
+          of the Copernicus Emergency Management Service (CEMS). Additionally,
+          return period threshold data was obtained directly from the GloFAS
+          team, but this will soon be made available through the CDS as well.
+          All the data is on a global scale with resolution 5° by 5° and is
+          licensed under the{' '}
+          <a
+            href={
+              'https://cds.climate.copernicus.eu/api/v2/terms/static/cems-floods.pdf'
+            }
+            className={'underline hover:no-underline'}
+          >
+            CEMS-FLOODS datasets licence
+          </a>
+          .
         </Typography>
         <Typography className={'text-3xl mt-14'}>Processing</Typography>
         <Typography className={'text-base mt-6'}>
-          There is a need for a robust and accessible digital infrastructure for
-          open data and algorithms on weather, water, earth, and vegetation,
-          across projects, sectors, and contexts – providing a base for the
-          necessary local technology innovation. The Open Earth Platform
-          (OpenEPI) is an initiative to prepare for such an infrastructure.
+          The forecasted river discharge data is processed in order to obtain
+          the summary and detailed forecasts. The summary forecast corresponds
+          to the GloFAS{' '}
+          <a
+            href={
+              'https://confluence.ecmwf.int/display/CEMS/GloFAS+Reporting+Points'
+            }
+            className={'underline hover:no-underline'}
+          >
+            Reporting Point
+          </a>{' '}
+          structure, which defines a flood&apos;s intensity, tendency, and peak
+          timing over the 30-day forecast horizon for each grid cell. In GloFAS,
+          each reporting point is associated with a discharge hydrograph, which
+          makes up the detailed forecast provided by the API. The detailed
+          forecast provides, for each day of the forecast horizon, values such
+          as the five-number summary of the discharge distribution, as well as
+          the probabilities of exceeding the 2-, 5-, and 20-year return period
+          thresholds.
+          <br />
+          <br />
+          In our processing pipeline, we first determine the detailed forecast
+          by computing simple statistics at each day of the forecasted discharge
+          data, making use of the GloFAS return period threshold data. Then, we
+          compute the summary forecast by aggregating the detailed forecast data
+          over the forecast horizon. Similarly to GloFAS, the upstream area data
+          is used to filter out grid cells that have an upstream area smaller
+          than 250 km<sup>2</sup>. Currently, the region of interest is limited
+          to the following bounding box covering parts of Western, Central, and
+          Eastern Africa: -18.0° to 52.0° longitude and -6.0° to 17.0° latitude.
         </Typography>
         <Typography className={'text-4xl mt-16'}>Examples</Typography>
         <Typography className={'text-3xl mt-8'}>Example 1</Typography>
         <Typography className={'text-base mt-6'}>
-          There is a need for a robust and accessible digital infrastructure for
-          open data and algorithms on weather, water, earth, and vegetation,
-          across projects, sectors, and contexts – providing a base for the
-          necessary local technology innovation. The Open Earth Platform
-          (OpenEPI) is an initiative to prepare for such an infrastructure.
+          Retrieving the peak day of the summary forecast for the 5° by 5° grid
+          cell that the given coordinates fall into using JavaScript.
+        </Typography>
+        <CodeBlock
+          language={'javascript'}
+          codeString={getCodeExample('flood-summary.js')}
+        />
+        <Typography className={'text-3xl mt-8'}>Example 2</Typography>
+        <Typography className={'text-base mt-6'}>
+          Retrieving the minimum forecasted discharge of the first day of the
+          detailed forecast for the 5° by 5° grid cell that the given
+          coordinates fall into using Python.
+        </Typography>
+        <CodeBlock
+          language={'javascript'}
+          codeString={getCodeExample('flood-detailed.py')}
+        />
+        <Typography className={'text-3xl mt-8'}>Example 3</Typography>
+        <Typography className={'text-base mt-6'}>
+          Retrieving the 2-year return period threshold for the 5° by 5° grid
+          cell that the given coordinates fall into using JavaScript.
         </Typography>
         <CodeBlock
           language={'javascript'}
-          codeString={getCodeExample('flood.js')}
+          codeString={getCodeExample('flood-threshold.js')}
         />
       </Box>
     </Box>