Units of Measurement Repo
Last updated
Last updated
This tutorial will walk you through creating a sample repo with data in it. We will review creating each of the four root WarmHub types, committing data to your repo, and editing the templates to communicate a message for your instance data.
In modern times, standardized units of measurement have brought the world together. Units provide consistency to all measures of our physical world, making commerce, transportation, and science the way it is. Yet, the journey to a single set of absolute physical quantities has been arduous. We see the impacts today of an ongoing effort to settle on one consistent set of units. Many governing bodies assert claims upon the value of a set of units of measurement. We can capture these claims in the WarmHub data model to show relationships between various units.
You will need some way to post data to your repo. This can be an API client, or a Python script. Examples shown in this tutorial use .
Additionally, create a repo called unit_repo_walkthrough:
From the home page, click on “My Repos”
Click “Add Repo”
Enter unit_repo_walkthrough in the name. If you name the repo something different, please take care to update it every time it is referred to in the remainder of the walkthrough.
Enter whatever you’d like in the description.
To create our first type, we want to make an Article type. In this repo, our Article type will represent a unit of measurement.
After creating your repo, you will be redirected to the root page. In the sidebar, click on “Types.”
Then, click on “Add Type.” This will launch a dialog on your screen. We will first be creating a “Unit,” which will be an Article.
Then, click “Create.” You will be redirected to the type builder. Here, we would like to add two properties of type “Text” — GoverningBody, and PhysicalProperty:
GoverningBody is the organization which defines the unit. For example, the National Institutes of Science and Technology of the United States of America (NIST) defines the unit of a foot.
PhysicalProperty is the physical quantity which the unit measures. For example, the unit of a foot measures the physical property of length.
For each of these properties, select “Add Property,” and fill out the characteristics of the property as shown in the following screenshots:
Your “Properties” table should look like the below image. Then, click on “Save Changes.”
You will then be redirected back to the Types page. The Unit type should now show up in the Types table, as well as the Articles table (accessible via the side bar).
You will be making a POST request to the commit endpoint. In order to authenticate with WarmHub, you have to pass a bearer token in the header. Then, in the body, it’s necessary to provide a JSON object with the content of your commit.
Go to your repo’s About page via the sidebar. Then, click on the “Copy” button next to the Commit Endpoint field. In your API client, paste the commit endpoint in the relevant field.
Authenticate your API client with WarmHub using personal access tokens. First, expand the profile menu dropdown by clicking on your avatar. Then, select “Tokens.”
Click on “Create Token,” enter a name for your token, and set an expiration date. Then, click on “Create Token.” A dialog will appear, from which you can copy your token.
The structure of the authorization header is as follows: Authorization: Bearer [token]. After copying your token, you can put it into your API client.
In your API client, paste the following body and post the data to your commit endpoint:
The response should be similar to this, albeit with a different commitId and wid:
You can then view your data by going back to your repo page. In the sidebar, select the “Data” tab.
Links to the data are available in the table. Once you click on "unit/Kilogram", you will see the full instance page.
Let's post another commit to our commit endpoint:
The API call should complete successfully. You will then see the new "Kelvin" Article on the data page of your repo.
You might notice two things about this page in relation to the previous page:
There is a new "Related Instances" section generated by default. This shows the instances which have something in common. The table on the page right now shows the instances in your repo whose governing body is the BIPM (which is both the kilogram and the Kelvin). There should be another table which shows all of the instances in your repo whose physical property is Mass
There is something wrong with the Physical Property field of this instance. Whereas Kelvin is the SI base unit for thermodynamic temperature, the data we posted states that it measures mass, which is incorrect
In order to fix this, let's revise our data. First, you need to find your wid (WarmHub ID). A wid is an identifying link, which can be used to reference an instance in WarmHub. The format is as follows:
http://repo.warmhub.com/MyOrgName/MyRepoName/data/MyTypeName/MyInstanceIdentifier
We will be using this wid in the wref field of the following commit to identify that this revision is revising a certain instance. You will need to change the org and repo name to match your org and repo name in the body below.
Then, post this body to your repo's commit endpoint. You can refresh the page of the instance of "Kelvin", and the physical property should have changed from "Mass" to "Temperature."
You can navigate back to the original revision using the dropdown at the top of the page, or by clicking the link in the "revises" field.
Units of measurements are often referred to by a short symbol, rather than the full name of the unit, as it may become tedious to use the full name. For example, a recognized symbol for Kelvin is K. This symbol does not uniquely identify the Article (our unit), but instead it is an Assertion about the Article. We want to state that K refers to Kelvin.
In WarmHub, all Evidence must have a Source. So, we must begin by creating a Source.
We can create types by going into the subpage for the root type, as well. In the navigation panel, select Types, and then select Sources.
Click on the "Add Source" button
Set the name of the Source to "Agency"
Click on "Add Property"; Add a property named Link, of type Url
Your types table should look like the following screenshot. Click "Save changes"
Now that we have a Source type, we can create some Evidence. In the sidebar, you can select "Evidence" and click "Add Evidence." We will name this piece of Evidence "Symbol." All assertions (Evidence and Claims) must be about an Article. As discussed previously, this Symbol is about the Unit. So, select "Unit" for the "Type" field under the "About" section as follows:
The Symbol will just have a text property called "Symbol". After doing this, your type builder should look like the picture below, and you can click "Save Changes."
Now that the types have been defined, you can return to your API client and post our symbols to the commit endpoint. Please note that you will have to replace the org name and repo names in the wref field.
The consequence of this commit as well is that any instances of the unit which we did not post previously (in this example, "gram") will also be posted to your repo. This is determined by the $id field. For "Kelvin" and "kilogram", we take two approaches to posting the data:
"Kelvin" uses the full definition of the unit. Do be careful: if another instance of this type with the $id already exists in the repo, the commit won't go through unless the objects are the same.
"Kilogram" uses a wref. The wref is a reference to the previously committed object.
As we do not yet have the "gram" (Unit) or "BIPM" (Agency) instances, they will be created in your repo as well. If you go to the data page of your repo, you should see:
three new Evidence (Symbol objects),
KilogramSymbol
GramSymbol
WARM-[some UUID] — Automatically generated if you don't provide a $id
one newly created unit (Gram), and;
one new Source (BIPM)
Notice the difference between the the "Kilogram" Symbol and the other Symbol objects. As we provided a $id to the kilogram Symbol, the supplied identifier is used in the URL and as the name of the instance. The other symbol in the screenshot has the format WARM-instanceid, where instanceid is a UUID.
When we posted the "Unit" Articles earlier, the $id field is mandatory. However, for Evidence, the $id field is not mandatory. If you do specify a $id , the benefit is that the string is something will become the name of the instance datum in the URL. However, this must be a unique value among this type: you cannot have two Units, Symbols, or any other type with the same $id.
Next, it would be useful to create evidence about converting between two units. We will be using a simple linear model with two scalar properties: a coefficient, and a constant. The formula is as follows:
(From Unit) * factor + offset = To Unit
For example, if we were to convert from Celsius to Fahrenheit:
37 C * 1.8 + 32 = 98.6 F
As discussed in the Symbol section, each Evidence can be about one and only one Article. As our unit conversion is between two Articles, we first have to create a parent type, which we will call UnitConversionPair. Thus, our unit conversion will be about this UnitConversionPair.
First, create an Article type with the name UnitConversionPair.
We want to have a To and a From property, which should be of the Unit type.
You can repeat this for the From property. The resultant type definition should look like the following. You can then click "Save Changes."
Now, we want to create our UnitConversion (Evidence) type.
After creating the type, select UnitConversionPair for the "About" field. Add two properties Factor and Offset. Both of these properties should be numbers, and you don't need to add any constraints.
The finished type table should look like the following, and you can then click on "Save Changes."
Let's go back to the API client, and post the following commit. Please remember to change the org and repo name to match the org and repo name you used when creating the repo:
In this commit, there are the following results:
Creating a new Unit "Ton"
Will not create the duplicate Unit "Kilogram", which already exists in your repo
Creating a new UnitConversionPair "FromKilogramToTonne"
Creating a new UnitConversion converting from kilogram to tonne
You can view these new UnitConversion objects through the Data view by root type. First, select "Data" in the side bar, and then click on "Evidence."
Since we have two types of Evidence: Symbol and UnitConversion, only instances which are of those types will show up.
In this walkthrough, we have created Articles, Sources, and Evidence. The last remaining root type is a Claim. Claims are based on a set of evidence that we refer to as the "basis" for the Claim. They allow you to compose other assertions together to make higher level assertions within your repo.
In this repo, we will create a Claim asserting whether we can convert two units back and forth — whether the conversion we've stated between UnitA and UnitB also works from UnitB to UnitA. For some of these conversions, such as the conversion from Kilogram to Tonne, this is true, but for some conversions such as between Celsius and Fahrenheit, our formula is not commutative and thus it's not possible to convert back and forth using that conversion.
Like before, create a Claim type with the name "CanBeConvertedBackAndForth."
The claim will be about a UnitConversionPair, and we will add on a property called "IsReversibleConversion" of type boolean.
After this is complete, you can click "Save Changes."
Now, we can post the following body to the commit endpoint. Again, please make sure to change the org and repo name to match yours. You will have to do this several times in the current body, so we recommend using a text editor with the automatic replacement function.
As a result of the commit, there are three new instances:
A new UnitConversionPair from a Tonne to a Kilogram (without an $id)
A new UnitConversion "FromTonneToKilogram" (the inverse of what we had created before)
A new claim "CanKilogramAndTonneBeConvertedBackAndForth"
You will see these respective data in the Data tab of your repo. By default, the About field is placed above the property, but if you scroll down, you can view the result of the Claim (that the conversion between Kilogram and Tonne is reversible).
