Add class gist:SpecEntry #527

rjyounes · 2021-08-05T20:09:31Z

A SpecEntry is a Specification that has a magnitude and an aspect; for example, the specification of a particular furnace has an entry specifying weight (aspect) of 107 lbs (magnitude). This seems to be useful in a number of domains. Proposed definition:

gist:SpecEntry 
	a owl:Class ;
	skos:prefLabel "Spec Entry" ;
	skos:definition "A sub-specification consisting of the aspect being measured and a magnitude." ;
	skos:example "The specification of a particular furnace includes, among others, spec entries specifying a weight of 107 lbs and a maximum overcurrent protection of 15 amps. In the first entry, the aspect is weight and the magnitude is 107 lbs. In the second, the aspect is maximum overcurrent protection and the magnitude is 15 amps. (Each magnitude consists of a numeric value and unit of measure.)" ;
	owl:equivalentClass [
		owl:intersectionOf (
			gist:Specification 
			[
				a owl:Restriction ;
				owl:onProperty gist:hasMagnitude ;
				owl:someValuesFrom owl:Thing ;
			]
			[
				a owl:Restriction ;
				owl:onProperty 
                                       [ owl:inverseOf gist:aspectOf ] ;
				owl:allValuesFrom gist:Aspect ;
			]
			[
				a owl:Restriction ;
				owl:onProperty 
                                       [ owl:inverseOf [ gist:aspectOf ] ;
				owl:cardinality "1"^^xsd:nonNegativeInteger ;
			]	
			[
				a owl:Restriction ;
				owl:onProperty gist:partOf ;
				owl:onClass gist:Specification ;
				owl:minQualifiedCardinality "1"^^xsd:nonNegativeInteger ;
			]			
		) ;
	] ;
	.

Details negotiable. E.g, is it always part of a larger Specification, or could it occur on its own?

Question regarding the first restriction: are two magnitudes expressed in different units of measure and numeric values but which equal the same amount the same thing or two different things? Assuming the latter, I've used a someValuesFrom restriction on hasMagnitude. Assuming the latter we could specify cardinality of 1.

Notice also that aspectOf doesn't specify domain Aspect; thus the allValuesFrom restriction on the inverse of aspectOf.

The text was updated successfully, but these errors were encountered:

rjyounes · 2021-09-03T14:30:42Z

Related issue: in the case of concrete objects, as opposed to specifications, we suggest, I guess, that different predicates would be used to indicate the aspect being measured: hasWidth, hasHeight, hasCoolingCapacity, etc. It seems to me we should have a single approach to both specifications and real objects, and that the aspect model is preferable because it avoids defining a plethora of predicates in the domain ontology.

uscholdm · 2021-09-06T00:23:22Z

I'd love to have a sub-gist for specifications to include something like this. We have modeled this sort of thing for many clients.
However, as described in this wiki article, each situation is different enough so that the model usually needs to be tweaked in some way. I'd have to give careful thought to what we might be able to use as a stable core model.

uscholdm · 2023-09-13T19:28:02Z

@rjyounes This should be discussed in the context of #800. I think it is a good idea, especially now that we are creating the operators ontology. The above definition seems overly complicated. Below is more like what we have used for past clients.

gist:SpecEntry
	a owl:Class ;
	owl:equivalentClass [
		a owl:Class ;
		owl:intersectionOf (
			gist:Specification
			[
				a owl:Restriction ;
				owl:onProperty gist:ofCharacteristic ;
				owl:someValuesFrom gist:Characteristic ;
			]
			[
				a owl:Restriction ;
				owl:onProperty gist:specifiedValue ;
				owl:someValuesFrom [
					a owl:Class ;
					owl:unionOf (
						gist:Category
						gist:Magnitude
					) ;
				] ;
			]
		) ;
	] ;
	skos:definition "Specifies values for a particular characteristic indicating what it means to be in spec for that characteristic. Often this will be what is required, allowed or promised, but it could also be used to specify what is not allowed.  The values will typically be numerical with some unit of measure specified."^^xsd:string ;
	skos:prefLabel "Spec Entry"^^xsd:string ;
	skos:scopeNote "Sets of allowed values may also come from a Nominal or Ordinal scale of measure."^^xsd:string ;
	.

rjyounes · 2024-02-08T18:10:02Z

Closing - this will be handled by the new units and measures model.

uscholdm · 2024-02-09T01:36:17Z

There was not completed. There was no decision or even a discussion about whether/how to have SpecEntry in the context of the new units model. Once that is settled, we should come back and consider how it would work.

rjyounes · 2024-02-28T16:48:49Z

Closing due to implementation of new units and magnitudes model.

rjyounes · 2024-03-01T16:22:03Z

Reopening due to the question of how to handle a range of values (greater than, greater than or equal to, etc.) accommodated in spec entries. It remains to be seen how the new units and magnitudes model will model this, as it was built on the pre-gist13 Magnitude consisting of unit of measure + numeric value, without an aspect built in.

One approach would be to define several subproperties of gist:numericValue, such as lessThanOrEqualTo etc. to connect the gist13 Magnitude to one or more numeric values. This is different from the original SpecEntry relation which points the SpecEntry at two or more gist12 Magnitudes. This model would be more compact, though it's an open question whether it gains or loses semantic correctness. It's also not clear whether we would want any of this in gistCore.

@philblackwood any thoughts on this?

rjyounes · 2024-08-22T16:40:57Z

Given that gist 13 magnitudes include aspect, a class for SpecEntry = ((uom + numericValue) + aspect) doesn't seem necessary.

However, SpecEntries have also been used to model aspect + category, as in color: green.

Should characteristics whose values can be expressed either numerically or categorially be one aspect or two?

Rebecca: Should be one aspect. There are mappings between the two - e.g., European shoe size 40 (a numeric value measured in cm) = US women's shoe size 9 (arguably a category) which can be mapped to, say, medium. It depends on use case. Notably, manufacturers typically need precise numeric values where the customer value is categorial. Amplitude might be measured in decibels while others may only need high, medium, low - it's still the same aspect.

Phil agrees, Michael thinks they are distinct.

Allowing for either magnitude or categorial values with an aspect would complicate queries, though.
Users might implement SHACL constraints to limit the values, just as they might require that length be expressed in inches rather than centimeters.

We ascertained that Aspect and hasAspect are not definitionally limited to scalar values, though some annotation changes should be made, depending on the decision we reach above:

Aspect is defined as "A measurable characteristic such as length, weight, cost, cycle time, or defect rate." If it can include non-scalar aspects we should make this clear at least with examples or a scope note.
hasAspect is defined as "Relates a magnitude to its aspect (measurable characteristic)." If it's meant to apply beyond magnitudes we should loosen up the definition. (Note that there's no domain.)

Do we need a class for Aspect + category (color: green)? What would we call it?

uscholdm · 2024-09-04T16:21:31Z

The defining characteristic of what we're calling SpecEntry is that it has an aspect plus a value,

Not just a value, but a set of acceptable values (which could be just one value).

uscholdm · 2024-09-04T16:26:56Z

The versioning ontology doesn't import gist, it defines its own terms, so I'm not convinced that gist must consider the needs of that ontology.

We don't want to be forced to align them, but I am strongly against having different ways to do the same thing, just because we did not give enough thought to it.

rjyounes · 2024-09-04T19:07:06Z

I don't see that VersionRangeSpec is sufficiently similar to SpecEntry that they should coincide.

uscholdm · 2024-09-09T14:59:52Z

We may also want to add a restriction on SpecEntry that it be part of a Specification, but we should discuss that.

That is too strong, by analogy, engine bolts are created and intended to be part of actual engines. But they might not be so for a while, if ever. I can create a spec entry saying that width is between 1 and 2 inches intending it to be used for furniture. In practice it will almost certainly be part of a specification, but not in principle.

uscholdm · 2024-09-09T15:44:31Z

I don't see that VersionRangeSpec is sufficiently similar to SpecEntry that they should coincide.

They are very close in meaning. Each has:

an aspect (e.g. width, version number)
a specification of a set of acceptable values for the aspect using the operators: EQ, GE, GT, LE & LT

Ignoring ontology modularity issues regarding, gist and the operators and versioning ontologies one could define version range spec to be a subclass of spec entry with three additional restrictions.

`hasAspect value :_Aspect_versionNumber
isVersionRangeOf some owl:Thing
`hasSpecifiedValue some SemanticVersionNumber

In fact, defining version range spec as an explicit subclass would be optional.

I'll work out an example to clarify this.

uscholdm · 2024-09-09T16:14:27Z

Ignoring ontology modularity issues regarding, gist and the operators and versioning ontologies one could define version range spec to be a subclass of spec entry with three additional restrictions.

Having taken a closer look at the versioning ontology, which imports the operators ontology, I have a sense of what it would take to explicitly make VersionRangeSpec a subclass of SpecEntry. I conclude that there is little if any benefit in doing so, given the design goal to keep the versioning and operators ontologies independent from gist. As it is, to keep that independence, we had to recreate separate versions of a few classes and properties that were needed. There is no need for SpecEntry in the versioning ontology, so it's a bit moot to consider creating it just to subclass off it. I thought of having a skos note about it, but that hardly seems worthwhile.

rjyounes · 2024-09-09T22:03:51Z

We deliberately wanted to keep the operators/versioning ontologies independent of gist. I therefore don't see that the subclassing is an option. gist should not inherit a concept as fundamental as SpecEntry from the versioning ontology, and as you say it's not needed there.

uscholdm · 2024-09-10T14:33:17Z

We deliberately wanted to keep the operators/versioning ontologies independent of gist. I therefore don't see that the subclassing is an option. gist should not inherit a concept as fundamental as SpecEntry from the versioning ontology, and as you say it's not needed there.

Agreed. However, this does bring into focus how we implement SpecEntry in gist. Specifically, given that the operators ontology properties were designed to be used with SpecEntry in the first place with client ontologies, it would be nice to just use them w/o reinventing the wheel. Two approaches are:

import the operators ontology into gist
recreate them in the gist namespace

The first is straight-forward - I had a close look and did not see any issues.
The second would be unfortunate duplication.

dylan-sa · 2024-09-15T16:14:19Z

We may also want to add a restriction on SpecEntry that it be part of a Specification, but we should discuss that.

That is too strong, by analogy, engine bolts are created and intended to be part of actual engines. But they might not be so for a while, if ever. I can create a spec entry saying that width is between 1 and 2 inches intending it to be used for furniture. In practice it will almost certainly be part of a specification, but not in principle.

To me the term "entry" implies that it is actually entered in (or part of) a specification. (See, for example, 4b--"something entered.") For this reason I'm in favor of the restriction.

dylan-sa · 2024-09-15T16:42:07Z

@rjyounes -- At one client we've seen a use case for composite aspects. If drawer size is represented as '20in x 10in x 30 in' in the data, it is helpful to be able to model which of those is the height, which is the width, and which the depth.

Should the definition of SpecEntry accommodate this use case?

uscholdm · 2024-09-16T14:04:18Z

@rjyounes -- At one client we've seen a use case for composite aspects. If drawer size is represented as '20in x 10in x 30 in' in the data, it is helpful to be able to model which of those is the height, which is the width, and which the depth.

Should the definition of SpecEntry accommodate this use case?

That is very interesting, but seems highly specialized - not the sort of thing that we normally include in gist.

uscholdm · 2024-09-16T14:11:56Z

To me the term "entry" implies that it is actually entered in (or part of) a specification. (See, for example, 4b--"something entered.") For this reason I'm in favor of the restriction.

An airplane engine is so called because it is intended to be part of an airplane, just like SpecEntry is intended to be part of a specification. We don't need to give 'airplane engine' because sometimes is it not part of an actual airplane.

rjyounes · 2024-09-16T21:35:47Z

@rjyounes -- At one client we've seen a use case for composite aspects. If drawer size is represented as '20in x 10in x 30 in' in the data, it is helpful to be able to model which of those is the height, which is the width, and which the depth.

No, that got very messy and we ended up not using it anyway.

rjyounes · 2024-09-16T21:37:12Z

To me the term "entry" implies that it is actually entered in (or part of) a specification. (See, for example, 4b--"something entered.") For this reason I'm in favor of the restriction.

I think maybe the problem is with the word choice - I.e., can we call it something other than SpecEntry? I never understood the use of "entry" here. How about ValueSpecification?

uscholdm · 2024-09-17T15:20:39Z

I think maybe the problem is with the word choice - I.e., can we call it something other than SpecEntry? I never understood the use of "entry" here. How about ValueSpecification?

In long form, a spec entry is

a specification of a set of acceptable values for a particular aspect

So ValueSpecification is accurate and reasonable. Main downside is it's a bit long. I don't particularly like ValueSpec either even if we did go for abbreviated forms for names, which is against our general guidelines, AFAIK.

rjyounes · 2024-09-17T15:50:38Z

I prefer ValueSpecification but could live withValueSpec. We occasionally use abbreviated forms (the geo terms, not to mention SpecEntry itself), and ValueSpecification is not out of place with terms such as SubCountryGovernment, DegreeOfCommitment, ElectronicAddressType.

uscholdm · 2024-09-18T14:28:42Z

I just drafted a PR with a detailed example which is based on @rjyounes 's proposal. It directly imports the operators ontology
#1161

rjyounes · 2024-09-26T16:03:30Z

Goal: Specify a set of acceptable values for an aspect.

Requirements:

Handle categories and magnitudes uniformly.
Handle a range of values, either categories or magnitudes.
Handle single values (a single target)
Handle a set that isn't a range (discrete values).
Ability to set a target value with a range of variation (could be expressed in the max and min, or as a separate percent). gist could provide max and min only, extensions can add a percentage property.

TODOs for next meeting:

Michael: account for requirement 4.
Phil: account for requirement 1.

philblackwood · 2024-10-29T18:40:40Z

Getting to be long thread, but it's not clear SpecEntry is necessary.

Just relate the specification to an individual magnitude or range of magnitudes.

It looks like it would be helpful to add a class for Range.

NaoualSmaili · 2024-10-29T20:54:58Z

Versions may include additional qualifiers like alpha, beta, RC (Release Candidate), or build metadata. Ignoring these can lead to misrepresentation of compatibility and dependencies.
Also, for version range representation, simply using ranges may not suffice. For instance, a software might be compatible with versions 2.0.x but not 2.0.5 due to a known bug. The model should allow for specifying such exceptions within version ranges.

rjyounes · 2024-10-30T18:16:05Z

@philblackwood

...it's not clear SpecEntry is necessary. Just relate the specification to an individual magnitude or range of magnitudes. It looks like it would be helpful to add a class for Range.

I agree that since magnitudes include aspect, SpecEntry (or Characteristic) doesn't add anything, though would still be needed for category values and collections. Were you thinking a Range itself would have an aspect or not? Example:

# Range with aspect
:_Range_gas_mileage_31_39_mpg
    a gist:Range ;
    gist:hasAspect :_Aspect_gas_mileage ;
    gist:hasMinInclusive :_Magnitude_gas_mileage_31_mpg ;
    gist:hasMaxInclusive :_Magnitude_gas_mileage_39_mpg .

:_Magnitude_gas_mileage_31_mpg
    a gist:Magnitude ;
    gist:hasAspect :_Aspect_gas_mileage ;
    gist:hasUnitOfMeasure :_UnitOfMeasure_mpg ;
    gist:numericValue 31 .

:_Magnitude_gas_mileage_39_mpg
    a gist:Magnitude ;
    gist:hasAspect :_Aspect_gas_mileage ;
    gist:hasUnitOfMeasure :_UnitOfMeasure_mpg ;
    gist:numericValue 39.

Or:

# Range without aspect
:_Range_gas_mileage_31_39_mpg
    a gist:Range ;
    gist:hasMinInclusive :_Magnitude_gas_mileage_31_mpg ;
    gist:hasMaxInclusive :_Magnitude_gas_mileage_39_mpg .

In the first case we duplicate the aspect on both the range and the magnitudes, as we talked about with my proposed Characteristic class.

philblackwood · 2024-10-30T19:46:21Z

This comment is for creating specifications with categorical data ...

Note added 11/6/2024: if our subclasses of gist:Category are actually aspects (as they appear to be), then we need to pick one pattern ... either model them as aspects and stop using subclasses of Category, or continue using subclasses of Category and make it the standard pattern (leave aspects as is, representing only measurable characteristics).

The convention we use to model categories is a pattern like:

Some issues with this pattern are:

• Exterior color is an aspect, so now we have two ways to represent aspects (gist:Aspect or subclass of category)
• Every time a new subclass of category is needed, the ontology needs to be changed.
• Only annotation properties can have the class ex:ExteriorColor as an object, limiting expressiveness.

Note that we could also have an interior color red; since it has a different IRI than the exterior color red, it does not have to represent the same shade of red as the exterior color (which is a good thing). In this representation there is no stand-alone “red”.

IRIs:
ex:_ExteriorColor_red
ex:_InteriorColor_red

Also note that ex:_ExteriorColor_red is an instance of the gist:Category class.

Now suppose we want to use aspects instead of subclasses:

Old: ex:_ExteriorColor_red
New: ex:_Category_exterior_color_red

With this pattern, there is a one-to-one correspondence between the “old” representation and the “new” representation of categorical data. Also, with this new representation:

• New aspects can be added without changing the ontology
• We have only one way to represent aspects
• User-defined properties can relate things to the aspect

With this new representation, we might model categorical specifications as:

The fact that thing 1 is categorized by a category that is part of the specification means it conforms to the specification.

[arguably there might be a better way to say that the specification includes exterior colors red, blue, gray, and white]

Note added 11/6/2024: the example is not correct. See additional comment showing 3 cases.

Note that in either representation, we might want to be able to say that the interior and exterior red are the same [method tbd].

uscholdm · 2024-11-04T17:12:04Z

This is very interesting.

Are you proposing that all instances of gist:Category are to have an aspect, just like all Magnitudes do?
Are you proposing to never have subclasses of gist:Category?

philblackwood · 2024-11-06T16:16:37Z

@uscholdm if we want to expand the definition of aspect from "measurable characteristics" to "characteristics" then I think we want to use those aspects instead of creating subclasses of category so that there is a single way to represent them.

e.g. pick one of these styles:

using categories: ex:_ExteriorColor_red (requires updating the ontology to include ExteriorColor)
using aspects: ex:_Category_exterior_color_red with aspect ex:_Aspect_exterior_color

Actually, either style can be used to define specifications, so we can treat the question separately if we agree that we should pick one of these and not use a combination of aspects and subclasses of category.

philblackwood · 2024-11-06T16:25:35Z

Comment about how we use specifications ...

Consider the simple case of a specification with two aspects, with a single fixed acceptable value for each one.

rectangle specification: length 3 inches, width 8 inches.
actual rectangle measurements: length 3 inches, width 8 inches.

In this simple case we define the specification exactly the same way we describe the actual.

Variation: specification says the width may be either 8 inches or 10 inches. We should cover this case as well, since many specifications come with a choice of values.

The concept of SpecEntry really isn't needed in either case.

See next comment for how this applies to "categorical values".

philblackwood · 2024-11-06T16:38:10Z

Specifying things with categorical values using our convention of subclasses of categories.

Case 1: within each category a thing and its specification are single-valued.

Thing 1 conforms to its specification. In general, check to see if there is an exact match between the actual values and the values in the specification.

Variation: choice of colors. First introduce the collection of acceptable colors.

Now see if the value for thing 1 is one of the acceptable colors:

Thing 1 conforms to its specification because its value is one of the acceptable colors in the specification.

To specify that a thing can have multiple colors, either create a category for each color combination (explicit) or create a new property (not as useful because it might require one property for a pair of colors, one for any 3 colors, one for any 4 colors, etc.)

Note that the examples still work if _ExteriorColor is replaced by _Category_exterior_color (1-to-1 correspondence).

uscholdm · 2024-11-07T15:39:20Z

Interesting, so it seems you are proposing that it is not necessary to have subclasses of Category, one could use aspects instead.
Is that correct?

uscholdm · 2024-11-07T15:46:02Z

On property naming... Thing 1 may well be a thing with a red exterior color, and thus saying that it gist:isCategorizedBy :_ExteriorColor_red makes sense.
However the specification does not have an exterior color, as it is not a physical object. In longwinded terms, the specification specifies that the exterior color is red. Not easy to come with a good property name for this that conforms to common sense and is not too long or convoluted.

rjyounes · 2024-11-15T12:46:32Z

If we are going to say that a specification hasValue or hasMagnitude, then why not also isCategorizedBy? I think the predicates can be interpreted flexibly enough to make that acceptable.

rjyounes added the topic: specifications label Aug 5, 2021

rjyounes added this to gist Version 12.1.0 Nov 19, 2023

rjyounes moved this to In triage in gist Version 12.1.0 Nov 19, 2023

rjyounes added topic: units and measures and removed topic: specifications labels Dec 28, 2023

rjyounes removed this from gist Version 12.1.0 Dec 28, 2023

rjyounes added this to gist Version 13.0.0 Dec 28, 2023

github-project-automation bot moved this to In Triage in gist Version 13.0.0 Dec 28, 2023

rjyounes closed this as completed Feb 8, 2024

github-project-automation bot moved this from In Triage to Done in gist Version 13.0.0 Feb 8, 2024

uscholdm reopened this Feb 9, 2024

github-project-automation bot moved this from Done to In Progress in gist Version 13.0.0 Feb 9, 2024

rjyounes closed this as not planned Won't fix, can't repro, duplicate, stale Feb 28, 2024

github-project-automation bot moved this from In Progress to Done in gist Version 13.0.0 Feb 28, 2024

rjyounes removed this from gist Version 13.0.0 Feb 28, 2024

rjyounes reopened this Mar 1, 2024

rjyounes added this to gist Version 13.0.0 Mar 1, 2024

github-project-automation bot moved this to In Triage in gist Version 13.0.0 Mar 1, 2024

rjyounes removed this from gist Version 13.0.0 Apr 11, 2024

rjyounes added this to gist Version 13.1.0 Apr 11, 2024

github-project-automation bot moved this to In Triage in gist Version 13.1.0 Apr 11, 2024

rjyounes mentioned this issue Aug 8, 2024

Modeling patterns and/or gist updates for a magnitude range #1145

Open

rjyounes linked a pull request Sep 26, 2024 that will close this issue

Added spec entry class #1161

Draft

Add class gist:SpecEntry #527

Add class gist:SpecEntry #527

Comments

rjyounes commented Aug 5, 2021 • edited Loading

rjyounes commented Sep 3, 2021

uscholdm commented Sep 6, 2021

uscholdm commented Sep 13, 2023 • edited Loading

rjyounes commented Feb 8, 2024

uscholdm commented Feb 9, 2024

rjyounes commented Feb 28, 2024

rjyounes commented Mar 1, 2024 • edited Loading

rjyounes commented Aug 22, 2024

uscholdm commented Sep 4, 2024

uscholdm commented Sep 4, 2024

rjyounes commented Sep 4, 2024

uscholdm commented Sep 9, 2024

uscholdm commented Sep 9, 2024 • edited Loading

uscholdm commented Sep 9, 2024

rjyounes commented Sep 9, 2024

uscholdm commented Sep 10, 2024

dylan-sa commented Sep 15, 2024

dylan-sa commented Sep 15, 2024

uscholdm commented Sep 16, 2024

uscholdm commented Sep 16, 2024

rjyounes commented Sep 16, 2024

rjyounes commented Sep 16, 2024 • edited Loading

uscholdm commented Sep 17, 2024

rjyounes commented Sep 17, 2024

uscholdm commented Sep 18, 2024

rjyounes commented Sep 26, 2024 • edited Loading

philblackwood commented Oct 29, 2024

NaoualSmaili commented Oct 29, 2024

rjyounes commented Oct 30, 2024 • edited Loading

philblackwood commented Oct 30, 2024 • edited Loading

uscholdm commented Nov 4, 2024

philblackwood commented Nov 6, 2024

philblackwood commented Nov 6, 2024

philblackwood commented Nov 6, 2024

uscholdm commented Nov 7, 2024

uscholdm commented Nov 7, 2024

rjyounes commented Nov 15, 2024

rjyounes commented Aug 5, 2021 •

edited

Loading

uscholdm commented Sep 13, 2023 •

edited

Loading

rjyounes commented Mar 1, 2024 •

edited

Loading

uscholdm commented Sep 9, 2024 •

edited

Loading

rjyounes commented Sep 16, 2024 •

edited

Loading

rjyounes commented Sep 26, 2024 •

edited

Loading

rjyounes commented Oct 30, 2024 •

edited

Loading

philblackwood commented Oct 30, 2024 •

edited

Loading