Skip to content

Commit 186e762

Browse files
Bento007Bento007
authored
chore: deprecate older version of cellxgene schema (#172)
## Reason for Change - automate the cellxgene schema versions deprecation process. - #170 ## Changes - add deprecation warning to API when older version of the cellxgene schema are used. - add logic to all_ontology_generator.py to remove expired ontology files from repo, expired cellxgene schema versions from ontology_info.json, and deprecate the previous cellxgene schema version if a new version exists. ## Testing steps - updated unit tests - Need to verify that files will be removed by the GHA. ## Notes for Reviewer
1 parent c0aec23 commit 186e762

File tree

9 files changed

+340
-110
lines changed

9 files changed

+340
-110
lines changed

‎.github/workflows/generate_all_ontology.yml

+1
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,7 @@ jobs:
4141
run: |
4242
python3 ./tools/ontology-builder/src/all_ontology_generator.py
4343
git add ./ontology-assets/*.json.gz
44+
git add ./ontology-assets/ontology_info.json
4445
- name: Commit
4546
run: |
4647
git commit -m "AUTO: update ontologies"

‎README.md

+5
Original file line numberDiff line numberDiff line change
@@ -16,3 +16,8 @@ This project adheres to the Contributor Covenant [code of conduct](https://githu
1616
## Reporting Security Issues
1717

1818
If you believe you have found a security issue, please responsibly disclose by contacting us at [[email protected]](mailto:[email protected]).
19+
20+
## Updating to a new Cellxgene Schema Version
21+
22+
1. Update the [ontology_info.json](./ontology-assets/ontology_info.json) file with the new schema version
23+
2. Leave the older versions in the file for backward compatibility. They will be deprecated and removed automatically after 6 months. That process is handled in [deprecate_previous_cellxgene_schema_versions](https://github.com/chanzuckerberg/cellxgene-ontology/blob/main/tools/ontology-builder/src/all_ontology_generator.py#L311-L311).

‎api/python/src/cellxgene_ontology_guide/supported_versions.py

+11-1
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22
import gzip
33
import json
44
import os
5+
import warnings
6+
from datetime import datetime
57
from typing import Any, Dict, List, Optional
68

79
from semantic_version import Version
@@ -63,8 +65,16 @@ def __init__(self, version: Optional[str] = None):
6365
raise ValueError(f"Schema version {version} is not supported in this package version.")
6466

6567
self.version = version
66-
self.supported_ontologies = ontology_info[version]
68+
self.supported_ontologies = ontology_info[version]["ontologies"]
6769
self.ontology_file_names: Dict[str, str] = {}
70+
self.deprecated_on = ontology_info[version].get("deprecated_on")
71+
if self.deprecated_on:
72+
parsed_date = datetime.strptime(self.deprecated_on, "%Y-%m-%d")
73+
warnings.warn(
74+
f"Schema version {version} is deprecated as of {parsed_date}. It will be removed in a future version.",
75+
DeprecationWarning,
76+
stacklevel=1,
77+
)
6878

6979
def ontology(self, name: str) -> Any:
7080
"""Return the ontology terms for the given ontology name. Load from the file cache if available.

‎api/python/tests/test_ontology_parser.py

+3-1
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,9 @@ def ontology_dict():
4343
@pytest.fixture
4444
def mock_CXGSchema(ontology_dict, mock_load_supported_versions, mock_load_ontology_file):
4545
mock_load_supported_versions.return_value = {
46-
"v5.0.0": {"CL": {"version": "2024-01-01", "source": "http://example.com", "filename": "cl.owl"}}
46+
"v5.0.0": {
47+
"ontologies": {"CL": {"version": "2024-01-01", "source": "http://example.com", "filename": "cl.owl"}}
48+
}
4749
}
4850
cxg_schema = CXGSchema()
4951
cxg_schema.ontology_file_names = {"CL": "CL-ontology-2024-01-01.json.gz"}

‎api/python/tests/test_supported_versions.py

+18-5
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,9 @@
1717
@pytest.fixture
1818
def initialized_CXGSchemaInfo(mock_load_supported_versions):
1919
mock_load_supported_versions.return_value = {
20-
"v5.0.0": {"CL": {"version": "v2024-01-01", "source": "http://example.com", "filename": "cl.owl"}}
20+
"v5.0.0": {
21+
"ontologies": {"CL": {"version": "v2024-01-01", "source": "http://example.com", "filename": "cl.owl"}}
22+
}
2123
}
2224
return CXGSchema()
2325

@@ -71,18 +73,29 @@ def test__load_supported_versions__OK(tmpdir):
7173

7274
class TestCXGSchema:
7375
def test__init__defaults(self, mock_load_supported_versions):
74-
support_versions = {"v5.0.0": "current version", "v0.0.1": "old version"}
76+
support_versions = {"v5.0.0": {"ontologies": {}}, "v0.0.1": {"ontologies": {}}}
7577
mock_load_supported_versions.return_value = support_versions
7678
cxgs = CXGSchema()
7779
assert cxgs.version == "v5.0.0"
78-
assert cxgs.supported_ontologies == support_versions["v5.0.0"]
80+
assert cxgs.supported_ontologies == support_versions["v5.0.0"]["ontologies"]
7981

8082
def test__init__specific_version(self, mock_load_supported_versions):
81-
support_versions = {"v5.0.0": "current version", "v0.0.1": "old version"}
83+
support_versions = {"v5.0.0": {"ontologies": {}}, "v0.0.1": {"ontologies": {}}}
8284
mock_load_supported_versions.return_value = support_versions
8385
cxgs = CXGSchema(version="v0.0.1")
8486
assert cxgs.version == "v0.0.1"
85-
assert cxgs.supported_ontologies == support_versions["v0.0.1"]
87+
assert cxgs.supported_ontologies == support_versions["v0.0.1"]["ontologies"]
88+
89+
def test__init__deprecated_version(self, mock_load_supported_versions):
90+
support_versions = {"v5.0.0": {"ontologies": {}}, "v0.0.1": {"ontologies": {}, "deprecated_on": "2024-01-01"}}
91+
mock_load_supported_versions.return_value = support_versions
92+
# catch the deprecation warning
93+
with pytest.warns(DeprecationWarning) as record:
94+
CXGSchema(version="v0.0.1")
95+
warning = record.pop()
96+
assert warning.message.args[0] == (
97+
"Schema version v0.0.1 is deprecated as of 2024-01-01 00:00:00. It will be removed in a " "future version."
98+
)
8699

87100
def test__init__unsupported_version(self, mock_load_supported_versions):
88101
mock_load_supported_versions.return_value = {}

‎artifact-schemas/ontology_info_schema.json

+38-26
Original file line numberDiff line numberDiff line change
@@ -8,34 +8,46 @@
88
"description": "The version of CellxGene schema that maps to this set of ontology versions",
99
"type": "object",
1010
"properties": {
11-
"CL": {
12-
"$ref": "#/definitions/ontologyEntry"
13-
},
14-
"EFO": {
15-
"$ref": "#/definitions/ontologyEntry"
16-
},
17-
"HANCESTRO": {
18-
"$ref": "#/definitions/ontologyEntry"
19-
},
20-
"HsapDv": {
21-
"$ref": "#/definitions/ontologyEntry"
22-
},
23-
"MONDO": {
24-
"$ref": "#/definitions/ontologyEntry"
25-
},
26-
"MmusDv": {
27-
"$ref": "#/definitions/ontologyEntry"
28-
},
29-
"NCBITaxon": {
30-
"$ref": "#/definitions/ontologyEntry"
31-
},
32-
"UBERON": {
33-
"$ref": "#/definitions/ontologyEntry"
11+
"deprecated_on": {
12+
"type": "string",
13+
"description": "The date this version was deprecated. The format of the date is YYYY-MM-DD. If this is the current verison then this field will be empty."
3414
},
35-
"PATO": {
36-
"$ref": "#/definitions/ontologyEntry"
15+
"ontologies": {
16+
"type": "object",
17+
"properties": {
18+
"CL": {
19+
"$ref": "#/definitions/ontologyEntry"
20+
},
21+
"EFO": {
22+
"$ref": "#/definitions/ontologyEntry"
23+
},
24+
"HANCESTRO": {
25+
"$ref": "#/definitions/ontologyEntry"
26+
},
27+
"HsapDv": {
28+
"$ref": "#/definitions/ontologyEntry"
29+
},
30+
"MONDO": {
31+
"$ref": "#/definitions/ontologyEntry"
32+
},
33+
"MmusDv": {
34+
"$ref": "#/definitions/ontologyEntry"
35+
},
36+
"NCBITaxon": {
37+
"$ref": "#/definitions/ontologyEntry"
38+
},
39+
"UBERON": {
40+
"$ref": "#/definitions/ontologyEntry"
41+
},
42+
"PATO": {
43+
"$ref": "#/definitions/ontologyEntry"
44+
}
45+
}
3746
}
38-
}
47+
},
48+
"required": [
49+
"ontologies"
50+
]
3951
}
4052
},
4153
"additionalProperties": false,

‎ontology-assets/ontology_info.json

+46-44
Original file line numberDiff line numberDiff line change
@@ -1,49 +1,51 @@
11
{
22
"v5.0.0": {
3-
"CL": {
4-
"version": "v2024-01-04",
5-
"source": "https://github.com/obophenotype/cell-ontology/releases/download",
6-
"filename": "cl.owl"
7-
},
8-
"EFO": {
9-
"version": "v3.62.0",
10-
"source": "https://github.com/EBISPOT/efo/releases/download",
11-
"filename": "efo.owl"
12-
},
13-
"HANCESTRO": {
14-
"version": "3.0",
15-
"source": "https://github.com/EBISPOT/hancestro/raw",
16-
"filename": "hancestro.owl"
17-
},
18-
"HsapDv": {
19-
"version": "11",
20-
"source": "http://aber-owl.net/media/ontologies/HSAPDV",
21-
"filename": "hsapdv.owl"
22-
},
23-
"MONDO": {
24-
"version": "v2024-01-03",
25-
"source": "https://github.com/monarch-initiative/mondo/releases/download",
26-
"filename": "mondo.owl"
27-
},
28-
"MmusDv": {
29-
"version": "9",
30-
"source": "http://aber-owl.net/media/ontologies/MMUSDV",
31-
"filename": "mmusdv.owl"
32-
},
33-
"NCBITaxon": {
34-
"version": "v2023-06-20",
35-
"source": "https://github.com/obophenotype/ncbitaxon/releases/download",
36-
"filename": "ncbitaxon.owl.gz"
37-
},
38-
"UBERON": {
39-
"version": "v2024-01-18",
40-
"source": "https://github.com/obophenotype/uberon/releases/download",
41-
"filename": "uberon.owl"
42-
},
43-
"PATO": {
44-
"version": "v2023-05-18",
45-
"source": "https://github.com/pato-ontology/pato/raw",
46-
"filename": "pato.owl"
3+
"ontologies": {
4+
"CL": {
5+
"version": "v2024-01-04",
6+
"source": "https://github.com/obophenotype/cell-ontology/releases/download",
7+
"filename": "cl.owl"
8+
},
9+
"EFO": {
10+
"version": "v3.62.0",
11+
"source": "https://github.com/EBISPOT/efo/releases/download",
12+
"filename": "efo.owl"
13+
},
14+
"HANCESTRO": {
15+
"version": "3.0",
16+
"source": "https://github.com/EBISPOT/hancestro/raw",
17+
"filename": "hancestro.owl"
18+
},
19+
"HsapDv": {
20+
"version": "11",
21+
"source": "http://aber-owl.net/media/ontologies/HSAPDV",
22+
"filename": "hsapdv.owl"
23+
},
24+
"MONDO": {
25+
"version": "v2024-01-03",
26+
"source": "https://github.com/monarch-initiative/mondo/releases/download",
27+
"filename": "mondo.owl"
28+
},
29+
"MmusDv": {
30+
"version": "9",
31+
"source": "http://aber-owl.net/media/ontologies/MMUSDV",
32+
"filename": "mmusdv.owl"
33+
},
34+
"NCBITaxon": {
35+
"version": "v2023-06-20",
36+
"source": "https://github.com/obophenotype/ncbitaxon/releases/download",
37+
"filename": "ncbitaxon.owl.gz"
38+
},
39+
"UBERON": {
40+
"version": "v2024-01-18",
41+
"source": "https://github.com/obophenotype/uberon/releases/download",
42+
"filename": "uberon.owl"
43+
},
44+
"PATO": {
45+
"version": "v2023-05-18",
46+
"source": "https://github.com/pato-ontology/pato/raw",
47+
"filename": "pato.owl"
48+
}
4749
}
4850
}
4951
}

0 commit comments

Comments
 (0)