Unit displays
- Lite Farm
- David Trapp
- Crystal Arsenault (Unlicensed)
- jdhillon (Unlicensed)
Introduction
In our day-to-day lives, almost every number we discuss has an implicit “unit” attached to it. Whether it’s dollars when we’re buying something, length when discussing a haircut with our barbers, or the weight of a block of cheese when shopping at a market. These units are often implied by the situation. We call this combination of value and unit a value-unit-pairing. An example is “20 kg”.
Transitioning from different units when discussing certain topics is such a natural thing that we don’t usually even acknowledge it. When discussing the distance to a far-off town we obviously use km / miles. When measuring wood to cut, we use inches / fractions of inches, cm or mm. Likewise, on farms there are certain times when displaying in a unit may be “technically” correct - but not helpful. This is especially true when discussing Imperial measurements. Imagine if we tried to describe the distance to Montreal in inches! It would take some mental gymnastics to figure out what that is in miles!
The purpose of unit displays are, in order of priority, to:
Display value-unit-pairs that are most intuitive for users to understand. This idea can be further broken down into:
Systems of measure (e.g metric vs. imperial)
Default display units (e.g. 0.5 hectares instead of 7,750,000 square inches)
User specified value-unit-pairs (e.g. users should be able to override default display units)
Make the comparison of data at the database level apples to apples
Ways users will interact with value-unit-pairs
There are a few ways a user will interact with a unit-value-pairings.
When creating something, such as a crop plan or task. Within these types of creation flows, there are two primary ways a unit-value-pairing can be shown to the user:
When the value is pre-populated by the system, the Unit displays | Default display guidance below should determine the value / unit combination
When a value is NOT pre-populated by the system, the user set unit preference should be used
When viewing a unit-value-pairing in a read-only settings:
If the value was user created, the user set unit preference should be used
If the value was system generated, the Unit displays | Default display guidance should be used
When modifying a unit-value-pairing:
If the value was user created, the user set unit preference should be used
If the value was system generated, the Unit displays | Default display guidance should be used
A note on changing units when a value has already been entered
We have two options:
Updating the unit, transforms the value. For example, changing “kg” to “g” for the value “20 kg” results in the new value “20,000”.
Updating the unit does not transform the value. For example, changing “m” to “cm” for the value “20 m” results in the new unit-value-pairing “20 cm”.
Warning: As of Feb 2023, the production environment has the first behaviour and the beta environment has the second. Both approaches have supporters, so we would like to move forward with the easiest to implement and maintain option.
When changing from one system of measure to another (e.g. Imperial to metric) all user entered value-unit-pairs should default to the Unit displays | Default display guidance for the new system of measure. Unit displays | User Preference are reset when re-establishing a system of measure.
Default display guidance
Please note, this guidance is on DISPLAYING units - not on persisting units. Units should be persisted in the database in a way that allows easy, apples to apples comparisons between farms with differing unit display preferences. The “apples to apples” unit is shown in the “Stored as…” column below and to the right.
Please use the following transitions when displaying various default measures. Once a user has expressed a desired unit (see User Preferences section at the bottom of this page for more details), that should supersede the default display rules.
Type of measure | Metric | Imperial | Stored as… |
|---|---|---|---|
Area | Default: Square meter; two decimal places If more than 1,000 sqm show in Hectare (e.g. 0.10 ha) to two decimal places | Default: Square feet; two decimal places If more than 10,890 sqft show in Acres (e.g. 0.25 ac) to two decimal places | m2 |
Distance includes length, height, weight, and depth | Default: Meter; two decimal places If less than 1 m, show in cm (e.g. 97.34 cm) to two decimal places If more than 1,000m show in kilometers (e.g. 1 km) to two decimal place | Default: Foot; two decimal places If less than 4 ft, show in inches (e.g. 2.25 inches) to two decimal places If between 4 ft and 20 ft, show in feet and inches to the nearest inch If between 20 ft and 1,320 ft, show in ft to the nearest foot (e.g. 326 ft) If more than 1,320 ft show in miles (e.g. 0.25 mi) to two decimal places | m |
Mass | Default: Kilogram (kg); two decimal places If less than 1 kg, show in grams (e.g. 1,000 g) to 0 decimal places If more than 1,000 kg show in metric tons (e.g. 1.83 MT) to two decimal place | Default: Pounds (lbs) and ounces (oz.) If less than 1 lb, show in ounces (e.g. 12.16 oz) to two decimal places Between 1 lbs and 2,000 lbs, show in pounds to two decimal places (e.g. 544.65 lbs) If equal or more than 2,000 lbs show in US tons (e.g. 1 ton) to two decimal place | Kg |
Volume | Default: Liter (L); two decimal places If less than 0.01L, display in mL to 2 decimal places | Default: Gallon (gal); two decimal places If less than 0.01 gal, display in fl oz to two decimal places | L |
Flow rate | Default: Liters per minute (L/m); two decimal places If < 1 L/m, display in liters per hour (L/h); two decimal places | Default: Gallons per minute (gpm); two decimal places If < 1 gpm, display in gallons per hour (gph); two decimal places | L / min |
Seed amounts | Default: seed count If more than 10,000 seeds show in g If more than 1000 g show in Kg Cover Crops default: Kg | Default: seed count If more than 10,000 seeds show in oz If more than 16 oz show in lb Cover Crops default: lbs | Kg |
Time | Default: Minutes If more than or equal to 60 minutes, show in hours and minutes (e.g. 90 minutes → 1 hour 30 minutes) to zero decimal places In general, minutes cannot be entered in less than 15 minute segments. Valid set: {15, 30, 45} | Same as metric | Minutes |
Temperature | Default: Celsius to 0 decimal places In most cases, temperatures can be displayed in C without conversion | Default: Fahrenheit to 0 decimal places In most cases, temperatures can be displayed in F without conversion | C |
Pressure | Default: kPa (kilopascal); two decimal places | Default: PSI (pounds per square inch); two decimal places | kPa |
User Preference
The above conversions and default transition points should be assumed when displaying a unit for the first time to a user. However, in many cases, users can modify this value after the fact to better suit their preferences. In these cases, the user preferences should be maintained on a record-to-record basis.
For example, when creating a farm site boundary a user might see this screen upon landing on the detail page (https://lite-farm.atlassian.net/browse/LF-935).
However, if the user chose to update “mi” to be “ft” (which would update the value from 0.75 → 3,960) then that preference should be persisted for this particular farm site boundary.
If the user had several different farm site boundaries, they could choose to display each of them per their preference on those pages.
How values are stored in the database
Regardless of Unit displays | Default display guidance and Unit displays | User Preference, it’s worth re-iterating that values are always stored in the database in a default unit (defined in the “Stored as…” column on the Unit displays | Default display guidance table). Hence, the following database entry should be read by human eyes as: “0.354… litres should be converted and displayed to the user in fl-oz”.
Once converted, the user would see 12 fl-oz instead.
This approach allows researchers looking at the raw data to compare entries in an apples-to-apples manner regardless of the user’s system of measure preference, default values, and individual value-unit-pair user preference.
Proposed architecture moving forward
Unit displays architecture refactor proposal (February 2023)
Past (obsolete) proposals: Unit displays architecture refactor proposal (August 2022)