Help:Semantic custom units

This page explains ways that pages can have more control over the display and conversion of units. Units are used for properties of type Number, and make annotation more flexible: everybody can view and enter data in his or her preferred unit without restricting mutual understanding. For example, some people might prefer a distance given in "miles" over one given in "km". In other cases, it might not be suitable to display a distance in "km" since "nm" are more appropriate.

Custom types with unit conversions
SMW already comes with support for at least one types that can handle units (i.e., Type:Temperature), but editors can add more. Such abstract types that support units can accept, convert, and display values in several different units.

To support such features, SMW must know how to convert values from one unit into another. This is rather easy in many cases, but can also involve more complex computation in other situations. We distinguish two cases:
 * 1) Conversion between the desired units is proportional, i.e. you multiply one value with a fixed conversion factor to get the value in another unit. For example, this is the case for converting between centimeters and inches.
 * 2) Conversion between units is not proportional and more complex computations are needed. For example, this occurs for temperatures, since you need to add and multiply in order to get from °C to °F (or from Kelvins to Rankines or any other temperature unit).

For all unit conversions of the first kind, you can easily create custom types that support those units. The second situation is not supported today, except for temperatures.

Linear unit conversions
Before thinking about creating a new datatype, make sure that the type does not already exist. Use the Special:Types page to review all types, or go to Special:Allpages and search the Type namespace.

If the desired type does not exist, you can create a new one easily. First, you need to create a page in the Type namespace. For example, you might want to create Type:Power. In the new article, you should first write some sentences on the purpose and use of this new type. In our case this would say that we mean the physical quantity of the rate of work done as a function of time. This also helps others to find and reuse your type when searching for keywords.

To specify the supported units, the special property "corresponds to" is used. For example, to specify the main unit of the new type, we write

Corresponds to::1 W.

The value "1 W" states two things:


 * 1) We support the unit symbol "W"
 * 2) That symbol is the main unit (that is what the "1" is for).

Intuitively, the statement says "One quantity of this type corresponds to 1W."

You then, in the same Type declaration, specify further units by using the "Corresponds to" property and giving their conversion ratios:

Corresponds to::0.001 kW. Corresponds to::0.0013410220 hp.

This says that "kW" and "hp" are also supported, and that 1 W (the main unit) is 0.001 kW and 0.0013410220 hp. You may add as many units as you like, as long as you can describe their relationship to W in this simple manner.

Often one unit can have many symbols. For example a user might write "W" or "Watt" or even "Watts" and mean the same thing. A short way of doing this is to separate additional units with "," instead of making multiple "corresponds to" statements with the same factor. For example we would write:

Corresponds to:=1 W, Watt, Watts.

The above states that we support W, Watt, and Watts as valid symbols, and that they are all equivalent.

After saving the article of the new type, the "corresponds to" statements will appear as special properties in the factbox. The type now can be used like any other type. For example, we could make a new Property:Engine power that is of type Power, written by saying:

Has type::Type:Power

somewhere on its page. Values given to this property will then understand all of the given units, and will show conversions between them (without duplicates, i.e. SMW does not dipslay "W" and "Watt"). Internally, the values will all be converted to the main unit, and the RDF export will show the value in this unit as well. The display of units within the wiki still is highly customisable and need not involve the main unit, see below.

Non-linear unit conversions
Non-linear unit conversions are supported for one quantity only: Type:Temperature. Any other non-linear conversion would require a developed spinoff extension to SMW. If enough editors express an interest in a unit requiring non-linear handling, the administration will consider developing it.

Customising the display of units
Through the use of floating-point numbers, a single type can support a broad range of units. For example, a length type can easily support multiple units varying from parsecs to nanometers. However, if someone uses a property called "Elevation" for specifying the height of mountains (or the average altitude of a city), then such a property would not be likely to use parsecs or nanometers.

SMW allows you to specify which units a property should display from all the units its type supports. This information is specific to the property: two attributes can both use, say, Type:Length while still having different appearances in the wiki. If no preferences on display are given, a property will display all of its type's units, with the main unit (the one with conversion factor 1) first.

To specify custom display units, add the special property display units to the property's page, mentioning each unit you want displayed separated by commas. For example, the page Property:Height could contain the statements:

display units::km,ft,miles

With this statement, factboxes of articles having length annotations will display only those three units for values of the property Height, even though its Type:Length might support dozens of other units. Similarly, the tooltip for each such value will show those conversions. This customization works for all attributes that use types with unit support, no matter whether the type was customized or built-in.

If you change the first display unit, consider displaying the type's "Standard Unit" to users as one of the other display units, since SMW still converts values to the standard unit when storing them.