Unit displays

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:

  1. Display value-unit-pairs that are most intuitive for users to understand. This idea can be further broken down into:

    1. Systems of measure (e.g metric vs. imperial)

    2. Default display units (e.g. 0.5 hectares instead of 7,750,000 square inches)

    3. User specified value-unit-pairs (e.g. users should be able to override default display units)

  2. 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.

 

  1. 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:

    1. When the value is pre-populated by the system, the https://lite-farm.atlassian.net/wiki/spaces/LITEFARM/pages/658309153/Unit+displays#Default-display-guidance below should determine the value / unit combination

    2. When a value is NOT pre-populated by the system, the user set unit preference should be used

  2. When viewing a unit-value-pairing in a read-only settings:

    1. If the value was user created, the user set unit preference should be used

    2. If the value was system generated, the https://lite-farm.atlassian.net/wiki/spaces/LITEFARM/pages/658309153/Unit+displays#Default-display-guidance should be used

  3. When modifying a unit-value-pairing:

    1. If the value was user created, the user set unit preference should be used

    2. If the value was system generated, the https://lite-farm.atlassian.net/wiki/spaces/LITEFARM/pages/658309153/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 for the new system of measure. 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…

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 ().

 

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 and , 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 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

 

Past (obsolete) proposals: