Lists of locations¶

This page tells you how to make, change and delete a list of locations.

A list contains one or more locations, for example farms or plots. The app analyzes each location in a list. To read the results, see 03-analysis-and-results.md.

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

The lists page¶

The lists page has the title Location Lists. It shows a table with one row for each list.

The table has these columns:

Name: the name of the list. Select the name to open the list.
Locations: the number of locations in the list.
Commodity: the commodity that you gave for the list. If you gave no commodity, the cell shows "—".
Analyses: the analyses that the app did for the list.
Last Processed: the date of the last analysis.
Created: the date that you made the list.
Actions: the menu for the list (⋯).

To sort the table, push a column heading. Push the same heading again to change the sort direction.

To find a list, type a part of its name or commodity in the search box (Search lists by name or commodity…). If no list agrees with your text, the table shows "No lists match "…"". If you have no lists, the page shows "No lists found".

Labels in the table¶

Incomplete: the analysis did not finish for all locations in the list. Put the pointer on the label to see the number of locations that the app analyzed.
Newer data available: a dataset that the list used changed after the last analysis. Refer to "Update a list" below.
Updating: an update of the list is in progress. The table shows the results of the previous analysis until the update is complete.

Uploads that are not complete¶

If an upload is not complete, a banner shows at the top of the lists page. Push Resume to go back to the upload. If the upload waits for your review, push Review.

Make a new list¶

To start, push + New list on the lists page. The page Create a new list comes into view.

The page asks How do you want to add locations?. Select one of these two methods:

Upload a set of locations: upload a file that holds one or more locations. This is the default method.
Manually add a single location: type the coordinates of one location.

NOTE: Change from one method to the other only before you start. When you change the method, the app clears the values that you typed for the other method.

NOTE: If the app shows "Uploads are disabled", the server configuration stops all uploads. A new Docker install lets you upload files. An install that you upgraded keeps its old configuration file. Refer to 01-install-and-start.md.

Accepted file types¶

The app accepts these file types:

File type	File name extension
CSV	.csv
Excel workbook	.xlsx
GeoJSON	.geojson or .json
KML	.kml
Zipped shapefile	.zip

The app does not accept other file types. For example, it does not accept KMZ (.kmz) files or old Excel (.xls) files. If you upload a different file type, the app shows "Unsupported file type". To use a KMZ file, extract the KML file from the KMZ file. Then upload the KML file.

CSV and Excel files¶

A CSV or Excel file holds one location in each row. The first row must hold the column headings. For an Excel workbook, the app reads only the first worksheet.

Each row must have a latitude and a longitude in decimal degrees. Latitude must be between -90 and 90. Longitude must be between -180 and 180.

The app finds the columns from their headings. It recognizes these headings. It ignores upper case, lower case, spaces, hyphens and underscores:

Latitude: latitude, lat, y, ycoord, ylat.
Longitude: longitude, lon, lng, long, x, xcoord, xlon.
Name of the location: name, id, plotid, locationid, locationname, plot.

The name column is optional. A CSV or Excel file with latitude and longitude columns holds points. Because of this, you must give a size for each point. Refer to "Size for point locations" below.

The app can also read a polygon from a column with the heading geometry, geom, wkt, thegeom or shape. This column must hold the shape as WKT text, for example POLYGON((...)).

GeoJSON, KML and shapefile files¶

These file types hold the shape of each location in the file. The page shows "Geometry will be read from the file itself." You do not set the coordinate columns for these files.

A zipped shapefile is one .zip file that holds the shapefile parts (.shp, .shx, .dbf and, if you have it, .prj). The .zip file must hold a .shp file. It must not hold more than 256 files.

Points and polygons¶

A location can be a polygon or a point.

A polygon shows the boundary of the location. The app analyzes the area in the boundary.
A point is one GPS position. To analyze an area around a point, the app must know the size of the area. The app then makes a circle around the point.

A file can hold points and polygons together. A size has an effect only on the points.

Upload a file¶

Push Choose file.
Select the file on your computer.
Make sure that the page shows the correct name after Selected file.
Optional: type a name in List name. If you do not type a name, the app uses the file name.
Optional: type a commodity in Commodity, for example "cocoa".
Examine the section Check the field mapping. Refer to "Match the columns" below.
If the file holds points, give a size. Refer to "Size for point locations" below.
Push Upload & analyze.

NOTE: The Upload & analyze button is not available until the page has all necessary data. Read the messages on the page to find what is necessary.

Match the columns¶

After you select a file, the app matches the columns in your file to the data that it needs. If the app is sure of all matches, it shows "We matched the columns in your file to the fields we need. Check them before analyzing."

To see or change the matches, push Change field mapping. The table has these columns:

We need: the data that the app needs, for example Latitude (north–south) and Longitude (east–west).
Column in your file: the column that holds this data. If the match is not correct, select a different column.
Example values: values from your file.
How it was matched: for example Matched by name, Matched a known alias or You chose this.

If the app is not sure of a match, the label check this one shows next to it. Examine that match before you continue.

If some latitude or longitude examples are out of range, the app shows a warning. For example: "Some latitude examples are outside −90 to 90. Check this mapping." This usually means that the latitude and longitude columns are in the wrong positions. Select the correct columns.

If a necessary field has no column, the app shows "Map required fields before continuing:" and the names of the fields. Select a column for each field.

When all necessary fields have a column, the app shows "All required fields matched".

If the app cannot read the columns, it shows "We couldn’t load field mapping for this file." Push Retry. You can also push Upload & analyze without a check of the columns.

Size for point locations¶

If the file holds latitude and longitude columns, the app shows How big is each location?. You must give a size before you can upload.

For a GeoJSON, KML or shapefile file, the size is optional. Push Show size options to give a size. If the file holds points and you do not give a size, the app does not make circles. Each location stays a point.

CAUTION: Make sure that you select Area or Radius correctly. If you select the wrong one, the circle has the wrong size and the results are not correct.

At How is each location sized?, select one of these two values:
All rows the same: one value for all points.
From a column in the file: each row has its own value in a column.
At Is this an area or a radius?, select Area or Radius.
If you selected All rows the same, type the value in Value.
If you selected From a column in the file, select the column in Column.
Optional: to analyze a ring around each location, select Add a buffer ring around each location.
If you selected the buffer ring, type the width of the ring in Buffer.

The units are:

Size	Unit	Limits
Area	hectares (ha)	More than zero.
Radius	kilometers (km)	At least 0.001 km (1 m). Not more than 500 km.
Buffer	meters (m)	A whole number, at least 1 m. Not more than 500,000 m.

The app tells you the result of the size. For example: "circle 1.00 ha → radius ≈ 56.4 m". The app does not guess the unit or the type of size from a column name.

NOTE: The buffer ring does not include the location itself. The app analyzes only the ring around the location. A buffer ring has an effect on polygons and on points.

Map projection¶

The app must have coordinates in WGS 84 latitude and longitude. If the coordinates look like a projected map, the app shows Which map projection?. Then do these steps:

At Which projection does this file use?, select the projection of your file. The app can show a projection with the text suggested (matches your coordinates).
Push Upload & analyze again.

The app uses your selection only for this upload. You can select one of these projections: EPSG:4326, OGC:CRS84, EPSG:3857 and EPSG:24818.

Analysis and review¶

After you upload the file, the app analyzes each location. The page shows "Analyzing upload…" and the number of locations that the app analyzed.

While the analysis is in progress, you can do one of these actions:

Push Cancel to stop the upload. The app does not keep the list.
Push Halt & commit to stop the analysis. The app keeps only the locations that it analyzed. If the app did not analyze all locations, the list has the label Incomplete.

When the analysis is complete, the page Review analyzed records comes into view. It shows the number of Locations, Analyzed OK and Errors. The table shows each location with its Status. For a location with the status Error, the Explanation column tells you the cause.

Examine the table.
To keep the list, push Commit list.
To not keep the list, push Discard.

When the app saves the list, the page List created comes into view. Push View list to open the list, or push ← Back to lists.

Add one location manually¶

Select Manually add a single location.
Type a name in Name. The app uses this name for the list and for the location.
At How will you define the location?, select Single GPS point or Polygon boundary (3 or more points).
Type the coordinates. Refer to the steps below.
Push Create location.

For a point, do these steps:

Type the Latitude and the Longitude in decimal degrees (WGS 84).
At Is this an area or a radius?, select Area or Radius.
Type the size value.

For a polygon, do these steps:

Type the latitude and the longitude of each boundary point. The page starts with three points.
To add one more point, push Add point.
To remove a point, push Remove point for that point. A polygon must keep at least three points.

You do not type the first point again at the end. The app closes the boundary automatically.

The app then analyzes the location in the same way as an uploaded file.

Error messages¶

If the upload fails, the page shows an error title, a cause and an action. To see the technical data, push Technical details.

Error title	Cause	Action
"Unsupported file type"	The app does not accept this file type.	Upload a CSV, .xlsx, GeoJSON, KML or .zip shapefile file.
"File too large"	The file is larger than 10 MiB (10,485,760 bytes), or the .zip file holds more than 256 files.	Divide the file into smaller files. Upload each file as a list.
"Spreadsheet too wide"	A row of the Excel file has more than 512 columns.	Remove the columns that you do not need.
"Too many locations"	The file has more than 5,000 locations.	Divide the file into smaller files. Upload each file as a list.
"No locations found"	The file has no rows of data.	Make sure that the file has rows.
"Archive couldn’t be opened"	The .zip file is damaged, or it has no .shp file.	Export the file again. Upload it again.
"We couldn’t find the location columns"	The app cannot find the coordinate columns.	Set the column matches. Upload again.
"That column isn’t in your file"	The column matches use a column that is not in the file.	Examine the column matches.
"No valid locations"	No location in the file has valid coordinates.	Examine the coordinates.
"KML/KMZ couldn’t be read"	The KML file is not a valid KML file.	Export the file again. Upload it again.
"Locations need a size"	The file has only points and no size.	Give a size for the points.
"Choose a unit"	A size has no unit.	Select Area or Radius.
"Column not found"	The size column is not in the file.	Make sure that the column heading is correct.
"Size value can’t be used"	Some size values are empty, zero or too large.	Examine the size values in those rows.
"Which map projection?"	The coordinates are not WGS 84 latitude and longitude.	Select the projection of the file.
"Projection not recognized"	The app cannot use the projection for this file.	Select a different projection.
"Upload expired"	You did not commit the upload in time.	Upload the file again.
"Upload interrupted"	The upload stopped before it was complete.	Upload the file again.
"Can’t reach the server"	The app cannot connect to the server.	Make sure that the container runs. Then try again.

NOTE: The limits of 10 MiB, 512 columns and 5,000 locations are the default values. The server configuration can change them.

NOTE: An error in one location does not stop the upload. The review table shows the locations that have an error.

For more problems and their corrective actions, see 07-troubleshooting.md.

Rename a list¶

On the lists page, push ⋯ in the row of the list.
Select Rename.
Type the new name.
Push Enter to save the name, or push Esc to cancel.

The name can have a maximum of 200 characters. An empty name does not change the list. If the app cannot save the name, it shows "Rename failed".

Delete a list¶

WARNING: Make sure that you select the correct list. You cannot restore a list after you delete it.

On the lists page, push ⋯ in the row of the list.
Select Delete.
In the confirmation message, push OK.

If the app cannot delete the list, it shows "Delete failed" and keeps the list.

Update a list¶

You cannot add locations to a list or remove locations from a list. To use a different group of locations, make a new list.

You can analyze a list again with the current datasets. Use this action when the list has the label Newer data available.

WARNING: Read the cost before you push Run again. If the dialog shows "Read from WRI online, billed to your AWS account", the analysis causes a charge to your AWS account. You must select I understand this run is billed to my AWS account. before you push Run again.

On the lists page, push ⋯ in the row of the list.
Select Run again with current data.
Read the datasets that changed after the last analysis.
At How should the new run be applied?, select one of these two values:
Update this list: the app replaces the results of the list. The name, notes and dates of the list stay the same.
Create a new copy: the app makes a new list with the same locations. The initial list does not change.
Push Run again.

If the update fails, the app keeps the previous results. You can also start this action from the page of the list. For more data about costs, see 03-analysis-and-results.md.

The ⋯ menu also has Export. Export downloads the results of the list as a CSV file. You can push Export only when the analysis of the list is complete. For exports, see 05-exports.md.