From 3bac3a9aed95826272c0da9b1d8157242a8ee814 Mon Sep 17 00:00:00 2001 From: Alex Nelson Date: Wed, 23 Nov 2022 11:23:13 -0500 Subject: [PATCH 1/2] Document --built-version flag No effects were observed on Make-managed files. References: * https://github.com/casework/CASE-Utilities-Python/issues/45 Signed-off-by: Alex Nelson --- README.md | 20 ++++++++++++++++++-- case_utils/case_sparql_construct/__init__.py | 2 +- case_utils/case_sparql_select/__init__.py | 2 +- case_utils/case_validate/__init__.py | 2 +- 4 files changed, 21 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 802e678..b7205ac 100644 --- a/README.md +++ b/README.md @@ -55,12 +55,17 @@ To produce the validation report as a machine-readable graph output, the `--form case_validate --format turtle input.json > result.ttl ``` -To use one or more supplementary ontology files, the `--ontology-graph` flag can be used, more than once if desired, to supplement the selected CASE version: +To use one or more supplementary ontology or shapes files, the `--ontology-graph` flag can be used, more than once if desired, to supplement the selected CASE version: ```bash -case_validate --ontology-graph internal_ontology.ttl --ontology-graph experimental_shapes.ttl input.json +case_validate \ + --ontology-graph internal_ontology.ttl \ + --ontology-graph experimental_shapes.ttl \ + input.json ``` +This tool uses the `--built-version` flag, described [below](#built-versions). + Other flags are reviewable with `case_validate --help`. @@ -87,6 +92,8 @@ These commands can be used with any RDF files to run arbitrary SPARQL queries. Note that prefixes used in the SPARQL queries do not need to be defined in the SPARQL query. Their mapping will be inherited from their first definition in the input graph files. However, input graphs are not required to agree on prefix mappings, so there is potential for confusion from input argument order mattering if two input graph files disagree on what a prefix maps to. If there is concern of ambiguity from inputs, a `PREFIX` statement should be included in the query, such as is shown in [this test query](tests/case_utils/case_sparql_select/subclass.sparql). +These tools use the `--built-version` flag, described [below](#built-versions). + #### `case_sparql_construct` @@ -116,6 +123,15 @@ case_sparql_select output.md input.sparql input.json [input-2.json ...] This [module](case_utils/local_uuid.py) provides a wrapper UUID generator, `local_uuid()`. Its main purpose is making example data generate consistent identifiers, and intentionally includes mechanisms to make it difficult to activate this mode without awareness of the caller. +### Built versions + +Several tools in this package include a flag `--built-version`. This flag tailors the tool's behavior to a certain CASE ontology version; typically, this involves mixing the ontology graph into the data graph for certain necessary knowledge expansion for pattern matching (such as making queries aware of the OWL subclass hierarchy). + +If not provided, the tool will assume a default value of the latest ontology version. + +If the special value `none` is provided, none of the ontology builds this package ships will be included in the data graph. The `none` value supports use cases that are wholly independent of CASE, such as running a test in a specialized vocabulary; and also suports use cases where a non-released CASE version is meant to be used, such as a locally revised version of CASE where some concept revisions are being reviewed. + + ## Development status This repository follows [CASE community guidance on describing development status](https://caseontology.org/resources/software.html#development_status), by adherence to noted support requirements. diff --git a/case_utils/case_sparql_construct/__init__.py b/case_utils/case_sparql_construct/__init__.py index f8f62b4..abb55f5 100644 --- a/case_utils/case_sparql_construct/__init__.py +++ b/case_utils/case_sparql_construct/__init__.py @@ -49,7 +49,7 @@ def main() -> None: "--built-version", choices=tuple(built_version_choices_list), default="case-" + CURRENT_CASE_VERSION, - help="Ontology version to use to supplement query, such as for subclass querying. Does not require networking to use. Default is most recent CASE release.", + help="Ontology version to use to supplement query, such as for subclass querying. Does not require networking to use. Default is most recent CASE release. Passing 'none' will mean no pre-built CASE ontology versions accompanying this tool will be included in the analysis.", ) parser.add_argument( "--disallow-empty-results", diff --git a/case_utils/case_sparql_select/__init__.py b/case_utils/case_sparql_select/__init__.py index f609a12..0874483 100644 --- a/case_utils/case_sparql_select/__init__.py +++ b/case_utils/case_sparql_select/__init__.py @@ -63,7 +63,7 @@ def main() -> None: "--built-version", choices=tuple(built_version_choices_list), default="case-" + CURRENT_CASE_VERSION, - help="Ontology version to use to supplement query, such as for subclass querying. Does not require networking to use. Default is most recent CASE release.", + help="Ontology version to use to supplement query, such as for subclass querying. Does not require networking to use. Default is most recent CASE release. Passing 'none' will mean no pre-built CASE ontology versions accompanying this tool will be included in the analysis.", ) parser.add_argument( "--disallow-empty-results", diff --git a/case_utils/case_validate/__init__.py b/case_utils/case_validate/__init__.py index c278fee..15ab11e 100644 --- a/case_utils/case_validate/__init__.py +++ b/case_utils/case_validate/__init__.py @@ -92,7 +92,7 @@ def main() -> None: "--built-version", choices=tuple(built_version_choices_list), default="case-" + CURRENT_CASE_VERSION, - help="Monolithic aggregation of CASE ontology files at certain versions. Does not require networking to use. Default is most recent CASE release.", + help="Monolithic aggregation of CASE ontology files at certain versions. Does not require networking to use. Default is most recent CASE release. Passing 'none' will mean no pre-built CASE ontology versions accompanying this tool will be included in the analysis.", ) parser.add_argument( "--ontology-graph", From f6522a43cdf49f23319839526d29a9b64827b9d3 Mon Sep 17 00:00:00 2001 From: Alex Nelson Date: Wed, 23 Nov 2022 11:46:54 -0500 Subject: [PATCH 2/2] Adjust spelling Signed-off-by: Alex Nelson --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index b7205ac..d1e6ff9 100644 --- a/README.md +++ b/README.md @@ -55,7 +55,7 @@ To produce the validation report as a machine-readable graph output, the `--form case_validate --format turtle input.json > result.ttl ``` -To use one or more supplementary ontology or shapes files, the `--ontology-graph` flag can be used, more than once if desired, to supplement the selected CASE version: +To use one or more supplementary ontology or shape files, the `--ontology-graph` flag can be used, more than once if desired, to supplement the selected CASE version: ```bash case_validate \