{"id":29499821,"url":"https://github.com/globaldothealth/adtl","last_synced_at":"2026-01-26T12:17:03.545Z","repository":{"id":65777282,"uuid":"592231702","full_name":"globaldothealth/adtl","owner":"globaldothealth","description":"Another data transformation language","archived":false,"fork":false,"pushed_at":"2025-07-14T17:04:49.000Z","size":1359,"stargazers_count":2,"open_issues_count":6,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-07-14T22:13:05.720Z","etag":null,"topics":["data-transformation","json","parser","python"],"latest_commit_sha":null,"homepage":"https://adtl.readthedocs.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/globaldothealth.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-01-23T09:13:47.000Z","updated_at":"2025-07-08T14:33:37.000Z","dependencies_parsed_at":"2023-03-10T19:01:21.577Z","dependency_job_id":"31afb855-f3b1-4a13-9ff2-dfc161ebb97d","html_url":"https://github.com/globaldothealth/adtl","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/globaldothealth/adtl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/globaldothealth%2Fadtl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/globaldothealth%2Fadtl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/globaldothealth%2Fadtl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/globaldothealth%2Fadtl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/globaldothealth","download_url":"https://codeload.github.com/globaldothealth/adtl/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/globaldothealth%2Fadtl/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265459608,"owners_count":23769417,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["data-transformation","json","parser","python"],"created_at":"2025-07-15T21:01:30.803Z","updated_at":"2026-01-26T12:17:03.539Z","avatar_url":"https://github.com/globaldothealth.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# adtl – another data transformation language\n\n[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)\n\n[![tests](https://github.com/globaldothealth/adtl/actions/workflows/tests.yml/badge.svg)](https://github.com/globaldothealth/adtl/actions/workflows/tests.yml)\n[![codecov](https://codecov.io/gh/globaldothealth/adtl/branch/main/graph/badge.svg?token=QTD7HRR3TO)](https://codecov.io/gh/globaldothealth/adtl)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n\n\nadtl is a data transformation language (DTL) used by some applications in\n[Global.health](https://global.health), notably for the ISARIC clinical data pipeline at\n[globaldothealth/isaric](https://github.com/globaldothealth/isaric) and the InsightBoard\nproject dashboard at [globaldothealth/InsightBoard](https://github.com/globaldothealth/InsightBoard)\n\nDocumentation: [ReadTheDocs](https://adtl.readthedocs.io/en/latest/index.html)\n\n## Installation\n\nYou can install this package using either [`pipx`](https://pypa.github.io/pipx/)\nor `pip`. Installing via `pipx` offers advantages if you want to just use the\n`adtl` tool standalone from the command line, as it isolates the Python\npackage dependencies in a virtual environment. On the other hand, `pip` installs\npackages to the global environment which is generally not recommended as it\ncan interfere with other packages on your system.\n\n* Installation via `pipx`:\n\n  ```shell\n  pipx install adtl\n  ```\n\n* Installation via `pip`:\n\n  ```shell\n  python3 -m pip install adtl\n  ```\n\nIf you are writing code which depends on adtl (instead of using the\ncommand-line program), then it is best to add a dependency on `adtl` to your\nPython build tool of choice.\n\nTo use the development version, replace `adtl` with the full GitHub URL:\n\n```shell\npip install git+https://github.com/globaldothealth/adtl\n```\n\n## Rationale\n\nMost existing data transformation languages are usually in a XML dialect, though\nthere are recent variations in other file formats. In addition, many DTLs use a\ncustom domain specific language. The primary utility of this DTL is to provide a\neasy to use library in Python for basic data transformations, which are\nspecified in a JSON file. It is not meant to be a comprehensive, and adtl can\nbe used as a step within a larger data processing pipeline.\n\n## Usage\n\nadtl can be used from the command line or as a Python library\n\nAs a CLI:\n```bash\nadtl parse specification-file input-file\n```\n\nHere *specification-file* is the parser specification (as TOML or JSON)\nand *input-file* is the data file (not the data dictionary) that adtl\nwill transform using the instructions in the specification.\n\nIf adtl is not in your PATH, this may give an error. Either add the location\nwhere the adtl script is installed to your PATH, or try running adtl as a module\n\n```shell\npython3 -m adtl parse specification-file input-file\n```\n\nRunning adtl will create output files with the name of the parser, suffixed with\ntable names in the current working directory.\n\nBefore trying to transform your data, you can check that your specification file matches\nthe format adtl expects, and for fields which may have been either misspelled or missed out\nduring the mapping, by using:\n```bash\nadtl check specification-file input-file\n```\n\nPython library:\n```python\nimport adtl\n\nparser = adtl.Parser(specification)\nprint(parser.tables) # list of tables created\n\nfor row in parser.parse().read_table(table):\n    print(row)\n```\nalternatively to get an output file as a CSV, similarly to the CLI:\n```python\nimport adtl\n\ndata = adtl.parse(\"specification-file\", \"input-file\")\n```\nwhere `data` is returned as a dictionary of pandas dataframes, one for each table.\n\n## Development\n\nInstall [pre-commit](https://pre-commit.com) and setup pre-commit hooks\n(`pre-commit install`) which will do linting checks before commit.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fglobaldothealth%2Fadtl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fglobaldothealth%2Fadtl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fglobaldothealth%2Fadtl/lists"}