Document both libraries at the repository root

Author: johngrimes

.gitignore

@@ -1,4 +1,21 @@
-/build/
-/fhir_tx_encoder.egg-info/
+# Python artefacts. The package moved to python/, so these are no longer
+# anchored at the repository root.
+python/build/
+python/dist/
+python/*.egg-info/
+__pycache__/
+.venv/
 Pipfile
 Pipfile.lock
+
+# R artefacts.
+.Rproj.user/
+.Rhistory
+r/*.tar.gz
+*.Rcheck/
+
+# Editor state.
+.idea/
+
+# Matrix Market exports.
+*.mtx

CONTRIBUTING.md

@@ -5,6 +5,66 @@ Thanks for your interest in contributing to "fhir-tx-encoder".
 You can find out a bit more about the project by reading the [README](README.md)
 file within this repository.
 
+## Repository layout
+
+The repository houses two implementations of the same encoder:
+
+| Directory | Package | Language |
+| --------- | ------- | -------- |
+| [`python/`](python) | `fhir-tx-encoder` (PyPI) | Python |
+| [`r/`](r) | `fhirtxencoder` (GitHub) | R |
+
+The community documents (this file, `README.md`, `LICENSE`,
+`CODE_OF_CONDUCT.md`) live at the root and cover both.
+
+### Why `python/LICENSE` is a symlink
+
+`python/LICENSE` is a symbolic link to the repository's root `LICENSE`. It is
+not a stray duplicate, and it should not be replaced with a copy or deleted.
+
+`python/setup.py` uses setuptools' default licence-file discovery, which only
+looks inside the package directory. Before the Python package moved from the
+repository root into `python/`, `LICENSE` sat next to `setup.py` and setuptools
+packaged it as `fhir_tx_encoder-<version>.dist-info/licenses/LICENSE`. The
+symlink keeps that true after the move, so the published wheel and sdist remain
+byte-identical to earlier releases. Removing it would silently drop the licence
+from the distributed artefact.
+
+Verify with:
+
+```bash
+cd python
+uv venv --python 3.11 && uv pip install build && uv run python -m build
+unzip -p dist/*.whl 'fhir_tx_encoder-*.dist-info/RECORD' | grep LICENSE
+```
+
+## Running the checks
+
+Python:
+
+```bash
+cd python
+uv venv --python 3.11
+uv run python -m build
+```
+
+Python 3.11 is pinned here because `setup.py` requires `scipy~=1.11.3`, which
+publishes no wheels for later Python versions.
+
+R (see [`r/README.md`](r/README.md) for detail):
+
+```bash
+Rscript -e 'devtools::test("r")'
+R CMD build r && R CMD check --as-cran fhirtxencoder_1.0.0.tar.gz
+Rscript -e 'print(covr::package_coverage("r"))'
+```
+
+The R unit suite answers every terminology server request from canned fixtures,
+so it needs no network. `r/tests/testthat/test-integration.R` is the exception:
+it runs the README example against the live CSIRO public Ontoserver, and is
+skipped when `NOT_CRAN` is unset, when the machine is offline, or when `CI` is
+set.
+
 ## Reporting issues
 
 Issues can be used to:
@@ -23,8 +83,14 @@ Your branch should be named `issue/[GitHub issue #]`.
 
 ### Coding conventions
 
-This repository uses [Black](https://github.com/psf/black), please use it to
-reformat your code before pushing.
+Python code in `python/` uses [Black](https://github.com/psf/black), please use
+it to reformat your code before pushing.
+
+R code in `r/` follows the [tidyverse style guide](https://style.tidyverse.org/)
+with an 80 character line limit. Every exported and internal function carries a
+roxygen2 block; regenerate `NAMESPACE` and `man/` with
+`Rscript -e 'roxygen2::roxygenise("r")'` after changing documentation. New
+behaviour needs a test - the R package is held at full line coverage.
 
 ## Code of conduct
 

README.md

@@ -0,0 +1,79 @@
+# FHIR Terminology Encoder
+
+Encoders that use a [FHIR](https://hl7.org/fhir/) terminology server to turn
+terminology codes into features for machine learning.
+
+You supply a scope in the form of a FHIR ValueSet URI and a FHIR terminology
+endpoint. The encoder expands the scope, retrieves the subsumption
+relationships between the concepts within it, and returns a multi-hot encoded
+sparse matrix. Each code carries a feature for itself and for every concept
+that subsumes it, so ontologically close codes share features. Concept
+properties can be included as additional features.
+
+This repository houses two implementations of the same idea:
+
+| Language | Directory | Package |
+| -------- | --------- | ------- |
+| Python   | [`python/`](python) | `fhir-tx-encoder` (PyPI) |
+| R        | [`r/`](r) | `fhirtxencoder` (GitHub) |
+
+## Python
+
+Install from PyPI:
+
+```bash
+pip install fhir-tx-encoder
+```
+
+```python
+from fhir_tx import FhirTerminologyEncoder
+import numpy as np
+
+encoder = FhirTerminologyEncoder(
+    # Ancestors of the SNOMED CT concept "Malignant neoplastic disease".
+    scope="http://snomed.info/sct?fhir_vs=ecl/(%3E%3E%20363346000)",
+    # Include "Associated morphology" (116676008) as a property.
+    properties=["116676008"],
+)
+
+result = encoder.fit_transform(np.array([["399981008"], ["363346000"]]))
+print(result.shape)  # (2, 9)
+print(encoder.feature_names_)
+```
+
+The encoder implements the scikit-learn transformer interface, so it can be
+used within a `Pipeline`. See [`python/README.md`](python/README.md) for the
+full documentation.
+
+## R
+
+Install from GitHub:
+
+```r
+remotes::install_github("aehrc/fhir-tx-encoder", subdir = "r")
+```
+
+```r
+library(fhirtxencoder)
+
+encoder <- fhir_tx_encoder(
+  # Ancestors of the SNOMED CT concept "Malignant neoplastic disease".
+  scope = "http://snomed.info/sct?fhir_vs=ecl/(%3E%3E%20363346000)",
+  # Include "Associated morphology" (116676008) as a property.
+  properties = c("116676008")
+)
+
+result <- transform(encoder, matrix(c("399981008", "363346000"), ncol = 1))
+dim(result)  # 2 9
+encoder$feature_names
+```
+
+See [`r/README.md`](r/README.md) for the full documentation.
+
+## Important note
+
+This software is currently in alpha. It is not yet ready for production use.
+
+Copyright © 2026, 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).