# 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)
## 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": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "cldfbench",
"author": "Robert Forkel",
"author_email": "dlce.rdm@eva.mpg.de",
"download_url": "https://files.pythonhosted.org/packages/e5/13/97379726afb095e931062abf33e781cc5ebb0df8b1d826e8332def09a0e4/cldfviz-1.0.2.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## 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.0.2",
"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": "a70e0b1cbb7581322e36d27c9525ed9f20bf7665f5b6426bc021981a54d82709",
"md5": "bddfd857be034ea5240d719e07a4cad1",
"sha256": "8203f1b31deb4a199be37f19619aa5df32809a0f03f1f6ce37b64c1ab8861301"
},
"downloads": -1,
"filename": "cldfviz-1.0.2-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "bddfd857be034ea5240d719e07a4cad1",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.8",
"size": 1938664,
"upload_time": "2023-12-05T14:14:07",
"upload_time_iso_8601": "2023-12-05T14:14:07.841136Z",
"url": "https://files.pythonhosted.org/packages/a7/0e/0b1cbb7581322e36d27c9525ed9f20bf7665f5b6426bc021981a54d82709/cldfviz-1.0.2-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e51397379726afb095e931062abf33e781cc5ebb0df8b1d826e8332def09a0e4",
"md5": "a7a9c5f2b315aa2945be9215c316d83b",
"sha256": "e32a0acb7178b09f5f2e9e98983b5438cca291906cc91dfd5b375a6c5bf78fef"
},
"downloads": -1,
"filename": "cldfviz-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "a7a9c5f2b315aa2945be9215c316d83b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 1938222,
"upload_time": "2023-12-05T14:14:19",
"upload_time_iso_8601": "2023-12-05T14:14:19.546910Z",
"url": "https://files.pythonhosted.org/packages/e5/13/97379726afb095e931062abf33e781cc5ebb0df8b1d826e8332def09a0e4/cldfviz-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-05 14:14:19",
"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
