Metadata-Version: 2.4
Name: pyitalic
Version: 0.1.0
Summary: Interface to the ITALIC database of lichen biodiversity
Project-URL: Homepage, https://github.com/plant-data/pyitalic
Project-URL: Repository, https://github.com/plant-data/pyitalic
Project-URL: Issues, https://github.com/plant-data/pyitalic/issues
Project-URL: Documentation, https://italic.units.it/index.php?procedure=api
Author: Luana Francesconi, Alice Musina, Luca Di Nuzzo, Gabriele Gheza, Chiara Pistocchi, Juri Nascimbene, Pier Luigi Nimis, Stefano Martellos
Author-email: Matteo Conti <matt.ciao@gmail.com>
Maintainer-email: Matteo Conti <matt.ciao@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ITALIC,Italy,biodiversity,lichens,occurrences,taxonomy
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: pandas>=2.0
Requires-Dist: tqdm>=4.0
Provides-Extra: map
Requires-Dist: geopandas>=0.14; extra == 'map'
Requires-Dist: matplotlib>=3.7; extra == 'map'
Description-Content-Type: text/markdown

# pyitalic

**pyitalic** is a Python package that gives you access to
[ITALIC](https://italic.units.it/) mediated data via its
[RESTful API](https://italic.units.it/index.php?procedure=api).

It is a Python port of the R package
[ritalic](https://github.com/plant-data/ritalic), exposing the same functions
(the R `italic_*` exports become `pyitalic.match`, `pyitalic.taxonomy`, ...).

**ITALIC**, the Information System on Italian Lichens, makes available
information and resources about the lichens known to occur in Italy and
bordering countries. It is maintained and updated by the Research Unit of
Professor Pier Luigi Nimis, at the University of Trieste (NE Italy), Department
of Life Sciences. Most of the data are derived from the Checklist of the Lichens
of Italy by Nimis (2016), but nomenclatural and distributional data are being
continuously updated.

## Installation

```bash
pip install pyitalic
```

The distribution-map function (`distribution_map`) needs extra
geospatial/plotting dependencies (geopandas + matplotlib). Install them with:

```bash
pip install "pyitalic[map]"
```

## Usage

```python
import pyitalic

# Match scientific names against the Checklist of the Lichens of Italy
matched = pyitalic.match("Cetraria islandica")
accepted = matched["accepted_name"]

# Retrieve data for accepted names
pyitalic.taxonomy(accepted)
pyitalic.ecology_traits(accepted)
pyitalic.regions_distribution(accepted)
pyitalic.ecoregions_distribution(accepted)

# Occurrence records and their references
occ = pyitalic.occurrences("Cetraria ericetorum Opiz")
pyitalic.occurrences_references(occ)

# The full checklist (optionally filtered)
pyitalic.checklist(genus="Lecanora")

# A distribution map (requires the [map] extra)
fig = pyitalic.distribution_map("Flavoparmelia caperata (L.) Hale")
fig.savefig("flavoparmelia.png")
```

Most functions accept a single name (`str`) or several names
(`list[str]` / `pandas.Series`) and return a `pandas.DataFrame`.

### Available functions

| Function | Description |
|---|---|
| `match` | Match scientific names against the ITALIC checklist |
| `checklist` | Accepted names in the Checklist of the Lichens of Italy |
| `taxonomy` | Taxonomic classification |
| `name_usage` | Name metadata (IDs, status, authorship) |
| `description` | Morphological descriptions and notes |
| `ecology_traits` | Morpho-functional traits and ecological indicators |
| `traits_pa` | Presence/absence matrix of morphological traits |
| `regions_distribution` | Presence/absence across Italian administrative regions |
| `ecoregions_distribution` | Commonness/rarity across Italian ecoregions |
| `occurrences` | Herbarium occurrence records (Darwin Core) |
| `occurrences_references` | Bibliographic references for occurrence datasets |
| `taxon_data` | Combined taxonomy + ecology + distribution data |
| `identification_key` | URL to an interactive identification key |
| `distribution_map` | Distribution map (requires the `[map]` extra) |

## License

MIT
