pyinaturalist-convert


Namepyinaturalist-convert JSON
Version 0.6.5 PyPI version JSON
download
home_pagehttps://github.com/pyinat/pyinaturalist-convert
SummaryData conversion tools for iNaturalist observations and taxonomy
upload_time2024-07-22 18:54:53
maintainerNone
docs_urlNone
authorJordan Cook
requires_python<4.0,>=3.8
licenseMIT
keywords inaturalist biodiversity export convert csv darwin-core dataframe gpx
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls. 
            # pyinaturalist-convert
[![Build status](https://github.com/pyinat/pyinaturalist-convert/workflows/Build/badge.svg?branch=main)](https://github.com/pyinat/pyinaturalist-convert/actions)
[![codecov](https://codecov.io/gh/pyinat/pyinaturalist-convert/branch/main/graph/badge.svg?token=Mt3V5H409C)](https://codecov.io/gh/pyinat/pyinaturalist-convert)
[![Docs](https://img.shields.io/readthedocs/pyinaturalist-convert/stable)](https://pyinaturalist-convert.readthedocs.io)
[![PyPI](https://img.shields.io/pypi/v/pyinaturalist-convert?color=blue)](https://pypi.org/project/pyinaturalist-convert)
[![Conda](https://img.shields.io/conda/vn/conda-forge/pyinaturalist-convert?color=blue)](https://anaconda.org/conda-forge/pyinaturalist-convert)
[![PyPI - Python Versions](https://img.shields.io/pypi/pyversions/pyinaturalist-convert)](https://pypi.org/project/pyinaturalist-convert)

This package provides tools to convert iNaturalist observation data to and from a wide variety of
useful formats. This is mainly intended for use with the iNaturalist API
via [pyinaturalist](https://github.com/niconoe/pyinaturalist), but also works with other data sources.

Complete project documentation can be found at [pyinaturalist-convert.readthedocs.io](https://pyinaturalist-convert.readthedocs.io).

# Formats
## Import
* CSV (From either [API results](https://www.inaturalist.org/pages/api+reference#get-observations)
 or the [iNaturalist export tool](https://www.inaturalist.org/observations/export))
* JSON (from API results)
* [`pyinaturalist.Observation`](https://pyinaturalist.readthedocs.io/en/stable/modules/pyinaturalist.models.Observation.html) objects
* Dataframes, Feather, Parquet, and anything else supported by [pandas](https://pandas.pydata.org/pandas-docs/stable/user_guide/io.html)
* [iNaturalist GBIF Archive](https://www.inaturalist.org/pages/developers)
* [iNaturalist Taxonomy Archive](https://www.inaturalist.org/pages/developers)
* [iNaturalist Open Data on Amazon](https://github.com/inaturalist/inaturalist-open-data)
* Note: see [API Recommended Practices](https://www.inaturalist.org/pages/api+recommended+practices)
  for details on which data sources are best suited to different use cases

## Export
* CSV, Excel, and anything else supported by [tablib](https://tablib.readthedocs.io/en/stable/formats/)
* Dataframes, Feather, Parquet, and anything else supported by [pandas](https://pandas.pydata.org/pandas-docs/stable/user_guide/io.html)
* Darwin Core
* GeoJSON
* GPX
* SQLite
* SQLite + FTS5 text search for taxonomy

# Installation
Install with pip:
```bash
pip install pyinaturalist-convert
```

Or with conda:
```bash
conda install -c conda-forge pyinaturalist-convert
```

To keep things modular, many format-specific dependencies are not installed by default, so you may
need to install some more packages depending on which features you want. Each module's docs lists
any extra dependencies needed, and a full list can be found in
[pyproject.toml](https://github.com/pyinat/pyinaturalist-convert/blob/main/pyproject.toml#L27).

For getting started, it's recommended to install all optional dependencies:
```bash
pip install pyinaturalist-convert[all]
```

# Usage

## Export
Get your own observations and save to CSV:
```python
from pyinaturalist import get_observations
from pyinaturalist_convert import *

observations = get_observations(user_id='my_username')
to_csv(observations, 'my_observations.csv')
```

Or any other supported format:
```python
to_dwc(observations, 'my_observations.dwc')
to_excel(observations, 'my_observations.xlsx')
to_feather(observations, 'my_observations.feather')
to_geojson(observations, 'my_observations.geojson')
to_gpx(observations, 'my_observations.gpx')
to_hdf(observations, 'my_observations.hdf')
to_json(observations, 'my_observations.json')
to_parquet(observations, 'my_observations.parquet')
df = to_dataframe(observations)
```

## Import
Most file formats can be loaded via `pyinaturalist_convert.read()`:
```python
observations = read('my_observations.csv')
observations = read('my_observations.xlsx')
observations = read('my_observations.feather')
observations = read('my_observations.hdf')
observations = read('my_observations.json')
observations = read('my_observations.parquet')
```

## Download
Download the complete research-grade observations dataset:
```python
download_dwca_observations()
```

And load it into a SQLite database:
```python
load_dwca_observations()
```

And do the same with the complete taxonomy dataset:
```python
download_dwca_taxa()
load_dwca_taxa()
```

Load taxonomy data into a full text search database:
```python
load_taxon_fts_table(languages=['english', 'german'])
```

And get lightning-fast autocomplete results from it:
```python
ta = TaxonAutocompleter()
ta.search('aves')
ta.search('flughund', language='german')
```

# Feedback
If you have any problems, suggestions, or questions about pyinaturalist-convert, you are welcome to [create an issue](https://github.com/pyinat/pyinaturalist-convert/issues/new/choose) or [discussion](https://github.com/orgs/pyinat/discussions). Also, **PRs are welcome!**

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/pyinat/pyinaturalist-convert",
    "name": "pyinaturalist-convert",
    "maintainer": null,
    "docs_url": null,
    "requires_python": "<4.0,>=3.8",
    "maintainer_email": null,
    "keywords": "inaturalist, biodiversity, export, convert, csv, darwin-core, dataframe, gpx",
    "author": "Jordan Cook",
    "author_email": null,
    "download_url": "https://files.pythonhosted.org/packages/4f/ff/3cdab0c0628f0e1a953dbcce90bc71dd5cbf8b1434fbf16dc1185090a850/pyinaturalist_convert-0.6.5.tar.gz",
    "platform": null,
    "description": "# pyinaturalist-convert\n[![Build status](https://github.com/pyinat/pyinaturalist-convert/workflows/Build/badge.svg?branch=main)](https://github.com/pyinat/pyinaturalist-convert/actions)\n[![codecov](https://codecov.io/gh/pyinat/pyinaturalist-convert/branch/main/graph/badge.svg?token=Mt3V5H409C)](https://codecov.io/gh/pyinat/pyinaturalist-convert)\n[![Docs](https://img.shields.io/readthedocs/pyinaturalist-convert/stable)](https://pyinaturalist-convert.readthedocs.io)\n[![PyPI](https://img.shields.io/pypi/v/pyinaturalist-convert?color=blue)](https://pypi.org/project/pyinaturalist-convert)\n[![Conda](https://img.shields.io/conda/vn/conda-forge/pyinaturalist-convert?color=blue)](https://anaconda.org/conda-forge/pyinaturalist-convert)\n[![PyPI - Python Versions](https://img.shields.io/pypi/pyversions/pyinaturalist-convert)](https://pypi.org/project/pyinaturalist-convert)\n\nThis package provides tools to convert iNaturalist observation data to and from a wide variety of\nuseful formats. This is mainly intended for use with the iNaturalist API\nvia [pyinaturalist](https://github.com/niconoe/pyinaturalist), but also works with other data sources.\n\nComplete project documentation can be found at [pyinaturalist-convert.readthedocs.io](https://pyinaturalist-convert.readthedocs.io).\n\n# Formats\n## Import\n* CSV (From either [API results](https://www.inaturalist.org/pages/api+reference#get-observations)\n or the [iNaturalist export tool](https://www.inaturalist.org/observations/export))\n* JSON (from API results)\n* [`pyinaturalist.Observation`](https://pyinaturalist.readthedocs.io/en/stable/modules/pyinaturalist.models.Observation.html) objects\n* Dataframes, Feather, Parquet, and anything else supported by [pandas](https://pandas.pydata.org/pandas-docs/stable/user_guide/io.html)\n* [iNaturalist GBIF Archive](https://www.inaturalist.org/pages/developers)\n* [iNaturalist Taxonomy Archive](https://www.inaturalist.org/pages/developers)\n* [iNaturalist Open Data on Amazon](https://github.com/inaturalist/inaturalist-open-data)\n* Note: see [API Recommended Practices](https://www.inaturalist.org/pages/api+recommended+practices)\n  for details on which data sources are best suited to different use cases\n\n## Export\n* CSV, Excel, and anything else supported by [tablib](https://tablib.readthedocs.io/en/stable/formats/)\n* Dataframes, Feather, Parquet, and anything else supported by [pandas](https://pandas.pydata.org/pandas-docs/stable/user_guide/io.html)\n* Darwin Core\n* GeoJSON\n* GPX\n* SQLite\n* SQLite + FTS5 text search for taxonomy\n\n# Installation\nInstall with pip:\n```bash\npip install pyinaturalist-convert\n```\n\nOr with conda:\n```bash\nconda install -c conda-forge pyinaturalist-convert\n```\n\nTo keep things modular, many format-specific dependencies are not installed by default, so you may\nneed to install some more packages depending on which features you want. Each module's docs lists\nany extra dependencies needed, and a full list can be found in\n[pyproject.toml](https://github.com/pyinat/pyinaturalist-convert/blob/main/pyproject.toml#L27).\n\nFor getting started, it's recommended to install all optional dependencies:\n```bash\npip install pyinaturalist-convert[all]\n```\n\n# Usage\n\n## Export\nGet your own observations and save to CSV:\n```python\nfrom pyinaturalist import get_observations\nfrom pyinaturalist_convert import *\n\nobservations = get_observations(user_id='my_username')\nto_csv(observations, 'my_observations.csv')\n```\n\nOr any other supported format:\n```python\nto_dwc(observations, 'my_observations.dwc')\nto_excel(observations, 'my_observations.xlsx')\nto_feather(observations, 'my_observations.feather')\nto_geojson(observations, 'my_observations.geojson')\nto_gpx(observations, 'my_observations.gpx')\nto_hdf(observations, 'my_observations.hdf')\nto_json(observations, 'my_observations.json')\nto_parquet(observations, 'my_observations.parquet')\ndf = to_dataframe(observations)\n```\n\n## Import\nMost file formats can be loaded via `pyinaturalist_convert.read()`:\n```python\nobservations = read('my_observations.csv')\nobservations = read('my_observations.xlsx')\nobservations = read('my_observations.feather')\nobservations = read('my_observations.hdf')\nobservations = read('my_observations.json')\nobservations = read('my_observations.parquet')\n```\n\n## Download\nDownload the complete research-grade observations dataset:\n```python\ndownload_dwca_observations()\n```\n\nAnd load it into a SQLite database:\n```python\nload_dwca_observations()\n```\n\nAnd do the same with the complete taxonomy dataset:\n```python\ndownload_dwca_taxa()\nload_dwca_taxa()\n```\n\nLoad taxonomy data into a full text search database:\n```python\nload_taxon_fts_table(languages=['english', 'german'])\n```\n\nAnd get lightning-fast autocomplete results from it:\n```python\nta = TaxonAutocompleter()\nta.search('aves')\nta.search('flughund', language='german')\n```\n\n# Feedback\nIf you have any problems, suggestions, or questions about pyinaturalist-convert, you are welcome to [create an issue](https://github.com/pyinat/pyinaturalist-convert/issues/new/choose) or [discussion](https://github.com/orgs/pyinat/discussions). Also, **PRs are welcome!**\n\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Data conversion tools for iNaturalist observations and taxonomy",
    "version": "0.6.5",
    "project_urls": {
        "Documentation": "https://pyinaturalist-convert.readthedocs.io",
        "Homepage": "https://github.com/pyinat/pyinaturalist-convert",
        "Repository": "https://github.com/pyinat/pyinaturalist-convert"
    },
    "split_keywords": [
        "inaturalist",
        " biodiversity",
        " export",
        " convert",
        " csv",
        " darwin-core",
        " dataframe",
        " gpx"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "292579f749afb6851c00ba7f90d188bb1ccbee8ebf46f84d404fcc4229e3de45",
                "md5": "57fb059741952076ee1bd985a37ac438",
                "sha256": "c31ae757c4ebae3efa8559bf1bbf7abd557fa41e9d6c6eb4037c61608aefb216"
            },
            "downloads": -1,
            "filename": "pyinaturalist_convert-0.6.5-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "57fb059741952076ee1bd985a37ac438",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": "<4.0,>=3.8",
            "size": 47534,
            "upload_time": "2024-07-22T18:54:51",
            "upload_time_iso_8601": "2024-07-22T18:54:51.848406Z",
            "url": "https://files.pythonhosted.org/packages/29/25/79f749afb6851c00ba7f90d188bb1ccbee8ebf46f84d404fcc4229e3de45/pyinaturalist_convert-0.6.5-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "4fff3cdab0c0628f0e1a953dbcce90bc71dd5cbf8b1434fbf16dc1185090a850",
                "md5": "63bd6af698c0fa7038a0a631a40d8f73",
                "sha256": "a7b20b58f9ebf74a5093effb3510cb43e953484a32ddf3e499a0a22bc2a3a1a5"
            },
            "downloads": -1,
            "filename": "pyinaturalist_convert-0.6.5.tar.gz",
            "has_sig": false,
            "md5_digest": "63bd6af698c0fa7038a0a631a40d8f73",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": "<4.0,>=3.8",
            "size": 1639306,
            "upload_time": "2024-07-22T18:54:53",
            "upload_time_iso_8601": "2024-07-22T18:54:53.388646Z",
            "url": "https://files.pythonhosted.org/packages/4f/ff/3cdab0c0628f0e1a953dbcce90bc71dd5cbf8b1434fbf16dc1185090a850/pyinaturalist_convert-0.6.5.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-07-22 18:54:53",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "pyinat",
    "github_project": "pyinaturalist-convert",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "pyinaturalist-convert"
}
Jordan Cook
Elapsed time: 1.92606s