# cldfviz
[](https://github.com/cldf/cldfviz/actions?query=workflow%3Atests)
[](https://pypi.org/project/cldfviz)
Python library providing tools to visualize [CLDF](https://cldf.clld.org) datasets.
## Install
Run
```shell
pip install cldfviz
```
If you want to create maps in image formats (PNG, JPG, PDF), the `cartopy` package is needed,
which will be installed with
```shell
pip install cldfviz[cartopy]
```
Note: Since `cartopy` has quite a few system-level requirements, installation may be somewhat tricky. Should
problems arise, https://scitools.org.uk/cartopy/docs/v0.15/installing.html may help.
If you want to create "treemaps" (i.e. use the [lingreemaps](https://lingtreemaps.readthedocs.io/en/latest/?badge=latest)
package for CLDF data), you need to install via
```shell
pip install cldfviz[lingtreemaps]
```
## CLI
`cldfviz` is implemented as [`cldfbench`](https://github.com/cldf/cldfbench)
plugin, i.e. it provides subcommands for the `cldfbench` command.
After installation you should see subcommands with a `cldfviz.` prefix
listed when running
```shell
cldfbench -h
```
Help provided by the CLI is sometimes extensive and can be consulted via
```shell
cldfbench <sucommand> -h
```
e.g.
```shell
$ cldfbench cldfviz.map -h
usage: cldfbench cldfviz.map [-h] [--download-dir DOWNLOAD_DIR] [--language-filters LANGUAGE_FILTERS]
[--glottolog GLOTTOLOG] [--glottolog-version GLOTTOLOG_VERSION]
...
```
## Commands
A short description of the `cldfviz` subcommands can be found below; for more documentation click on the images.
### Example data
Examples in this documentation sometimes use CLDF data stored in the local filesystem.
In particular, we'll use
- [](https://doi.org/10.5281/zenodo.7385533): WALS Online
- [](https://doi.org/10.5281/zenodo.7398887): Glottolog as CLDF dataset
- [](https://doi.org/10.5281/zenodo.7139937): APiCS Online
If you download these datasets using the `cldfbench` plugin [cldfzenodo](https://github.com/cldf/cldfzenodo/#cli)
```shell
cldfbench zenodo.download 10.5281/zenodo.7385533 --full-deposit
cldfbench zenodo.download 10.5281/zenodo.7398887 --full-deposit
cldfbench zenodo.download 10.5281/zenodo.7139937 --full-deposit
```
you should have the respective data in local directories `wals-2020.3/`, `glottolog-cldf-4.7/` and `cldf-datasets-apics-4ed59b5/`.
### `cldfviz.map`
A common way to visualize data from a CLDF StructureDataset is as "dots on a map",
i.e. as [WALS](https://wals.info)-like geographic maps, displaying typological variation.
The `cldfviz.map` subcommand allows you to create such maps. For details see [docs/map.md](docs/map.md).
[<img alt="details" width="350" src="docs/output/wals_10B.png" />](docs/map.md)
### `cldfviz.text`
A rather traditional visualization of linguistic data is the practice of interspersing bits of data
in descriptive texts, most obviously perhaps as examples formatted as **I**nterlinear **G**lossed **T**ext.
The `cldfviz.text` subcommand allows you "render" documents written in [CLDF markdown](https://github.com/cldf/cldf/blob/master/extensions/markdown.md), i.e. converting
such documents to plain markdown by inserting suitable representations of the referenced data.
For details see [docs/text.md](docs/text.md).
[<img alt="details" width="350" src="docs/output/wals_exponence.png" />](docs/text.md)
### `cldfviz.examples`
While it is possible to (selectively) include IGT formatted examples in [CLDF Markdown](https://github.com/cldf/cldf/blob/master/extensions/markdown.md) via `cldfviz.text`,
often it is useful to just look at an HTML formatted list of all examples from a dataset. This can
be done via `cldfviz.examples`. For details see [docs/examples.md](docs/examples.md).
[<img alt="details" width="350" src="docs/output/lgr_html.png" />](docs/examples.md)
### `cldfviz.tree`
Phylogenetic (or classification) trees of languages are a "proper" [CLDF component](https://github.com/cldf/cldf/tree/master/components/trees)
since CLDF 1.2 - and an obvious candidate for visualization (because noone likes to look at [Newick](https://en.wikipedia.org/wiki/Newick_format)).
To provide a configurable visualization of trees in [SVG format](https://en.wikipedia.org/wiki/SVG), the
`cldfviz.tree` command renders CLDF trees using the powerful [toytree](https://toytree.readthedocs.io/en/latest/)
package. For details see [docs/tree.md](docs/tree.md).
[<img alt="details" width="350" src="docs/output/wals-omotic.svg" />](docs/tree.md)
### `cldfviz.treemap`
Displaying maps and trees is nice, but visualizing how phylogeny relates to geography can also be done
in a more integrated way as demonstrated by the [lingtreemaps](https://lingtreemaps.readthedocs.io/en/latest/examples.html)
package. [cldfviz.treemap](docs/treemap.md) provides a front-end for this package, making it possible
to use its functionality with data and trees in CLDF datasets.
[<img alt="details" width="350" src="docs/output/treemap_wals88A.svg" />](docs/treemap.md)
### `cldfviz.audiowordlist`
Another case where it is often desirable to aggregate objects from different CLDF components
for inspection are Wordlists with associated audio files. Displaying forms for a specified
concept together with the audio as HTML page can be done running
[cldfviz.audiowordlist](docs/audiowordlist.md).
[<img alt="details" width="350" src="docs/output/awl_hindukush.png" />](docs/audiowordlist.md)
### `cldfviz.erd`
CLDF datasets typically contain multiple, related tables. The most common visualization of such a data model
are "entity-relationship diagrams", i.e. diagramy of the [entitty-relationship model](https://en.wikipedia.org/wiki/Entity%E2%80%93relationship_model)
of the dataset. Such a diagram can be created via `cldfviz.erd` (if a Java runtime is installed).
For details see [docs/erd.md](docs/erd.md).
[<img alt="details" width="350" src="docs/output/wacl.svg" />](docs/erd.md)
### `cldfviz.network`
A [ParameterNetwork component](https://github.com/cldf/cldf/tree/master/components/parameternetworks)
was added to CLDF with version 1.3, acknowledging that in datasets like [CLICS](https://clics.clld.org/)
a network of parameters (established through colexifications in CLICS) acted as both, output of the
colexification algorithm, but also as input for various cluster methods. Since there are many tools
for network analysis available, the main task for a CLDF-based tool is to convert (filtered) parts
of a `ParameterNetwork` to a format that can serve as input for other tools. This is what `cldfviz.network`
does and since [Graphviz' DOT format](https://graphviz.org/doc/info/lang.html) is one of the target
formats supported by `cldfviz.network`, exploratory analysis is supported by just piping the output
into the `dot` program to create a network visualization.
[<img alt="details" width="350" src="docs/output/partof_neck2.svg" />](docs/network.md)
## Related
Other tools to convert CLDF data to "human-readable" formats:
- [cldfofflinebrowser](https://github.com/cldf/cldfofflinebrowser)
- [clld](https://github.com/clld/clld)
Raw data
{
"_id": null,
"home_page": "https://github.com/cldf/cldfviz",
"name": "cldfviz",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "cldfbench",
"author": "Robert Forkel",
"author_email": "dlce.rdm@eva.mpg.de",
"download_url": "https://files.pythonhosted.org/packages/1b/4b/1ace14aada4fe763e60c73c95bab0984b70f901a09e5d578d43b9536f5aa/cldfviz-1.3.0.tar.gz",
"platform": "any",
"description": "# cldfviz\n\n[](https://github.com/cldf/cldfviz/actions?query=workflow%3Atests)\n[](https://pypi.org/project/cldfviz)\n\nPython library providing tools to visualize [CLDF](https://cldf.clld.org) datasets.\n\n\n## Install\n\nRun\n```shell\npip install cldfviz\n```\nIf you want to create maps in image formats (PNG, JPG, PDF), the `cartopy` package is needed,\nwhich will be installed with\n```shell\npip install cldfviz[cartopy]\n```\nNote: Since `cartopy` has quite a few system-level requirements, installation may be somewhat tricky. Should\nproblems arise, https://scitools.org.uk/cartopy/docs/v0.15/installing.html may help.\n\nIf you want to create \"treemaps\" (i.e. use the [lingreemaps](https://lingtreemaps.readthedocs.io/en/latest/?badge=latest)\npackage for CLDF data), you need to install via\n```shell\npip install cldfviz[lingtreemaps]\n```\n\n\n## CLI\n\n`cldfviz` is implemented as [`cldfbench`](https://github.com/cldf/cldfbench)\nplugin, i.e. it provides subcommands for the `cldfbench` command.\n\nAfter installation you should see subcommands with a `cldfviz.` prefix\nlisted when running\n```shell\ncldfbench -h\n```\n\nHelp provided by the CLI is sometimes extensive and can be consulted via\n```shell\ncldfbench <sucommand> -h\n```\ne.g.\n```shell\n$ cldfbench cldfviz.map -h\nusage: cldfbench cldfviz.map [-h] [--download-dir DOWNLOAD_DIR] [--language-filters LANGUAGE_FILTERS]\n [--glottolog GLOTTOLOG] [--glottolog-version GLOTTOLOG_VERSION]\n...\n```\n\n\n## Commands\n\nA short description of the `cldfviz` subcommands can be found below; for more documentation click on the images.\n\n\n### Example data\n\nExamples in this documentation sometimes use CLDF data stored in the local filesystem.\nIn particular, we'll use \n- [](https://doi.org/10.5281/zenodo.7385533): WALS Online\n- [](https://doi.org/10.5281/zenodo.7398887): Glottolog as CLDF dataset\n- [](https://doi.org/10.5281/zenodo.7139937): APiCS Online\n\nIf you download these datasets using the `cldfbench` plugin [cldfzenodo](https://github.com/cldf/cldfzenodo/#cli)\n```shell\ncldfbench zenodo.download 10.5281/zenodo.7385533 --full-deposit\ncldfbench zenodo.download 10.5281/zenodo.7398887 --full-deposit\ncldfbench zenodo.download 10.5281/zenodo.7139937 --full-deposit\n```\nyou should have the respective data in local directories `wals-2020.3/`, `glottolog-cldf-4.7/` and `cldf-datasets-apics-4ed59b5/`.\n\n\n### `cldfviz.map`\n\nA common way to visualize data from a CLDF StructureDataset is as \"dots on a map\",\ni.e. as [WALS](https://wals.info)-like geographic maps, displaying typological variation.\nThe `cldfviz.map` subcommand allows you to create such maps. For details see [docs/map.md](docs/map.md).\n\n[<img alt=\"details\" width=\"350\" src=\"docs/output/wals_10B.png\" />](docs/map.md)\n\n\n### `cldfviz.text`\n\nA rather traditional visualization of linguistic data is the practice of interspersing bits of data\nin descriptive texts, most obviously perhaps as examples formatted as **I**nterlinear **G**lossed **T**ext.\nThe `cldfviz.text` subcommand allows you \"render\" documents written in [CLDF markdown](https://github.com/cldf/cldf/blob/master/extensions/markdown.md), i.e. converting\nsuch documents to plain markdown by inserting suitable representations of the referenced data.\nFor details see [docs/text.md](docs/text.md).\n\n[<img alt=\"details\" width=\"350\" src=\"docs/output/wals_exponence.png\" />](docs/text.md)\n\n\n### `cldfviz.examples`\n\nWhile it is possible to (selectively) include IGT formatted examples in [CLDF Markdown](https://github.com/cldf/cldf/blob/master/extensions/markdown.md) via `cldfviz.text`,\noften it is useful to just look at an HTML formatted list of all examples from a dataset. This can\nbe done via `cldfviz.examples`. For details see [docs/examples.md](docs/examples.md).\n\n[<img alt=\"details\" width=\"350\" src=\"docs/output/lgr_html.png\" />](docs/examples.md)\n\n\n### `cldfviz.tree`\n\nPhylogenetic (or classification) trees of languages are a \"proper\" [CLDF component](https://github.com/cldf/cldf/tree/master/components/trees)\nsince CLDF 1.2 - and an obvious candidate for visualization (because noone likes to look at [Newick](https://en.wikipedia.org/wiki/Newick_format)).\n\nTo provide a configurable visualization of trees in [SVG format](https://en.wikipedia.org/wiki/SVG), the\n`cldfviz.tree` command renders CLDF trees using the powerful [toytree](https://toytree.readthedocs.io/en/latest/)\npackage. For details see [docs/tree.md](docs/tree.md).\n\n[<img alt=\"details\" width=\"350\" src=\"docs/output/wals-omotic.svg\" />](docs/tree.md)\n\n\n### `cldfviz.treemap`\n\nDisplaying maps and trees is nice, but visualizing how phylogeny relates to geography can also be done\nin a more integrated way as demonstrated by the [lingtreemaps](https://lingtreemaps.readthedocs.io/en/latest/examples.html)\npackage. [cldfviz.treemap](docs/treemap.md) provides a front-end for this package, making it possible\nto use its functionality with data and trees in CLDF datasets.\n\n[<img alt=\"details\" width=\"350\" src=\"docs/output/treemap_wals88A.svg\" />](docs/treemap.md)\n\n\n### `cldfviz.audiowordlist`\n\nAnother case where it is often desirable to aggregate objects from different CLDF components\nfor inspection are Wordlists with associated audio files. Displaying forms for a specified\nconcept together with the audio as HTML page can be done running\n[cldfviz.audiowordlist](docs/audiowordlist.md).\n\n[<img alt=\"details\" width=\"350\" src=\"docs/output/awl_hindukush.png\" />](docs/audiowordlist.md)\n\n\n### `cldfviz.erd`\n\nCLDF datasets typically contain multiple, related tables. The most common visualization of such a data model\nare \"entity-relationship diagrams\", i.e. diagramy of the [entitty-relationship model](https://en.wikipedia.org/wiki/Entity%E2%80%93relationship_model)\nof the dataset. Such a diagram can be created via `cldfviz.erd` (if a Java runtime is installed).\nFor details see [docs/erd.md](docs/erd.md).\n\n[<img alt=\"details\" width=\"350\" src=\"docs/output/wacl.svg\" />](docs/erd.md)\n\n\n### `cldfviz.network`\n\nA [ParameterNetwork component](https://github.com/cldf/cldf/tree/master/components/parameternetworks)\nwas added to CLDF with version 1.3, acknowledging that in datasets like [CLICS](https://clics.clld.org/)\na network of parameters (established through colexifications in CLICS) acted as both, output of the\ncolexification algorithm, but also as input for various cluster methods. Since there are many tools\nfor network analysis available, the main task for a CLDF-based tool is to convert (filtered) parts\nof a `ParameterNetwork` to a format that can serve as input for other tools. This is what `cldfviz.network`\ndoes and since [Graphviz' DOT format](https://graphviz.org/doc/info/lang.html) is one of the target\nformats supported by `cldfviz.network`, exploratory analysis is supported by just piping the output\ninto the `dot` program to create a network visualization.\n\n[<img alt=\"details\" width=\"350\" src=\"docs/output/partof_neck2.svg\" />](docs/network.md)\n\n\n## Related\n\nOther tools to convert CLDF data to \"human-readable\" formats:\n- [cldfofflinebrowser](https://github.com/cldf/cldfofflinebrowser)\n- [clld](https://github.com/clld/clld)\n\n\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "A cldfbench plugin to create vizualisations of CLDF datasets",
"version": "1.3.0",
"project_urls": {
"Bug Tracker": "https://github.com/cldf/cldfviz/issues",
"Homepage": "https://github.com/cldf/cldfviz"
},
"split_keywords": [
"cldfbench"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c7015e8fef2ba86aff4cfef439000d2043b49925aa1e30ca98e0710e14db16df",
"md5": "e833d53f7101018b34cf76b3a98e4cfd",
"sha256": "e3e534afdd8cfab5b138dcdf26f27699a35b087b75a3318003543047cae7e3c7"
},
"downloads": -1,
"filename": "cldfviz-1.3.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "e833d53f7101018b34cf76b3a98e4cfd",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.8",
"size": 1942168,
"upload_time": "2024-09-25T14:02:46",
"upload_time_iso_8601": "2024-09-25T14:02:46.187583Z",
"url": "https://files.pythonhosted.org/packages/c7/01/5e8fef2ba86aff4cfef439000d2043b49925aa1e30ca98e0710e14db16df/cldfviz-1.3.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1b4b1ace14aada4fe763e60c73c95bab0984b70f901a09e5d578d43b9536f5aa",
"md5": "b1941c6f0bd2d9d1028095a367397c20",
"sha256": "35cadadc4d28f2d39329260f5a8c78382f61bff3ac3e42ea6f1e03343743c976"
},
"downloads": -1,
"filename": "cldfviz-1.3.0.tar.gz",
"has_sig": false,
"md5_digest": "b1941c6f0bd2d9d1028095a367397c20",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 1941749,
"upload_time": "2024-09-25T14:02:59",
"upload_time_iso_8601": "2024-09-25T14:02:59.899104Z",
"url": "https://files.pythonhosted.org/packages/1b/4b/1ace14aada4fe763e60c73c95bab0984b70f901a09e5d578d43b9536f5aa/cldfviz-1.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-25 14:02:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cldf",
"github_project": "cldfviz",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "cldfviz"
}
JSON
