Refine the reverse-link names in #97 - #110
Open
apdavison wants to merge 2 commits into
Open
Conversation
Changes 106 nameForReverseLink values, based on the following principles: P1. Do not repeat the type in the name of its own property unless no meaningful alternative name exists. 46 reverse names in the original PR repeat the type they land on exactly (Handedness.isHandednessOf, License.isLicenseOf, Person.isPersonOf, AnatomicalAxesOrientation.isAnatomicalAxesOrientationOf) and a further 37 repeat part of it (ModelAbstractionLevel.isAbstractionLevelOf, SoftwareApplicationCategory.isApplicationCategoryOf). 37 of the exact repeats and 24 of the partial ones are changed here; the remaining 9 and 13 are left as they are, because their far end mixes unrelated types and no single name describes what the reverse returns (Laterality.isLateralityOf reaches annotations and tissue samples; DataType.isDataTypeOf reaches ContentType, DatasetVersion and File). Where the far end is coherent, the reverse is named for it. 45 names take the form appliesTo<FarEnd> for controlled terms (Handedness.appliesToSubjectState, MRIWeighting.appliesToMRIScannerUsage), and a plain verb is used where the relation has one, which takes precedence over appliesTo: SovereignState.containsLocation, ChemicalMixture.insulates, OperatingSystem.runs, Configuration.configures. Where a property could plausibly widen later the name follows the category rather than the class, so language becomes appliesToResearchProductVersion rather than appliesToSoftwareVersion. P2. Use "has" only for possession, not as a past-tense marker. hasPerformed, hasStarted, hasGenerated, hasInformed and hasInspired become the bare past participle. hasPart, hasMember, hasVersion, hasChild, and the other possessive uses are unchanged. P3. Prefer the past tense for events and the present tense for standing states, because metadata outlives the activity it describes: a grant that has ended no longer funds anything, but it funded something permanently. Hence funded, developed, edited, published, manufactured, emitted for events, and identifies, specifies, configures for relations that hold as long as both nodes do. P4. Keep reverse names singular, as for forward property names, with the same exception the forward vocabulary makes for a tuple of genuinely distinct values (Trapezoid.baseLengths). A reverse link returns a homogeneous collection, so every name here is singular. The remaining changes are individual, and are mostly cases where the current name is inaccurate rather than merely mechanical: isConfiguredBy on LaunchConfiguration inverts the direction of the relation; isDiseaseModelOf lands on Disease and asserts that the disease is the model, when the strain is; isContributionOf lands on Person and asserts that a person is a contribution; hasMeasurement names a device and collides with the Measurement type. Finally, isFileRepositoryOf on FileRepository is verbose: the resolved array will be the files contained in the repository, so `file` (plural "files" in fairgraph) is a much clearer name. Two properties that we may wish to merge in v6, dependency and dependsOn, are given the same reverse name isDependencyOf rather than divergent ones. The per-property rationale will be in the pull request description.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This builds on #97. It keeps the principle of having one reverse name per property, but proposes some refinements to the names themselves.
Principles
These changes are mostly based on the following principles, with a few justified exceptions.
P1. Do not repeat the type in the name of its own property, unless no meaningful alternative exists.
46 of the names in #97 are exact self-repeats:
Handedness.isHandednessOf,License.isLicenseOf,Person.isPersonOf,AnatomicalAxesOrientation.isAnatomicalAxesOrientationOf. The reader already knows the type, whether querying in the KG Query Builder or using fairgraph; the more useful information is what lies at the other end of the link.The "meaningful alternative" qualifier is important. 37 of the 46 exact repeats are changed here, and 24 of a further 37 partial repeats; 9 and 13 respectively are left alone, because their far end mixes unrelated types and no single name describes what the reverse returns:
Laterality.isLateralityOfreaches both annotations and tissue samples,DataType.isDataTypeOfreachesContentType,DatasetVersionandFile, andTechnique.isTechniqueOfreaches seven computational activities plusProtocolandDatasetVersion. Where there is no coherent far end,is<X>Ofremains the only stable choice.Where the far end is coherent, the reverse is named for it. Fifteen of the changes take the form
appliesTo<FarEnd>(Handedness.appliesToSubjectState,MRIWeighting.appliesToMRIScannerUsage), and others take a more specific verb than "applies" where the relation has an obvious one (configures,runs,usedForComputation,insulates,containsLocation).Where the far-end types belong to an openMINDS category (
researchProduct,computationalActivity,chemicalProduct) I've used the category name, e.g.,appliesToResearchProductVersion. Where a property could plausibly widen in a future openMINDS revision I've also used category-based names. For example,language(English, German, Chinese) is reached only fromSoftwareVersiontoday, but I can imagine addinglanguageto other research products, so I propose calling the reverseappliesToResearchProductVersioninstead ofappliesToSoftwareVersionfor the sake of future-proofing.I also note that the forward vocabulary almost never uses the
is<X>Ofconstruction. Of the 441 distinct forward property names across v4.0 and v5.0, only five have this form (isPartOf,isVersionOf,isNewVersionOf,isVariantOf,isAlternativeVersionOf) and all five name structural relations between parts or versions, where "of" genuinely is the relation. Nothing on the forward side is calledisSpeciesOforisLicenseOf. #97 applies the construction to 90% of reverse names in use (299 of 332). This PR reduces that to 64%, butis<X>Ofis still needed for a majority of reverse property names.P2. Use
hasfor possession, not as a past-tense marker.hasPerformed,hasStarted,hasGenerated,hasInformedandhasInspiredbecome the bare past participle (performed, etc).hasPart,hasMember,hasVersion,hasChildand the other possessive uses are untouched.A corollary:
has<Noun>promises that a<Noun>is what the reverse returns. It works where the type exists —hasMembershipreturnsMembership,hasAffiliationreturnsAffiliation— and misleads where it does not.hasImplementationwould returnSoftwareVersion(openMINDS has noImplementationtype), soisImplementedByis proposed instead; the schema's own instruction for that property reads "Add all interface versions that are implemented by this software version". The same test rejectshasDependent, which returns the research-product versions, andhasMeasurement, which returns devices and collides with the realMeasurementtype.P3. Past tense for events, present for standing states.
Metadata outlives the activity it describes: a grant that ended in 2019 no longer funds anything, but it funded something permanently. Hence
funded,developed,edited,published,manufactured,emitted; andidentifies,specifies,configuresfor relations that hold as long as both nodes do.P4. Reverse names stay singular.
This ollows the general rule for property names, with the same exception the forward vocabulary already makes for a tuple of genuinely distinct values (
Trapezoid.baseLengths, the major and minor bases;ElectrodeArrayUsage.contactResistances, one per electrode in order). A reverse link returns a homogeneous collection rather than a tuple, so every name here is singular.The changes
(Note: these tables are wide, you'll probably need to scroll horizontally)
(P1) The reverse name repeats the type it lives on
Exact repeats (
Handedness.isHandednessOf) and partial ones (ModelAbstractionLevel.isAbstractionLevelOf).Two further self-repeats,
diseaseModelandcontribution, are listed under Inaccurate below, where the stronger argument lies.MRIWeightingMRIWeightingMRIScannerUsageisMRIWeightingOfappliesToMRIScannerUsageMTPulseShapePulseShapeMRIScannerUsageisPulseShapeOfappliesToMRIScannerUsageabstractionLevelModelAbstractionLevelModelisAbstractionLevelOfappliesToModelaccessibilityAccessibility+1AnatomicalAtlasVersion+13isAccessibilityOfappliesToResearchProductVersionageCategoryAgeCategorySubjectGroupState+1isAgeCategoryOfappliesToSubjectStateanatomicalAxesOrientationAnatomicalAxesOrientationCommonCoordinateFrameworkVersion+3isAnatomicalAxesOrientationOfisOrientationOfapplicationCategorySoftwareApplicationCategorySoftwareVersionisApplicationCategoryOfappliesToSoftwareVersionattributeSubjectAttribute+1SubjectGroupState+3isAttributeOfappliesToSpecimenStatebreedingTypeBreedingTypeStrainisBreedingTypeOfappliesToStrainchannelAccessChannel+1Accessibility+1isChannelOfappliesToAccessibilitycommunicationProtocolCommunicationProtocolInterfaceisCommunicationProtocolOfusedByInterfaceconfigurationConfiguration+3Environment+3isConfigurationOfconfiguresconstructionTypeCranialWindowConstructionTypeCranialWindowPreparationisConstructionTypeOfappliesToCranialWindowPreparationcontactInformationContactInformationConsortium+1isContactInformationOfappliesToLegalPersoncontentTypeContentTypeContentTypePatternisContentTypeOfcontentTypePatterncontentTypePatternContentTypePatternFileRepositoryisContentTypePatternOfdefinesContentTypeForcultureTypeCellCultureTypeTissueCulturePreparationisCultureTypeOfappliesToTissueCulturePreparationdeviceTypeDeviceTypeElectrode+3isDeviceTypeOfappliesToDeviceeducationalLevelEducationalLevelLearningResourceisEducationalLevelOfappliesToLearningResourceeligibilityAccessEligibilityTypeAccessibilityisEligibilityOfappliesToAccessibilityenvironmentEnvironment+2DataAnalysis+7isEnvironmentOfusedForComputationethicsAssessmentEthicsAssessmentDatasetVersionisEthicsAssessmentOfappliesToResearchProductVersionexperimentalApproachExperimentalApproachDatasetVersionisExperimentalApproachOfappliesToDatasetVersionfatSuppressionTechniqueMRIFatSuppressionTechniqueMRIScannerUsageisFatSuppressionTechniqueOfappliesToMRIScannerUsagefeatureSoftwareFeatureSoftwareVersionisFeatureOfappliesToSoftwareVersionfileRepositoryFileRepositoryFileisFileRepositoryOffileformAccessFormAccessibilityisFormOfappliesToAccessibilityfundingFundingAnatomicalAtlasVersion+16isFundingOffundedgeneticStrainTypeGeneticStrainTypeStrainisGeneticStrainTypeOfappliesToStrainhandednessHandednessSubjectGroupState+1isHandednessOfappliesToSubjectStatehasEntityParcellationEntity+1ParcellationTerminology+1isEntityOfappliesToParcellationTerminologyinterfaceTypeCommunicationInterfaceTypeInterfaceisInterfaceTypeOfappliesToInterfacelanguageLanguageSoftwareVersionisLanguageOfappliesToResearchProductVersionlicenseLicense+1Book+12isLicenseOfisAppliedTomeasuredQuantityMeasuredQuantityMeasurementisMeasuredQuantityOfappliesToMeasurementmolecularEntityMolecularEntityChemicalSubstanceisMolecularEntityOfcomposesmountingTypeDeviceMountingTypeMRICoilisMountingTypeOfappliesToDeviceoperatingDeviceOperatingDeviceSoftwareVersionisOperatingDeviceOfrunsoperatingSystemOperatingSystemSoftwareVersionisOperatingSystemOfrunsorganizationOrganizationAffiliationisOrganizationOfhasAffiliationparallelAcquisitionTechniqueMRIParallelAcquisitionTechniqueMRIScannerUsageisParallelAcquisitionTechniqueOfappliesToMRIScannerUsagepaymentModelPaymentModelTypeAccessibilityisPaymentModelOfappliesToAccessibilitypersonPersonAffiliationisPersonOfhasAffiliationpreparationTypePreparationTypeDatasetVersionisPreparationTypeOfappliesToDatasetVersionprocessAccessProcessTypeAccessibilityisProcessOfappliesToAccessibilityproductSourceProductSourceChemicalMixture+1isProductSourceOfappliesToChemicalProductprogrammingLanguageProgrammingLanguageSoftwareVersionisProgrammingLanguageOfusedInSoftwareVersionpublicationStatusPublicationStatusAnatomicalAtlasVersion+9isPublicationStatusOfappliesToResearchProductVersionqualitativeOverlapQualitativeOverlapQualitativeRelationAssessmentisQualitativeOverlapOfappliesToAssessmentreferenceAgeReferenceSpecimenAgeisReferenceOfappliesToSpecimenAgereinforcementTypeCranialWindowReinforcementTypeCranialWindowPreparationisReinforcementTypeOfappliesToCranialWindowPreparationsignalDirectionalitySignalDirectionalityMRICoilUsageisSignalDirectionalityOfappliesToMRICoilUsagespatialEncodingSpatialEncodingMRIScannerUsageisSpatialEncodingOfappliesToMRIScannerUsagespoilingTechniqueMRISpoilingTechniqueMRIScannerUsageisSpoilingTechniqueOfappliesToMRIScannerUsagestatusActionStatusTypeDataAnalysis+6isStatusOfappliesToComputationstimulationStimulationApproach+1BehavioralProtocolisStimulationOfappliesToProtocolstimulusEphysStimulusStimulationActivityisStimulusOfisStimulusForstimulusTypeAuditoryStimulusType+6BehavioralProtocol+1isStimulusTypeOfappliesToProtocoltypeOfUncertaintyTypeOfUncertaintyQuantitativeValue+1isTypeOfUncertaintyOfappliesToValuevariationPatchClampVariationCellPatchingisVariationOfappliesToCellPatching(P2 / P3) The name should be a verb, in the right tense
authorConsortium+2Book+11isAuthorOfauthoredcommenterPersonCommentisCommenterOfcommentedcoordinatorConsortium+2ProjectisCoordinatorOfcoordinatedProjectcountrySovereignStateLocationisCountryOfcontainsLocationcultureMediumChemicalMixtureTissueCulturePreparationisCultureMediumOfusedForTissueCulturedeliveredByElectrodeArrayUsage+5EphysStimulushasDelivereddeliveredStimulusdeveloperConsortium+2MetaDataModel+11isDeveloperOfdevelopeddigitalIdentifierDOI+11AnatomicalAtlas+37isDigitalIdentifierOfidentifieseditorPersonBook+3isEditorOfeditedemitterOrganizationGenericIdentifierisEmitterOfemittedenvironmentVariablePropertyValueListLaunchConfigurationisEnvironmentVariableOfdefinesEnvironmentOffulfilledByConfiguration+4DependencyhasFulfilledfulfilsfullDocumentationDOI+3BrainAtlasVersion+9isFullDocumentationOffullyDocumentsgeneratedByElectrodeArrayUsage+5EphysStimulushasGeneratedgeneratedinspiredByFileAtlasAnnotation+1hasInspiredinspiredinsulatorMaterialChemicalMixture+2Electrode+1isInsulatorMaterialOfinsulateslabelingCompoundChemicalMixture+2PipetteUsageisLabelingCompoundOfusedToLabelmanufacturerConsortium+2Electrode+4isManufacturerOfmanufacturedperformedByPerson+1CellPatching+16hasPerformedperformedpublisherConsortium+2Book+3isPublisherOfpublishedspecificationConfiguration+4AtlasAnnotation+4isSpecificationOfspecifiesstartedByPerson+1DataAnalysis+7hasStartedstartedstudyTargetAnatomicalCavity+36CellPatching+19isStudyTargetOfstudiedInwasInformedByDataAnalysis+6DataAnalysis+6hasInformedinformedInaccurate or ambiguous
The name asserts something the schema does not, or does not say what the reverse returns
chemicalProductChemicalMixture+2AmountOfChemicalisChemicalProductOfusedInAmountcontributionContribution+2AnatomicalAtlas+32isContributionOfcontributedTocontributorConsortium+2ContributionisContributorOfcontributionmemberdoes: a person is not a contributor of a contribution record, they are the contributor named in itdependsOnAnatomicalAtlasVersion+6ServiceDeploymenthasDependentisDependencyOfdiseaseModelDisease+1StrainisDiseaseModelOfisModeledByDisease, soisDiseaseModelOfasserts that the disease is the model — it is the strain that isholderConsortium+2CopyrightisHolderOfholdsCopyrightCopyrightrecordslaunchConfigurationLaunchConfigurationDataAnalysis+6isConfiguredByconfiguresisConfiguredByinverts the direction — the reverse lives onLaunchConfiguration, which configures rather than is configuredmeasuredWithElectrodeArrayUsage+3MeasurementhasMeasurementusedToMeasureMeasurementtypememberConsortium+2MembershipisMemberOfhasMembershipobtainedWithElectrodeArrayUsage+5GridImage+4hasObtainedusedToObtainrecordedWithElectrodeArrayUsage+3RecordinghasRecordusedToRecordNote on
contribution. The property is used two ways in v5. Twenty-six research-product types embed aContributionrecord, while seven device types (Electrode,ElectrodeArray,MRICoil,MRIScanner,Pipette,SlicingDeviceandHardwareProduct) link straight toPerson/Organization. A single reverse name has to serve both, so #97's lands onPersonandOrganizationas well as onContribution. It is correct onContribution(Contribution.isContributionOf → [DatasetVersion, …]) and false on the other two (Person.isContributionOf → [MRIScanner, …]).contributedTois true on all three.Miscellaneous
Names that are more meaningful and/or are shorter.
conductorMaterialChemicalMixture+2Electrode+1isConductorMaterialOfisConductorOfdefaultImageFileCommonCoordinateFrameworkVersion+3isDefaultImageOfisDefaultImageForfailureImpactDependencyImpactDependencyisFailureImpactOfisImpactOfimplementsInterfaceVersionSoftwareVersionhasImplementationisImplementedBypreferredDisplayColorColormap+1ViewerSpecificationisPreferredDisplayColorOfpreferredBypreviewImageFileServiceLinkisPreviewImageOfisPreviewOfpreviousRecordingRecordingRecordinghasSubsequentRecordingnextRecordingspecialUsageRoleFileUsageRoleFile+1isSpecialUsageRoleOfappliesToFilestructurePatternFileRepositoryStructureFileRepositoryisStructurePatternOfrepositorystudiedSpecimenSubject+7DatasetVersionisStudiedSpecimenOfhasStudyResultsInstudiedStateSubjectGroupState+3Subject+3isStudiedStateOfisStateOfOne gap that will remain after rebasing onto
mainmainhas moved since this branch diverged, one change interacts with this PR:previousRegularTimeSerieswas added tomainafter the branch point, carries anasEdgeblock withnameForReverseLink: null, and is live in v5.0 onRegularTimeSeries. #97 never saw it, so it will still be null after merging.Suggested:
nextRegularTimeSeries, matching thepreviousRecording → nextRecordingproposed above.It is not included here because the property does not exist on this branch, so there is nothing to edit. I suggest opening a small follow-up PR after #97 has landed in "main".