This vignette will demonstrate how to use maplandscape to explore cropping systems and agricultural landscapes on the island group of Vava’u, Tonga, in the Pacific Ocean. It will provide a comprehensive overview of maplandscape’s features and how to navigate around the user interface.
A copy of the data to use for this vignette is available here.
This is a demo dataset of crop survey data collected by the Ministry of Agriculture, Food, Forests, and Fisheries, Government of Tonga, using QField mobile GIS. It is a GeoPackage file, which is a file-based relational database containing a spatial table storing field outlines as geometry objects and a number of non-spatial tables storing attributes about cropping practices in each field.
You’ll also need a copy of the village boundaries for Vava’u, which is available here.
The goal of this vignette is to:
Along the way you will learn how to use a range of data processing and GIS operations in maplandscape to perform custom analyses, extract insights from geospatial data, and generate outputs for reporting and decision making.
Kava is a shrub plant that is harvested for its roots which are used to make a drink which has sedative and anesthetic effects. It is a destructive harvest with the entire shrub pulled out of the ground to access the roots. This exposes and disturbs the soil, which increases the risk of soil erosion during intense rain events that are common in Vava’u. In recent years, in response to market demand, large areas of Vava’u have been allocated to kava cultivation. This is at the expense of crops that are important for food security and tree cover. Landscape managers in Vava’u are keen to track changes in cropping systems and have access to accurate data on the state of kava cultivation to guide landscape management activities.
Head to a live version of maplandscape here. Or, if you’re familiar with docker you can build and run it locally.
git clone https://github.com/livelihoods-and-landscapes/maplandscape.git cd maplandscape cd /inst/docker docker build -t maplandscape . docker run -p 3838:3838 maplandscape
The image below is a screen grab of the maplandscape user interface highlighting the main widgets and tools to be aware of. In particular, take note of the navbar at the top of the screen that lets you move between tabs for exploring your data in table, web map, or chart formats.
Let’s start by loading the demo crop survey data (in demo-crop-survey.gpkg that you downloaded earlier) into maplansdcape. Head to the sidebar in the Data tab and look for the Upload Data section. Click Browse and scroll to where you downloaded demo-crop-survey.gpkg and load it into maplandscape. You can also drag and drop demo-crop-survey.gpkg onto the white box next to the Browse button. If all goes well, you should see a green progress bar beneath the upload widget and then a small success message.
Once the file has been uploaded, it will unpack the layers in the GeoPackage and make them available to you under the Active Layer section at the top of the sidebar. You should see layer names such as pumpkin (demo-crop-survey)_1, tobacco (demo-crop-survey)_1, and so on. The layer names have the format of layer name (GeoPackage name)_layer index. The layer index is a numeric index to help you keep track of layer-GeoPackage combinations in case you load two GeoPackages with the same structure into the app.
You should see the selected layer rendered in the data table display in the main panel. Explore changing the selected Active layer and seeing a new layer rendered in the data table display (e.g. select the kava (demo-crop-survey)_1 layer and you should see column headers for akau_hina, akau_kula, and leka_hina which correspond to kava varieties).
Keep the layer kava (demo-crop-survey)_1 selected. Let’s explore some of the tools in the data table display for exploring your data. The kava_area column records the proportion of a field that is cultivated with kava. Let’s sort our data by kava_area. Next to the kava_area column header you should see and up and a down arrow. Clicking on these arrows will sort the rows in the table by the values in these columns.
If you scroll to the bottom of the table, you can see that the first 10 rows of the table are displayed. You can scroll through the rows using the numbers or the Previous and Next buttons.
You can also choose to display more records in the table using the Show XX entries selector.
You can also use the Search widget to search for matching records in the table. For example, if we start typing
gt_2 into the Search bar all records in the kava table with kava_growth_stage equal to
gt_2 will be rendered.
We can also explore spatial layers in a GeoPackage on a web map. Head to the Map tab in the navbar. Your Map display should look like the below image. There sidebar contains widgets that can be used to style data that is rendered on the web map.
There is only one spatial layer in the demo-crop-survey.gpkg GeoPacakge - the plot-boundary (demo-crop-survey)_17 layer. Under the Select active layer selector choose plot-boundary (demo-crop-survey)_17 and let’s map the area of each polygon to a fill colour palette - under Select variable select area_acres. Let’s choose the red - yellow - green Fill colour palette. When you have made these selections, click the draw map button at the top of the sidebar. This should render the plot-boundary (demo-crop-survey)_17 layer on the web map in the main panel. All going well, your map display should look like the below image. If any of the features look funky, they’ve been jittered and distorted from the actual field geometries collected using QField.
Often, data that’s collected in-the-field needs to be processed and transformed (data wrangling) before it’s ready for visualising, reporting, or providing insights that are relevant for decision making. maplandscape provides a range of tools for processing and transforming your spatial and non-spatial layers in a GeoPackage.
As we stated at the beginning, we’re interested in exploring kava-dominant cropping systems here. Head to the Data tab and select kava (demo-crop-survey)_16 as the Active layer. This is a non-spatial layer (the Geometry object is empty). We want to attach the attributes about kava cultivation in the kava (demo-crop-survey)_16 layer to a layer that stores the geometries for fields.
The plot-boundary (demo-crop-survey)_17 layer is a spatial table with field outlines stored in its geometry object. In the kava (demo-crop-survey)_16 layer there is a variable called kava_id and in the plot-boundary (demo-crop-survey)_17 layer there is a variable called plot_id. These variables are unique identifiers for fields and can be used to match records in the kava (demo-crop-survey)_16 layer to records in the plot-boundary (demo-crop-survey)_17 layer. In the sidebar, scroll down until you see the Table Analysis section. This provides a suite of tools for analysing spatial data. The tool we’re after here is Combine Tables. The Combine Tables tool allows you to perform key-based joins on two related tables. A key is a variable (or set of variable) that uniquely identifies records in both tables and allows us to add records from one table to another by matching values in keys in both tables. When joining tables you have a left and right table. maplandscape lets you perform left and inner joins. In a left join, all rows in the left table are retained and matching records in the right table are appended to the left table. An inner join keeps only rows where there was match between the key variables in both tables. You can read more about the concepts involved in joining tables and working with keys here.
Let’s perform an inner join to create a table that only has records for fields where kava is grown. Set up your Combine Tables as in the image below. Set the left table as plot-boundary (demo-crop-survey)_17, set the right table as kava (demo-crop-survey)_16, set the primary key as plot_id, and set the foreign key as kava_id, set the join type as column - inner, and give the output table a name (e.g. kava_fields). When you’re ready, click the Join button. This should add the layer kava_fields to the Active layer selector.
Explore kava_fields in the table display. It should have all the attributes from the plot-boundary (demo-crop-survey)_17 layer and the kava (demo-crop-survey)_16 layer.
We’re also going to want to aggregate the area and plant number of kava in each village. This means we’ll need to attach a column that tells us which village each kava field is in. Let’s start by loading the vavau-village-boundaries.gpkg file into the app using the Upload Data tools in the sidebar.
All going well, you should see a layer vavau-village-boundaries (vavau-village-boundaries)_18 appear in the Active layer selector. Head to the Map tab and draw this layer on the map to see the village boundaries.
We’re now ready use the vavau-village-boundaries (vavau-village-boundaries)_18 layer to identify which village each kava field is in. We can use a spatial join to do this, attaching the village_name attribute in the vavau-village-boundaries (vavau-village-boundaries)_18 layer to the kava_field table. A spatial join allows you to combine attributes from two spatial layers based upon the feature’s relationship in space. This will involve assigning attributes from the vavau-village-boundaries (vavau-village-boundaries)_18 (e.g. village name, village id) to fields in kava_fields whose outline overlaps with the village extent.
In maplandscape features are joined based on the largest intersection (largest overlap) between two features using sf’s
st_join(). If 30% of a field overlapped with Village A and 70% of a field overlapped with Village B, the field would be assigned the attributes of Village B. Another way to think of this is: the field is getting the columns from the table associated with village boundaries with the values coming from the row in village boundaries table corresponding to the village with the largest overlap with the field.
The following diagram illustrates the process of performing a spatial join using the field-to-village example.
Head to the Data tab and the Table Analysis section in the sidebar. Select Combine Spatial Layers and set up the options as in the image below. For the left table select kava fields, for the right table select vavau-village-boundaries (vavau-village-boundaries)_18, for the Join Type select spatial - inner, and choose a sensible table name such as kava_fields_village. Click the Join button. This should perform the spatial join and add kava_fields_village as a layer to the Active layer selector.
A key task in transforming data ready for analysis and decision making is creating new columns that are functions of existing columns in our data. Under the Table Analysis section is an Add Column tool that allows us to create custom functions to create new columns in a layer. Let’s write functions to compute the area of kava in each field in acres and to compute the number of kava plants in each field.
Select the Add Column tool. Then select the layer that we want to add a new column too - kava_fields_village. Click the Add Column Options button.
In the popup window, set the new column name as kava_area_acres and use this function to compute the area of kava cultivation in acres in each field:
area_acres * (kava_area / 100). The area_acres column is the area of the field in acres and the kava_area column is the percentage of a field covered in kava crops. This function is computing the area of kava cultivation in each field and will store the result in the column kava_area_acres. Click Create column.
Display kava_fields_village in the table display and check to see that a column kava_area_acres has been appended to the far end.
Let’s create one more column that stores the number of kava plants in each field. There is a special in-built function called
plant_number() in the app for this. Repeat the previous process of going to the Add Column tool and selecting kava_fields_village. This time set the new column name to kava_plant_number and the function as
plant_number(kava_area_acres, plant_spacing, row_spacing). This should have computed the number of kava plants in each field and stored the value in the column kava_plant_number.
As part of our data transformation tasks, we might want to create a new layer based on values in an existing layer. This is a subsetting task. Under the Table Analysis section is a Filter Rows tool that allows us specify a filter condition to subset rows from an existing layer and store them in a new layer. Let’s create a new layer that stores only fields that are kava dominant (i.e. kava cultivation covered more than 50% of the field’s area).
Under the Filter Rows tool, select the table to filter as kava_fields_village and click the Filter Options button.
Let’s set a condition to subset rows from the kava_fields_village layer keeping only rows that correspond to fields with greater than or equal to 50% kava coverage:
kava_area > 50. Enter a new layer name to store the subsetted records (e.g. kava_dominant_fields). Click Filter. The new layer should be added to the Active layer selector.
Let’s check the filter operation worked OK. Head to the Map tab and draw the kava_dominant_fields layer on the map. It should look like the below image, which shows all fields with greater than 50% kava coverage.
A key data reporting task is performing aggregated summaries or group-by and summarise operations. Let’s demonstrate how these can be performed in maplanscape by computing the area and plant number of kava in each village.
Above the table display, click the Data: Summary tab. This will change to a table display where can view aggregated summaries.
Make sure that kava_fields_village is selected as the Active Layer. Under the Table Analysis section in the sidebar select the Summary Tables option.
You should see two boxes labelled Grouping variable(s) and Summarising variable(s). In the Grouping variable(s) box select the variables we wish to group-by. Here, that is village_name as we want to compute village summaries. You can type in the box to help you find the correct grouping variable.
In the Summarising variable(s) select kava_area_acres and kava_plant_number.
In the table display you should see that for each village in Vava’u, the mean and sum of kava area in acres and kava plant number have been computed. You can click Download Summarised Data to export the summary table as a csv file. You can explore changing the grouping and summary variables to create new summary tables.
Let’s use the Map tab to visualise cropping systems in each of the kava fields. Choose kava_fields_village as the active layer in the sidebar, kava_plant_number as the variable, yellow-green-blue as the fill colour palette, set the line width to 0.1, and the basemap in the bottom right corner of the map view to ESRI Satellite. Then click draw map. You should see something like the image below.
In the sidebar, scroll down, and you will see there is a check box to turn on the legend. Check this box and display the legend. You can also enter text to create a legend title.
Finally, keep scrolling down the sidebar and you’ll see a Popup labels box. Click in this box and choose variables in the layer displayed on the map that you’d like to see in a popup label for each feature. Let’s select the grower_status variable to see if each field is subsistence, semi-subsistence, or commercial and select some kava variety variables to see what varieties are grown in each field. Click on some features on the map to explore attributes for that field.
There is also a Charts tab in maplandscape which provides tools to create charts from data in your GeoPackages. You can create histograms to visualise the distribution of a variable, scatter plots to visualise bivariate correlations and relationships, and bar plots to visualise amounts of a variable per-group.
Let’s create a bar plot showing the number of kava plants in each village. In the sidebar, select kava_fields_village as the active layer and bar plot as the chart type.
Select village_name as the Grouping variable and kava_plant_number as the Summary variable. Choose sum as the bar plot type and click draw chart.
You should see a chart that looks like the image below.
There are few extra things we can do to style the chart. Scroll down in the sidebar and change the chart’s height to fill your display.
You can also create axis labels and change text font sizes. Create and X-axis and Y-axis label and change the Axis label and Axis value text size to 16. Then click the draw chart button. You should see a chart with axis labels in your display. You can save the chart by right-clicking on it and selecing save as image.
For more advanced use of maplandscape, check out the vignette on admin mode to see how clean and edit your data.