Exports¶

This page tells you how to get data and reports out of LUC Analytics (LUCA), and when each export is not available.

In this page, a control or a label of the app is in bold. A message of the app is in "double quotes".

Summary of exports¶

Export	Where the control is	Format	File name
List results, post-2020	The ⋯ menu of the list on the lists page, item Export	CSV	`<list name> - post2020.csv`
List results, post-2020	The POST-2020 RISK ASSESSMENT tab of a list, button ⬇ Download CSV	CSV	`<list name> - post2020.csv`
List results, alerts	The RECENT DISTURBANCE ALERTS tab of a list, button ⬇ Download CSV	CSV	`<list name> - alerts.csv`
One location	The Location Details panel, button ⬇ Download CSV	CSV	`<list name> - location <id> detail.csv`
One location report	The Location Details panel, button Download PDF	PDF	`location-<id>-report.pdf`
Data used	Comes with each CSV export, as a second file	CSV	`<CSV name>.data-used.csv`
Map key template	The map key, Saved map templates, button Save	`.mpky` (JSON)	`mapkey_0001.mpky` or the name that you type

If the list name gives no usable file name, the app uses the list ID, for example list-<list id>-post2020.csv or location-<id>-detail.csv. The app replaces characters that Windows, macOS or Linux do not permit in a file name.

When an export is available¶

The browser and the server each do a check before an export. The two checks use the same rule:

An export of a full list is available only when the analysis of the list is complete.
An export of one location is available only when the analysis of that location is finished.

Export	Necessary condition
List CSV and its data-used file (Export and the two ⬇ Download CSV buttons)	The status of the list is complete. Before that, the tooltip shows "CSV export becomes available once the analysis of this list is complete."
Location CSV and its data-used file	Each analysis of the list is finished for that location.
Location PDF	The post-2020 analysis of that location is finished. The map must also be ready to capture.

These are the results of the checks:

You cannot export the CSV of a list that is not complete. A list with the label Incomplete (for example, after Halt & commit) stays in this condition. For such a list, export each finished location.
You can download the CSV or the PDF of a finished location. The other locations of the list do not have to be finished.
The PDF of a location in a list that is not complete has a note, for example "Report generated from a partially-analyzed list — 40/50 locations analyzed (80%)". If the app cannot count the locations, the note is "Report generated from a partially-analyzed list — number of locations analyzed could not be confirmed".
The app does not write a zero in place of a value that it did not calculate. There is no override for these checks.

If the server refuses an export, the app shows one of these messages:

"Export unavailable — no locations have been analyzed for this list yet, so there is nothing to export."
"CSV export becomes available once the analysis of this list is complete."
"Export unavailable — this location’s analysis has not finished. Export becomes available once every analysis for it is complete."
"PDF export unavailable — no locations have been analyzed for this list yet."

For more information about analysis states, see 03-analysis-and-results.md.

Export the results of a list as CSV¶

You can start the post-2020 export from the lists page or from the list. The two controls give the same file.

From the lists page:

Go to the lists page (Lists).
On the row of the list, push ⋯.
Select Export.

From the list:

Open the list.
Select the POST-2020 RISK ASSESSMENT tab or the RECENT DISTURBANCE ALERTS tab.
If you use the alerts tab, set the alert dates on the Alerts date chip. The CSV uses the same dates.
Push ⬇ Download CSV.

The browser downloads two files: the CSV and its data-used file. For the data-used file, see "The data-used file" below.

Contents of the post-2020 CSV¶

The CSV has one row for each location. The columns are:

The identity of the location: location_id, location_name, load_order, status, centroid_lat, centroid_lon.
The analysis date and dataset version: post2020_analysis_date, post2020_dataset_version.
The areas in hectares: total_area_ha, sbtn_area_ha, jrc_area_ha, and the flags sbtn_flag and jrc_flag.
The loss after 2020 for each forest basemap: sbtn_loss_ha_post2020, jrc_loss_ha_post2020. There is also one column for each loss year, for example sbtn_loss_ha_2021.
The drivers of tree cover loss: one driver_<name>_ha column for each driver. Then dominant_driver, dominant_share, dominant_is_mixed and dominant_is_none.
The errors: error_code and explanation.
The state: finished_state, list_status, list_locations_computed, list_locations_total.

Contents of the alerts CSV¶

The alerts CSV has one row for each location. It has the same identity, area, error and state columns as the post-2020 CSV. It also has these columns: alerts_analysis_date, alerts_dataset_version, alert_area_ha, alert_sbtn_area_ha, alert_jrc_area_ha, window_start and window_end. The two window columns show the dates of the alerts that the file counts.

Export one location as CSV¶

Open the list.
On the row of the location, push DETAILS. The Location Details panel opens.
Push ⬇ Download CSV.

The CSV has one row. It contains the identity, area, loss and driver columns of the post-2020 CSV, and the alerts columns of the alerts CSV. It also contains the annotation column, which is your note about the location. The browser also downloads the data-used file for that location.

Download a PDF report of one location¶

Open the list.
On the row of the location, push DETAILS.
Wait until the map in the Location Details panel is fully drawn.
Push Download PDF.

Before the app makes the PDF, it waits for the basemap tiles and the analysis layers. If they are not ready, the app does not make the file. It shows a message that tells you the cause. For example: "PDF export unavailable — still waiting for: basemap tiles loading (6 of 9 loaded). Please wait and try again."

The PDF is in landscape. It contains these items:

A title: the name and the ID of the location.
A note, only if the list is not complete. The note gives the number of finished locations. Refer to "When an export is available" above.
Two map images: "Boundary on basemap" and "Boundary + active analysis layers on basemap".
"Layer settings used for these images". This part gives the color and opacity of each layer, the loss years, the alert dates and the map resolution.
The details of the location: the name, the area and your notes.
The table of forest loss for each year, for the SBTN basemap and the JRC basemap.
The alerts, if the list has the alerts analysis.
The drivers of tree cover loss, as a pie chart with a legend. If there are no driver data, the PDF says so.
"Data used": the datasets and their versions.
"How to cite the data": the attribution text.

NOTE: The map images can be larger than on the screen. Then the PDF tells you the scale, for example "Map panels scaled ×2.00 from on-screen resolution for this report."

For the map controls that change the images, see 04-maps.md.

The data-used file¶

Each CSV export comes with a second file. Its name is the CSV name with .data-used.csv in place of .csv. It contains one row for each source dataset, with these columns: dataset, version_id, date, date_kind, local_or_s3, profile, currency_at_run, hash, location.

If the analysis ran before the app recorded dataset dates, the file has one row with the text vintage not recorded.

The CSV can download when the data-used file does not. Then the app shows "The CSV downloaded, but its Data-used sidecar file (the source dataset dates) could not be downloaded." Push the button again to get the two files.

Format of the CSV files¶

The text is UTF-8 with a byte order mark. The lines end with CR LF.
The first lines are the attribution text. Each of these lines starts with #. The header row of the table comes after them.
Numbers have no thousands separator. Areas have a maximum of 4 decimal places.
A cell is empty when the app has no value for it, for example a location with an error. The app does not write a zero in place of a value that it did not calculate.

NOTE: If a text cell starts with =, +, -, @ or a tab, the app puts ' before the text. Thus, a spreadsheet program does not read the text as a formula.

To read the table in a program, tell the program to skip lines that start with #. For example, in pandas, use read_csv(..., comment="#").

Attribution and licenses¶

The "Special Terms of Use for GNW Self-Hosted Monitoring" of WRI apply to the data. You must attribute the data when you share an output. You must not suggest that WRI endorses, sponsors, certifies or approves you or your use of the data.

The app adds the attribution text to each CSV export and to each PDF report. The text has these parts:

The GNW citation, with the access date: "Global Nature Watch. [year]. World Resources Institute. Accessed on [date]." The access date is the date when the last run of the list finished.
The citation of each dataset that the export uses, with its license.
"Computed with LUC Analytics, an independent project, using methods adapted from WRI's published scripts (post2020.py, GNW Self-Hosted Monitoring). WRI does not endorse this project or its results."
"Use of these data is subject to WRI's Special Terms of Use for GNW Self-Hosted Monitoring: https://www.wri.org/about/legal/gnw-shm-tos"

The datasets in each export are:

Export	Datasets
Post-2020 CSV	Tree cover loss, SBTN Natural Forest, JRC Global Forest Cover 2020, Dominant Drivers of Forest Loss
Alerts CSV	Global Integrated Disturbance Alerts, SBTN Natural Forest, JRC Global Forest Cover 2020
Location CSV and location PDF	All five datasets above

The licenses are:

License	Datasets
CC BY 4.0	Tree cover loss, SBTN Natural Forest, Dominant Drivers of Forest Loss, Global Integrated Disturbance Alerts
Free of charge, without restriction of use (Copernicus Regulation of the European Commission)	JRC Global Forest Cover 2020

For a list with synthetic demo data, the attribution text is different. It says "Synthetic demo data generated by LUC Analytics. No WRI dataset was read for these figures."

To read the attribution text in the app, push Data sources and licenses at the bottom of the page. The full text is in the file DATA-ATTRIBUTION.md in the project repository.

CAUTION: Keep the attribution lines when you copy data from a CSV into a different file. If you remove them, the new file does not tell readers the source and the license of the data.

Save a map key template¶

A map key template keeps the map layer settings in a file, so that you can use them again. It is not a results export.

In the map key, find Saved map templates.
Type a name in File name, or keep the default name.
Push Save.

The file is a JSON document with the extension .mpky. To use the file again, push Load…. For more information, see 04-maps.md.

Command line export¶

The program also has the command luc-analytics export for administrators. It writes the CSV of a list (--analysis post2020 or --analysis alerts) or of one location (--analysis detail --location-id <id>). The arguments --start and --end set the alert dates. The argument --output sets the file. Without --output, the command writes to the standard output.

The command uses the same checks as the app. For a whole list, the list must be complete. For a single location, that location must be finished. If the check fails, the command writes no file. It shows a message that starts with export_refused: and stops with exit code 1. The command does not write the data-used file.