pathling 9.0.0.dev1__tar.gz → 9.1.0.dev0__tar.gz

pathling-9.1.0.dev0/.gitignore

@@ -0,0 +1,3 @@
+build
+.coverage
+bin

{pathling-9.0.0.dev1 → pathling-9.1.0.dev0}/LICENSE

@@ -194,20 +194,20 @@ separate files distributed with the Software.
 * (Apache License, Version 2.0) Apache Commons BeanUtils (commons-beanutils:commons-beanutils:1.11.0 - https://commons.apache.org/proper/commons-beanutils)
 * (Apache License, Version 2.0) Apache Commons IO (commons-io:commons-io:2.16.1 - https://commons.apache.org/proper/commons-io/)
 * (Apache License, Version 2.0) Commons Lang (commons-lang:commons-lang:2.6 - http://commons.apache.org/lang/)
-* (Apache License, Version 2.0) delta-spark (io.delta:delta-spark_2.12:3.3.2 - https://delta.io/)
+* (Apache License, Version 2.0) delta-spark (io.delta:delta-spark_2.13:4.0.0 - https://delta.io/)
+* (Apache License, Version 2.0) ucumate-core (io.github.fhnaumann:ucumate-core:1.0.8 - https://github.com/fhnaumann/ucumate)
+* (EPL 2.0) (GPL2 w/ CPE) Jakarta Servlet (jakarta.servlet:jakarta.servlet-api:5.0.0 - https://projects.eclipse.org/projects/ee4j.servlet)
 * (Apache License, Version 2.0) Jakarta Bean Validation API (jakarta.validation:jakarta.validation-api:3.0.2 - https://beanvalidation.org)
-* (CDDL + GPLv2 with classpath exception) Java Servlet API (jakarta.servlet:jakarta.servlet-api:5.0.0 - https://javaee.github.io/servlet-spec/)
 * (Apache License, Version 2.0) Joda-Time (joda-time:joda-time:2.12.7 - https://www.joda.org/joda-time/)
-* (BSD License) ANTLR 4 Tool (org.antlr:antlr4:4.9.3 - http://www.antlr.org)
+* (BSD License) ANTLR 4 Tool (org.antlr:antlr4:4.13.1 - http://www.antlr.org)
 * (Apache License, Version 2.0) Apache Commons Lang (org.apache.commons:commons-lang3:3.18.0 - https://commons.apache.org/proper/commons-lang/)
 * (Apache License, Version 2.0) Apache Derby Tools (org.apache.derby:derbytools:10.16.1.1 - http://db.apache.org/derby/)
-* (Apache License, Version 2.0) Apache Hadoop Amazon Web Services support (org.apache.hadoop:hadoop-aws:3.3.4 - no url defined)
-* (Apache License, Version 2.0) Apache Hadoop Client API (org.apache.hadoop:hadoop-client-api:3.3.4 - no url defined)
-* (Apache License, Version 2.0) Spark Project Catalyst (org.apache.spark:spark-catalyst_2.12:3.5.6 - https://spark.apache.org/)
-* (Apache License, Version 2.0) Spark Project Core (org.apache.spark:spark-core_2.12:3.5.6 - https://spark.apache.org/)
-* (Apache License, Version 2.0) Spark Project Hive (org.apache.spark:spark-hive_2.12:3.5.6 - https://spark.apache.org/)
-* (Apache License, Version 2.0) Spark Project SQL (org.apache.spark:spark-sql_2.12:3.5.6 - https://spark.apache.org/)
-* (Apache License, Version 2.0) Spark Project Unsafe (org.apache.spark:spark-unsafe_2.12:3.5.6 - https://spark.apache.org/)
+* (Apache License, Version 2.0) Apache Hadoop Client API (org.apache.hadoop:hadoop-client-api:3.4.1 - no url defined)
+* (Apache License, Version 2.0) Spark Project Catalyst (org.apache.spark:spark-catalyst_2.13:4.0.1 - https://spark.apache.org/)
+* (Apache License, Version 2.0) Spark Project Core (org.apache.spark:spark-core_2.13:4.0.1 - https://spark.apache.org/)
+* (Apache License, Version 2.0) Spark Project Hive (org.apache.spark:spark-hive_2.13:4.0.1 - https://spark.apache.org/)
+* (Apache License, Version 2.0) Spark Project SQL (org.apache.spark:spark-sql_2.13:4.0.1 - https://spark.apache.org/)
+* (Apache License, Version 2.0) Spark Project Unsafe (org.apache.spark:spark-unsafe_2.13:4.0.1 - https://spark.apache.org/)
 * (Apache License, Version 2.0) Awaitility (org.awaitility:awaitility:4.2.0 - http://awaitility.org)
 * (Apache License, Version 2.0) Hibernate Validator Engine (org.hibernate.validator:hibernate-validator:8.0.1.Final - http://hibernate.org/validator/hibernate-validator)
 * (Apache License, Version 2.0) Infinispan Commons (org.infinispan:infinispan-commons:15.0.3.Final - http://www.infinispan.org)
@@ -221,7 +221,7 @@ separate files distributed with the Software.
 * (GNU General Public License (GPL), version 2, with the Classpath exception) JMH Core (org.openjdk.jmh:jmh-core:1.37 - http://openjdk.java.net/projects/code-tools/jmh/jmh-core/)
 * (GNU General Public License (GPL), version 2, with the Classpath exception) JMH Generators: Annotation Processors (org.openjdk.jmh:jmh-generator-annprocess:1.37 - http://openjdk.java.net/projects/code-tools/jmh/jmh-generator-annprocess/)
 * (MIT License) Project Lombok (org.projectlombok:lombok:1.18.38 - https://projectlombok.org)
-* (Apache License, Version 2.0) Scala Library (org.scala-lang:scala-library:2.12.17 - https://www.scala-lang.org/)
+* (Apache License, Version 2.0) Scala Library (org.scala-lang:scala-library:2.13.15 - https://www.scala-lang.org/)
 * (Apache License, Version 2.0) JSONassert (org.skyscreamer:jsonassert:1.5.1 - https://github.com/skyscreamer/JSONassert)
 * (MIT License) SLF4J API Module (org.slf4j:slf4j-api:2.0.17 - http://www.slf4j.org)
 * (Apache License, Version 2.0) spring-boot-starter-test (org.springframework.boot:spring-boot-starter-test:3.3.11 - https://spring.io/projects/spring-boot)

{pathling-9.0.0.dev1/pathling.egg-info → pathling-9.1.0.dev0}/PKG-INFO

@@ -1,34 +1,21 @@
 Metadata-Version: 2.4
 Name: pathling
-Version: 9.0.0.dev1
+Version: 9.1.0.dev0
 Summary: Python API for Pathling
-Home-page: https://github.com/aehrc/pathling
-Author: Australian e-Health Research Centre, CSIRO
-Author-email: pathling@csiro.au
+Project-URL: Homepage, https://github.com/aehrc/pathling
+Author-email: "Australian e-Health Research Centre, CSIRO" <pathling@csiro.au>
 License: Apache License, version 2.0
-Keywords: pathling,fhir,analytics,spark,standards,terminology
+License-File: LICENSE
+Keywords: analytics,fhir,pathling,spark,standards,terminology
 Classifier: Development Status :: 3 - Alpha
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: pyspark<4.1.0,>=4.0.0
 Requires-Dist: deprecated>=1.2.13
-Dynamic: author
-Dynamic: author-email
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: home-page
-Dynamic: keywords
-Dynamic: license
-Dynamic: license-file
-Dynamic: requires-dist
-Dynamic: requires-python
-Dynamic: summary
+Requires-Dist: pyspark<4.1.0,>=4.0.0
+Description-Content-Type: text/markdown
 
 Python API for Pathling
 =======================

pathling-9.1.0.dev0/examples/data/csv/conditions.csv

@@ -0,0 +1,20 @@
+START,STOP,PATIENT,ENCOUNTER,CODE,DESCRIPTION
+2012-10-24,,95d8fdbf-cb4c-7133-1b5f-ab23979febe6,5a0b7744-aceb-15ac-280e-8070b01f1fb4,65363002,Otitis media
+2015-06-24,2015-10-17,95d8fdbf-cb4c-7133-1b5f-ab23979febe6,0e105151-b37f-f62e-802f-beb66ba5fbc6,16114001,Fracture of ankle
+2015-11-13,2015-11-22,95d8fdbf-cb4c-7133-1b5f-ab23979febe6,ce85c3fd-7cc6-481b-6a07-0c46110197a1,444814009,Viral sinusitis (disorder)
+2016-12-22,2017-01-08,95d8fdbf-cb4c-7133-1b5f-ab23979febe6,0fd0b06b-1a99-7ebc-6d0f-a508f78e061f,444814009,Viral sinusitis (disorder)
+2014-06-05,2014-06-16,866f8524-ddd3-2e28-01ac-035e0d1832be,ffb4d9fb-5cd4-bf1f-5a18-833c8ade3993,43878008,Streptococcal sore throat (disorder)
+2019-02-24,2019-03-07,866f8524-ddd3-2e28-01ac-035e0d1832be,39b7146d-43b7-dc66-830b-f0051bd0ac1b,195662009,Acute viral pharyngitis (disorder)
+2013-10-31,2013-11-15,bbf93c9f-90f8-10ad-19b8-9ce4a7908d19,840ed7b9-00c6-00c1-a485-57400c569bff,10509002,Acute bronchitis (disorder)
+2004-01-15,,7316444b-558c-cf79-31d2-c4041929c344,add7491c-9521-5ed4-a161-7a4657e66341,65363002,Otitis media
+2012-08-04,2012-08-17,7316444b-558c-cf79-31d2-c4041929c344,f373fdb2-afb7-298c-bc5e-f3b98816f233,43878008,Streptococcal sore throat (disorder)
+2013-03-04,2013-04-05,7316444b-558c-cf79-31d2-c4041929c344,05c0cac5-ce66-7268-030c-1feb42c8bcda,403190006,First degree burn
+2013-06-27,2013-07-05,7316444b-558c-cf79-31d2-c4041929c344,362f70ee-f8a5-19da-24cb-4e3081dbb106,10509002,Acute bronchitis (disorder)
+2019-09-17,2019-11-21,7316444b-558c-cf79-31d2-c4041929c344,ba21ca9b-4692-2829-f333-531530e27d22,65966004,Fracture of forearm
+2014-04-14,2014-04-26,bbf93c9f-90f8-10ad-19b8-9ce4a7908d19,1c2b48dc-718f-07e7-3f92-d4172f8b51d0,195662009,Acute viral pharyngitis (disorder)
+2011-08-03,,f850b736-c3be-c2d0-5784-f551019956e1,1b81f386-65ae-4a26-343f-a7b2653020e1,65363002,Otitis media
+1987-05-28,,d0237a49-0d92-7514-0613-16685a9c9a3d,da768855-91a7-54d5-839b-931c365a9437,65363002,Otitis media
+2016-06-18,2016-07-11,d0237a49-0d92-7514-0613-16685a9c9a3d,e522ae5f-39fa-ab59-6aa7-dd15618a0312,444814009,Viral sinusitis (disorder)
+1980-01-02,,f07f926b-d82f-3ba5-1898-7fdb82160336,258a40e0-5248-958f-ea21-24247790a245,65363002,Otitis media
+2014-03-15,2014-10-18,f07f926b-d82f-3ba5-1898-7fdb82160336,09ccf1a1-0de0-1ecb-4cf2-3dd5fff14ec5,72892002,Normal pregnancy
+2013-03-05,2013-03-12,f850b736-c3be-c2d0-5784-f551019956e1,3c1ac45a-9063-8eb2-9e3d-399c6d9f140d,195662009,Acute viral pharyngitis (disorder)

{pathling-9.0.0.dev1 → pathling-9.1.0.dev0}/pathling/_version.py

@@ -2,8 +2,8 @@
 # Auto generated from POM project version.
 # Please do not modify.
 #
-__version__="9.0.0.dev1"
-__java_version__="9.0.0-SNAPSHOT"
+__version__="9.1.0.dev0"
+__java_version__="9.1.0-SNAPSHOT"
 __scala_version__="2.13"
 __delta_version__="4.0.0"
 __hadoop_version__="3.4.1"

{pathling-9.0.0.dev1 → pathling-9.1.0.dev0}/pathling/context.py

@@ -99,6 +99,8 @@ class PathlingContext:
         scope: Optional[str] = None,
         token_expiry_tolerance: Optional[int] = 120,
         accept_language: Optional[str] = None,
+        explain_queries: Optional[bool] = False,
+        max_unbound_traversal_depth: Optional[int] = 10,
         enable_delta=False,
         enable_remote_debugging: Optional[bool] = False,
         debug_port: Optional[int] = 5005,
@@ -173,6 +175,11 @@ class PathlingContext:
                the header is not sent. The server can use the header to return the result in the
                preferred language if it is able. The actual behaviour may depend on the server
                implementation and the code systems used.
+        :param explain_queries: setting this option to `True` will enable additional logging relating
+               to the query plan used to execute queries
+        :param max_unbound_traversal_depth: maximum depth for self-referencing structure traversals
+               in repeat operations. Controls how deeply nested hierarchical data can be flattened
+               during projection.
         :param enable_delta: enables the use of Delta for storage of FHIR data.
                Only supported when no SparkSession is provided.
         :param enable_remote_debugging: enables remote debugging for the JVM process.
@@ -270,8 +277,20 @@ class PathlingContext:
             .build()
         )
 
-        jpc: JavaObject = jvm.au.csiro.pathling.library.PathlingContext.create(
-            spark._jsparkSession, encoders_config, terminology_config
+        # Build a query configuration object from the provided parameters.
+        query_config = (
+            jvm.au.csiro.pathling.config.QueryConfiguration.builder()
+            .explainQueries(explain_queries)
+            .maxUnboundTraversalDepth(max_unbound_traversal_depth)
+            .build()
+        )
+
+        jpc: JavaObject = (
+            jvm.au.csiro.pathling.library.PathlingContext.builder(spark._jsparkSession)
+            .encodingConfiguration(encoders_config)
+            .terminologyConfiguration(terminology_config)
+            .queryConfiguration(query_config)
+            .build()
         )
         return PathlingContext(spark, jpc)
 

pathling-9.1.0.dev0/pyproject.toml

@@ -0,0 +1,78 @@
+#  Copyright © 2018-2025 Commonwealth Scientific and Industrial Research
+#  Organisation (CSIRO) ABN 41 687 119 230.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pathling"
+dynamic = ["version"]
+description = "Python API for Pathling"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Apache License, version 2.0" }
+authors = [
+    { name = "Australian e-Health Research Centre, CSIRO", email = "pathling@csiro.au" }
+]
+keywords = ["pathling", "fhir", "analytics", "spark", "standards", "terminology"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+]
+dependencies = [
+    "pyspark>=4.0.0,<4.1.0",
+    "deprecated>=1.2.13",
+]
+
+[project.urls]
+Homepage = "https://github.com/aehrc/pathling"
+
+[dependency-groups]
+dev = [
+    "Sphinx>=1.6,<8",
+    "sphinx-rtd-theme==1.2.2",
+    "pytest==8.2.0",
+    "ipython==8.10.0",
+    "wheel==0.43.0",
+    "twine==5.0.0",
+    "build==1.2.1",
+    "pytest-cov==5.0.0",
+    "http-server-mock==1.7",
+]
+
+[tool.hatch.version]
+path = "pathling/_version.py"
+pattern = '__version__="(?P<version>[^"]+)"'
+
+[tool.hatch.build.targets.wheel]
+packages = ["pathling"]
+artifacts = [
+    "target/dependency/*.jar",
+]
+
+[tool.hatch.build.targets.wheel.shared-data]
+"examples" = "share/pathling/examples"
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/pathling",
+    "/examples",
+    "/README.md",
+    "/LICENSE",
+]

pathling-9.0.0.dev1/MANIFEST.in

@@ -1,2 +0,0 @@
-global-exclude *.py[cod] __pycache__ .DS_Store
-recursive-include target/dependency library-runtime-*.jar

pathling-9.0.0.dev1/PKG-INFO

@@ -1,404 +0,0 @@
-Metadata-Version: 2.4
-Name: pathling
-Version: 9.0.0.dev1
-Summary: Python API for Pathling
-Home-page: https://github.com/aehrc/pathling
-Author: Australian e-Health Research Centre, CSIRO
-Author-email: pathling@csiro.au
-License: Apache License, version 2.0
-Keywords: pathling,fhir,analytics,spark,standards,terminology
-Classifier: Development Status :: 3 - Alpha
-Classifier: License :: OSI Approved :: Apache Software License
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: pyspark<4.1.0,>=4.0.0
-Requires-Dist: deprecated>=1.2.13
-Dynamic: author
-Dynamic: author-email
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: home-page
-Dynamic: keywords
-Dynamic: license
-Dynamic: license-file
-Dynamic: requires-dist
-Dynamic: requires-python
-Dynamic: summary
-
-Python API for Pathling
-=======================
-
-This is the Python API for [Pathling](https://pathling.csiro.au). It provides a
-set of tools that aid the use of FHIR terminology services and FHIR data within
-Python applications and data science workflows.
-
-[View the API documentation &rarr;](https://pathling.csiro.au/docs/python/pathling.html)
-
-## Installation
-
-Prerequisites:
-
-- Python 3.9+ with pip
-
-To install, run this command:
-
-```bash
-pip install pathling  
-```
-
-## Encoders
-
-The Python library features a set of encoders for converting FHIR data into
-Spark dataframes.
-
-### Reading in NDJSON
-
-[NDJSON](http://ndjson.org) is a format commonly used for bulk FHIR data, and
-consists of files (one per resource type) that contains one JSON resource per
-line.
-
-```python
-from pathling import PathlingContext
-
-pc = PathlingContext.create()
-
-# Read each line from the NDJSON into a row within a Spark data set.
-ndjson_dir = '/some/path/ndjson/'
-json_resources = pc.spark.read.text(ndjson_dir)
-
-# Convert the data set of strings into a structured FHIR data set.
-patients = pc.encode(json_resources, 'Patient')
-
-# Do some stuff.
-patients.select('id', 'gender', 'birthDate').show()
-```
-
-### Reading in Bundles
-
-The FHIR [Bundle](https://hl7.org/fhir/R4/bundle.html) resource can contain a
-collection of FHIR resources. It is often used to represent a set of related
-resources, perhaps generated as part of the same event.
-
-```python
-from pathling import PathlingContext
-
-pc = PathlingContext.create()
-
-# Read each Bundle into a row within a Spark data set.
-bundles_dir = '/some/path/bundles/'
-bundles = pc.spark.read.text(bundles_dir, wholetext=True)
-
-# Convert the data set of strings into a structured FHIR data set.
-patients = pc.encode_bundle(bundles, 'Patient')
-
-# JSON is the default format, XML Bundles can be encoded using input type.
-# patients = pc.encodeBundle(bundles, 'Patient', inputType=MimeType.FHIR_XML)
-
-# Do some stuff.
-patients.select('id', 'gender', 'birthDate').show()
-```
-
-## Running SQL on FHIR views
-
-The Pathling library leverages the SQL on FHIR specification to provide a way to
-project FHIR data into easy-to-use tabular forms.
-
-Once you have transformed your FHIR data into tabular views, you can choose to
-keep it in a Spark dataframe and continue to work with in Apache Spark, or
-export it to Python or R dataframes or a variety of different file formats for
-use in the tool of your choice.
-
-```python
-from pathling import PathlingContext
-
-pc = PathlingContext.create()
-data = pc.read.ndjson("/some/file/location")
-
-result = data.view(
-    resource="Patient",
-    select=[
-        {"column": [{"path": "getResourceKey()", "name": "patient_id"}]},
-        {
-            "forEach": "address",
-            "column": [
-                {"path": "line.join('\\n')", "name": "street"},
-                {"path": "use", "name": "use"},
-                {"path": "city", "name": "city"},
-                {"path": "postalCode", "name": "zip"},
-            ],
-        },
-    ],
-)
-
-display(result)
-```
-
-The result of this query would look something like this:
-
-| patient_id | street                     | use  | city       | zip   |
-|------------|----------------------------|------|------------|-------|
-| 1          | 398 Kautzer Walk Suite 62  | home | Barnstable | 02675 |
-| 1          | 186 Nitzsche Forge         | work | Revere     | 02151 |
-| 2          | 1087 Quitzon Club          | home | Plymouth   | NULL  |
-| 3          | 442 Bruen Arcade           | home | Nantucket  | NULL  |
-| 4          | 858 Miller Junction Apt 61 | work | Brockton   | 02301 |
-
-For a more comprehensive example demonstrating SQL on FHIR queries with multiple
-views, complex transformations and joins, see
-the [SQL on FHIR example](https://pathling.csiro.au/docs/libraries/examples/prostate-cancer.md).
-
-## Terminology functions
-
-The library also provides a set of functions for querying a FHIR terminology
-server from within your queries and transformations.
-
-### Value set membership
-
-The `member_of` function can be used to test the membership of a code within a
-[FHIR value set](https://hl7.org/fhir/valueset.html). This can be used with both
-explicit value sets (i.e. those that have been pre-defined and loaded into the
-terminology server) and implicit value sets (e.g. SNOMED CT
-[Expression Constraint Language](http://snomed.org/ecl)).
-
-In this example, we take a list of SNOMED CT diagnosis codes and
-create a new column which shows which are viral infections. We use an ECL
-expression to define viral infection as a disease with a pathological process
-of "Infectious process", and a causative agent of "Virus".
-
-```python
-result = pc.member_of(csv, to_coding(csv.CODE, 'http://snomed.info/sct'),
-                      to_ecl_value_set("""
-<< 64572001|Disease| : (
-  << 370135005|Pathological process| = << 441862004|Infectious process|,
-  << 246075003|Causative agent| = << 49872002|Virus|
-)
-                      """), 'VIRAL_INFECTION')
-result.select('CODE', 'DESCRIPTION', 'VIRAL_INFECTION').show()
-```
-
-Results in:
-
-| CODE      | DESCRIPTION               | VIRAL_INFECTION |
-|-----------|---------------------------|-----------------|
-| 65363002  | Otitis media              | false           |
-| 16114001  | Fracture of ankle         | false           |
-| 444814009 | Viral sinusitis           | true            |
-| 444814009 | Viral sinusitis           | true            |
-| 43878008  | Streptococcal sore throat | false           |
-
-### Concept translation
-
-The `translate` function can be used to translate codes from one code system to
-another using maps that are known to the terminology server. In this example, we
-translate our SNOMED CT diagnosis codes into Read CTV3.
-
-```python
-result = pc.translate(csv, to_coding(csv.CODE, 'http://snomed.info/sct'),
-                      'http://snomed.info/sct/900000000000207008?fhir_cm='
-                      '900000000000497000',
-                      output_column_name='READ_CODE')
-result = result.withColumn('READ_CODE', result.READ_CODE.code)
-result.select('CODE', 'DESCRIPTION', 'READ_CODE').show()
-```
-
-Results in:
-
-| CODE      | DESCRIPTION               | READ_CODE |
-|-----------|---------------------------|-----------|
-| 65363002  | Otitis media              | X00ik     |
-| 16114001  | Fracture of ankle         | S34..     |
-| 444814009 | Viral sinusitis           | XUjp0     |
-| 444814009 | Viral sinusitis           | XUjp0     |
-| 43878008  | Streptococcal sore throat | A340.     |
-
-### Subsumption testing
-
-Subsumption test is a fancy way of saying "is this code equal or a subtype of
-this other code".
-
-For example, a code representing "ankle fracture" is subsumed
-by another code representing "fracture". The "fracture" code is more general,
-and using it with subsumption can help us find other codes representing
-different subtypes of fracture.
-
-The `subsumes` function allows us to perform subsumption testing on codes within
-our data. The order of the left and right operands can be reversed to query
-whether a code is "subsumed by" another code.
-
-```python
-# 232208008 |Ear, nose and throat disorder|
-left_coding = Coding('http://snomed.info/sct', '232208008')
-right_coding_column = to_coding(csv.CODE, 'http://snomed.info/sct')
-
-result = pc.subsumes(csv, 'IS_ENT',
-                     left_coding=left_coding,
-                     right_coding_column=right_coding_column)
-
-result.select('CODE', 'DESCRIPTION', 'IS_ENT').show()
-```
-
-Results in:
-
-| CODE      | DESCRIPTION       | IS_ENT |
-|-----------|-------------------|--------|
-| 65363002  | Otitis media      | true   |
-| 16114001  | Fracture of ankle | false  |
-| 444814009 | Viral sinusitis   | true   |
-
-### Retrieving properties
-
-Some terminologies contain additional properties that are associated with codes.
-You can query these properties using the `property_of` function.
-
-There is also a `display` function that can be used to retrieve the preferred
-display term for each code.
-
-```python
-# Get the parent codes for each code in the dataset.
-parents = csv.withColumn(
-    "PARENTS",
-    property_of(to_snomed_coding(csv.CODE), "parent", PropertyType.CODE),
-)
-# Split each parent code into a separate row.
-exploded_parents = parents.selectExpr(
-    "CODE", "DESCRIPTION", "explode_outer(PARENTS) AS PARENT"
-)
-# Retrieve the preferred term for each parent code.
-with_displays = exploded_parents.withColumn(
-    "PARENT_DISPLAY", display(to_snomed_coding(exploded_parents.PARENT))
-)
-```
-
-Results in:
-
-| CODE      | DESCRIPTION       | PARENT    | PARENT_DISPLAY                          |
-|-----------|-------------------|-----------|-----------------------------------------|
-| 65363002  | Otitis media      | 43275000  | Otitis                                  |
-| 65363002  | Otitis media      | 68996008  | Disorder of middle ear                  |
-| 16114001  | Fracture of ankle | 125603006 | Injury of ankle                         |
-| 16114001  | Fracture of ankle | 46866001  | Fracture of lower limb                  |
-| 444814009 | Viral sinusitis   | 36971009  | Sinusitis                               |
-| 444814009 | Viral sinusitis   | 281794004 | Viral upper respiratory tract infection |
-| 444814009 | Viral sinusitis   | 363166002 | Infective disorder of head              |
-| 444814009 | Viral sinusitis   | 36971009  | Sinusitis                               |
-| 444814009 | Viral sinusitis   | 281794004 | Viral upper respiratory tract infection |
-| 444814009 | Viral sinusitis   | 363166002 | Infective disorder of head              |
-
-### Retrieving designations
-
-Some terminologies contain additional display terms for codes. These can be used
-for language translations, synonyms, and more. You can query these terms using
-the `designation` function.
-
-```python
-# Get the synonyms for each code in the dataset.
-synonyms = csv.withColumn(
-    "SYNONYMS",
-    designation(to_snomed_coding(csv.CODE),
-                Coding.of_snomed("900000000000013009")),
-)
-# Split each synonyms into a separate row.
-exploded_synonyms = synonyms.selectExpr(
-    "CODE", "DESCRIPTION", "explode_outer(SYNONYMS) AS SYNONYM"
-)
-```
-
-Results in:
-
-| CODE      | DESCRIPTION                          | SYNONYM                                    |
-|-----------|--------------------------------------|--------------------------------------------|
-| 65363002  | Otitis media                         | OM - Otitis media                          |
-| 16114001  | Fracture of ankle                    | Ankle fracture                             |
-| 16114001  | Fracture of ankle                    | Fracture of distal end of tibia and fibula |
-| 444814009 | Viral sinusitis (disorder)           | NULL                                       |
-| 444814009 | Viral sinusitis (disorder)           | NULL                                       |
-| 43878008  | Streptococcal sore throat (disorder) | Septic sore throat                         |
-| 43878008  | Streptococcal sore throat (disorder) | Strep throat                               |
-| 43878008  | Streptococcal sore throat (disorder) | Strept throat                              |
-| 43878008  | Streptococcal sore throat (disorder) | Streptococcal angina                       |
-| 43878008  | Streptococcal sore throat (disorder) | Streptococcal pharyngitis                  |
-
-### Terminology server authentication
-
-Pathling can be configured to connect to a protected terminology server by
-supplying a set of OAuth2 client credentials and a token endpoint.
-
-Here is an example of how to authenticate to
-the [NHS terminology server](https://ontology.nhs.uk/):
-
-```python
-from pathling import PathlingContext
-
-pc = PathlingContext.create(
-    terminology_server_url='https://ontology.nhs.uk/production1/fhir',
-    token_endpoint='https://ontology.nhs.uk/authorisation/auth/realms/nhs-digital-terminology/protocol/openid-connect/token',
-    client_id='[client ID]',
-    client_secret='[client secret]'
-)
-```
-
-## Installation in Databricks
-
-To make the Pathling library available within notebooks, navigate to the
-"Compute" section and click on the cluster. Click on the "Libraries" tab, and
-click "Install new".
-
-Install both the `pathling` PyPI package, and
-the `au.csiro.pathling:library-api`
-Maven package. Once the cluster is restarted, the libraries should be available
-for import and use within all notebooks.
-
-By default, Databricks uses Java 8 within its clusters, while Pathling requires
-Java 21. To enable Java 21 support within your cluster, navigate to __Advanced
-Options > Spark > Environment Variables__ and add the following:
-
-```bash
-JNAME=zulu21-ca-amd64
-```
-
-See the Databricks documentation on
-[Libraries](https://docs.databricks.com/libraries/index.html) for more
-information.
-
-## Spark cluster configuration
-
-If you are running your own Spark cluster, or using a Docker image (such as
-[jupyter/pyspark-notebook](https://hub.docker.com/r/jupyter/pyspark-notebook))
-,
-you will need to configure Pathling as a Spark package.
-
-You can do this by adding the following to your `spark-defaults.conf` file:
-
-```
-spark.jars.packages au.csiro.pathling:library-api:[some version]
-```
-
-See the [Configuration](https://spark.apache.org/docs/latest/configuration.html)
-page of the Spark documentation for more information about `spark.jars.packages`
-and other related configuration options.
-
-To create a Pathling notebook Docker image, your `Dockerfile` might look like
-this:
-
-```dockerfile
-FROM jupyter/pyspark-notebook
-
-USER root
-RUN echo "spark.jars.packages au.csiro.pathling:library-api:[some version]" >> /usr/local/spark/conf/spark-defaults.conf
-
-USER ${NB_UID}
-
-RUN pip install --quiet --no-cache-dir pathling && \
-    fix-permissions "${CONDA_DIR}" && \
-    fix-permissions "/home/${NB_USER}"
-```
-
-Pathling is copyright © 2018-2025, Commonwealth Scientific and Industrial
-Research Organisation
-(CSIRO) ABN 41 687 119 230. Licensed under
-the [Apache License, version 2.0](https://www.apache.org/licenses/LICENSE-2.0).