Help:Custom units
This page explains ways that pages can have more control over the display and conversion of units. Units can be 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" if "microns" are more appropriate.
Custom types with unit conversions[edit]
SMW has built-in support for some types that can handle units (e.g. Type:Temperature), but many more can easily be added. Types that support units can accept, convert, and display values in several different units. You can see this in the factbox of articles like "ow:Berlin", where the area is given in multiple units.
In order to support such features, SMW needs to 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:
- Conversion between the desired units is proportional, i.e. you just have to multiply one value with a fixed conversion factor to get the value in another unit. For example, this is the case for converting between kilometres and miles.
- 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.
For all unit conversions of the first kind, you can easily create custom types that support those units. For the second situation, we discuss some possibilities below.
Creating new datatypes with propertional unit conversion[edit]
Before thinking about creating a new datatype, make sure that the type does not already exist by consulting Special:Types.
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 that is usually measured in Watt. This also helps others to find and reuse your type when searching for keywords.
To specify the supported units, you use a special property corresponds to. For example, to specify the main unit of the new datatype for power, we add
[[Corresponds to::1 W]]
The value "1 W" states two things: (1) the type understands the unit "W" and (2) the unit "W" is its main unit (that is what the "1" is for). Intuitively, the statement says "One quantity of this type corresponds to 1W." It is easy to specify further units, e.g.
[[Corresponds to::0.001 kW]] [[Corresponds to::0.0013410220 hp]].
This says that the type also understands the units "kW" and "hp", and that 1 quantity of the main unit corresponds to 0.001 kW and to 0.0013410220 hp. In this way, you can support arbitrary units, so long as their relationship to the main unit can be described in this easy manner.
In many cases, there are multiple ways of referring to one unit. E.g. we would like to allow users to write "W" as well as "Watt" and maybe even "Watts". 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]] [[Corresponds to::0.0013410220 hp,bhp,horsepower]]
The very first symbol in the "corresponds to:: 1 xx" is the main unit. After saving the page for the new type, the "corresponds to" statements will appear as special properties in its 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, by adding to its page:
[[Has type::Power]]
This property will understand all the units defined in "corresponds to" statements in its datatype, 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 is highly customizable and need not involve the main unit, see below.
Unit conversions that are not proportional[edit]
Note that you can only specify a proportional conversion factor, a multiplier. So you cannot have different bases for different units, logarithmic scale conversions, etc. Thus you can't create a custom type for temperature which converts degrees Celsius to Fahrenheit. In the case of temperature, SMW already supplies a built-in Type:Temperature that handles this conversion, but this might not be true in other cases.
SMW does not allow specifying customized non-proportional units in the wiki. One workaround for this is to use Type:Number which also accepts unit strings after a given number. The type does not know how to convert between those values, but it still recognizes the unit and will be able to distinguish different units. If all users of a certain exotic type agree on using the same unit, the functionality would be similar to having real unit support. If someone still uses another unit, then the given value will at least not be confused with values in other units.
A more elaborate way of fixing the situation is to write a small script that implements the required conversion. It is not difficult to extend SMW in this fashion, and one could simply copy and adjust the code for Type:Temperature (which is below 70 lines, including comments). Upon implementing such a custom type, properties that needed to use Type:Number can be changed to the new type without any negative effects on existing articles. When confronted with unsupported units, custom types will still behave like simple number datatypes.
Customizing the display of units[edit]
Through the use of floating-point numbers, a single type can support a broad range of units. For example, a single length type can easily support both light years and nanometers. However, if someone uses a property "Elevation" to specify the height of a mountain, then it would hardly be useful to display this value in light years 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 properties can both use 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 article Property:Height could contain the statements:
[[display units::km,ft,miles]]
This results in the factbox displaying only those three units for values of the property Height, even though its Type:Length might support a dozen other units. Similarly, the tooltip for each such value will show those conversions. This customization works for all properties 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.
