**LAST RELEASE 2.0**: update to 2.0 version is highly recommended, since it
supports JSON-stat 2.0 and brings other improvements. Also, Version 2.X starts
to **support Pandas 1.X, and won't have backwards compatibility**.
**WARNING**: support for Python 2.7 has been removed in pyjstat 2.0.
=======
pyjstat
=======
.. image:: https://travis-ci.org/predicador37/pyjstat.svg?branch=master
:target: https://travis-ci.org/predicador37/pyjstat
**pyjstat** is a python library for **JSON-stat** formatted data manipulation
which allows reading and writing JSON-stat [1]_ format with python,using the
DataFrame structures provided by the widely accepted pandas library [2]_.
The JSON-stat format is a simple lightweight JSON format for data
dissemination, currently in its 2.0 version.
Pyjstat is inspired in rjstat [3]_, a library to read and write
JSON-stat with R, by ajschumacher. Note that, like in the rjstat project,
not all features are supported (i.e. not all metadata are converted).
**pyjstat** is provided under the Apache License 2.0.
.. [1] http://json-stat.org/ for JSON-stat information
.. [2] http://pandas.pydata.org for Python Data Analysis Library information
.. [3] https://github.com/ajschumacher/rjstat for rjstat library information
This library was first developed to work with Python 2.7. With some fixes
(thanks to @andrekittredge), now it works with Python 3.4 too.
Support for JSON-stat 1.3 and 2.0 is provided. JSON-stat 1.3 methods are
deprecated now and shouldn't be used in the future, but backwards compatibility
has been preserved.
Pyjstat 1.0 is aimed for simplicity. JSON-stat classes have been replicated
(Dataset, Collection and Dimension) and provided with simple read() and write()
methods. Funcionality covers common use cases as having a URL or dataframe
as data sources.
Methods for retrieving the value of a particular cube cell are taken from the
JSON-stat Javascript sample code. Thanks to @badosa for this.
Also, version 1.0 makes use of the requests package internally, which should
make downloading of datasets easier.
Test coverage is 88% and Travis CI is used.
Finally, note that the new classes and methods are inspired by JSON-stat 2.0,
and hence, won't work with previous versions of JSON-stat. However, older
methods are still available incorporating bug fixes and performance
improvements.
Installation
============
pyjstat requires pandas package. For installation::
pip install pyjstat
Usage of version 1.0 and newer (with JSON-stat 2.0 support)
===========================================================
Dataset operations: read and write
----------------------------------
Typical usage often looks like this::
from pyjstat import pyjstat
EXAMPLE_URL = 'http://json-stat.org/samples/galicia.json'
# read from json-stat
dataset = pyjstat.Dataset.read(EXAMPLE_URL)
# write to dataframe
df = dataset.write('dataframe')
print(df)
# read from dataframe
dataset_from_df = pyjstat.Dataset.read(df)
# write to json-stat
print(dataset_from_df.write())
Dataset operation: get_value
----------------------------------
This operation mimics the Javascript example in the JSON-stat web page::
from pyjstat import pyjstat
EXAMPLE_URL = 'http://json-stat.org/samples/oecd.json'
query = [{'concept': 'UNR'}, {'area': 'US'}, {'year': '2010'}]
dataset = pyjstat.Dataset.read(EXAMPLE_URL)
print(dataset.get_value(query))
Collection operations: read and write
-------------------------------------
A collection can be parsed into a list of dataframes::
from pyjstat import pyjstat
EXAMPLE_URL = 'http://json-stat.org/samples/collection.json'
collection = pyjstat.Collection.read(EXAMPLE_URL)
df_list = collection.write('dataframe_list')
print(df_list)
Example with UK ONS API
-----------------------
In the following example, apikey parameter must be replaced by a real api key
from ONS. This dataset corresponds to residence type by sex by age in London::
EXAMPLE_URL = 'http://web.ons.gov.uk/ons/api/data/dataset/DC1104EW.json?'\
'context=Census&jsontype=json-stat&apikey=yourapikey&'\
'geog=2011HTWARDH&diff=&totals=false&'\
'dm/2011HTWARDH=E12000007'
dataset = pyjstat.Dataset.read(EXAMPLE_URL)
df = dataset.write('dataframe')
print(df)
More examples
-------------
More examples can be found in the examples directory, both for versions 1.3
and 2.0.
Usage of version 0.3.5 and older (with support for JSON-stat 1.3)
=================================================================
This syntax is deprecated and therefore not recommended anymore.
From JSON-stat to pandas DataFrame
-----------------------------------
Typical usage often looks like this::
from pyjstat import pyjstat
import requests
from collections import OrderedDict
EXAMPLE_URL = 'http://json-stat.org/samples/us-labor.json'
data = requests.get(EXAMPLE_URL)
results = pyjstat.from_json_stat(data.json(object_pairs_hook=OrderedDict))
print (results)
From pandas DataFrame to JSON-stat
----------------------------------
The same data can be converted into JSON-stat, with some unavoidable metadata
loss::
from pyjstat import pyjstat
import requests
from collections import OrderedDict
import json
EXAMPLE_URL = 'http://json-stat.org/samples/us-labor.json'
data = requests.get(EXAMPLE_URL)
results = pyjstat.from_json_stat(data.json(object_pairs_hook=OrderedDict))
print (results)
print (json.dumps(json.loads(pyjstat.to_json_stat(results))))
Changes
-------
For a changes, fixes, improvements and new features reference, see CHANGES.txt.
Raw data
{
"_id": null,
"home_page": "https://github.com/predicador37/pyjstat",
"name": "pyjstat",
"maintainer": "",
"docs_url": "https://pythonhosted.org/pyjstat/",
"requires_python": "",
"maintainer_email": "",
"keywords": "json-stat,json,statistics,dataframe,converter",
"author": "Miguel Exp\u00f3sito Mart\u00edn",
"author_email": "miguel.exposito@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/62/25/a78cb7492a5482f0aa627189d2a58aa030ef419c36568cd8eb8581ab3451/pyjstat-2.4.0.tar.gz",
"platform": null,
"description": "**LAST RELEASE 2.0**: update to 2.0 version is highly recommended, since it \nsupports JSON-stat 2.0 and brings other improvements. Also, Version 2.X starts \nto **support Pandas 1.X, and won't have backwards compatibility**.\n**WARNING**: support for Python 2.7 has been removed in pyjstat 2.0.\n\n=======\npyjstat\n=======\n\n.. image:: https://travis-ci.org/predicador37/pyjstat.svg?branch=master\n :target: https://travis-ci.org/predicador37/pyjstat\n\n**pyjstat** is a python library for **JSON-stat** formatted data manipulation\nwhich allows reading and writing JSON-stat [1]_ format with python,using the\nDataFrame structures provided by the widely accepted pandas library [2]_.\nThe JSON-stat format is a simple lightweight JSON format for data\ndissemination, currently in its 2.0 version.\nPyjstat is inspired in rjstat [3]_, a library to read and write\nJSON-stat with R, by ajschumacher. Note that, like in the rjstat project,\nnot all features are supported (i.e. not all metadata are converted).\n**pyjstat** is provided under the Apache License 2.0.\n\n.. [1] http://json-stat.org/ for JSON-stat information\n.. [2] http://pandas.pydata.org for Python Data Analysis Library information\n.. [3] https://github.com/ajschumacher/rjstat for rjstat library information\n\nThis library was first developed to work with Python 2.7. With some fixes\n(thanks to @andrekittredge), now it works with Python 3.4 too.\n\nSupport for JSON-stat 1.3 and 2.0 is provided. JSON-stat 1.3 methods are\ndeprecated now and shouldn't be used in the future, but backwards compatibility\nhas been preserved.\n\nPyjstat 1.0 is aimed for simplicity. JSON-stat classes have been replicated\n(Dataset, Collection and Dimension) and provided with simple read() and write()\nmethods. Funcionality covers common use cases as having a URL or dataframe\nas data sources.\n\nMethods for retrieving the value of a particular cube cell are taken from the\nJSON-stat Javascript sample code. Thanks to @badosa for this.\n\nAlso, version 1.0 makes use of the requests package internally, which should\nmake downloading of datasets easier.\n\nTest coverage is 88% and Travis CI is used.\n\nFinally, note that the new classes and methods are inspired by JSON-stat 2.0,\nand hence, won't work with previous versions of JSON-stat. However, older\nmethods are still available incorporating bug fixes and performance\nimprovements.\n\nInstallation\n============\n\npyjstat requires pandas package. For installation::\n\n pip install pyjstat\n\nUsage of version 1.0 and newer (with JSON-stat 2.0 support)\n===========================================================\n\nDataset operations: read and write\n----------------------------------\n\nTypical usage often looks like this::\n\n from pyjstat import pyjstat\n\n EXAMPLE_URL = 'http://json-stat.org/samples/galicia.json'\n\n # read from json-stat\n dataset = pyjstat.Dataset.read(EXAMPLE_URL)\n\n # write to dataframe\n df = dataset.write('dataframe')\n print(df)\n\n # read from dataframe\n dataset_from_df = pyjstat.Dataset.read(df)\n\n # write to json-stat\n print(dataset_from_df.write())\n\nDataset operation: get_value\n----------------------------------\n\nThis operation mimics the Javascript example in the JSON-stat web page::\n\n from pyjstat import pyjstat\n\n EXAMPLE_URL = 'http://json-stat.org/samples/oecd.json'\n query = [{'concept': 'UNR'}, {'area': 'US'}, {'year': '2010'}]\n\n dataset = pyjstat.Dataset.read(EXAMPLE_URL)\n print(dataset.get_value(query))\n\nCollection operations: read and write\n-------------------------------------\n\nA collection can be parsed into a list of dataframes::\n\n from pyjstat import pyjstat\n\n EXAMPLE_URL = 'http://json-stat.org/samples/collection.json'\n\n collection = pyjstat.Collection.read(EXAMPLE_URL)\n df_list = collection.write('dataframe_list')\n print(df_list)\n\nExample with UK ONS API\n-----------------------\n\nIn the following example, apikey parameter must be replaced by a real api key\nfrom ONS. This dataset corresponds to residence type by sex by age in London::\n\n EXAMPLE_URL = 'http://web.ons.gov.uk/ons/api/data/dataset/DC1104EW.json?'\\\n 'context=Census&jsontype=json-stat&apikey=yourapikey&'\\\n 'geog=2011HTWARDH&diff=&totals=false&'\\\n 'dm/2011HTWARDH=E12000007'\n dataset = pyjstat.Dataset.read(EXAMPLE_URL)\n df = dataset.write('dataframe')\n print(df)\n\nMore examples\n-------------\n\nMore examples can be found in the examples directory, both for versions 1.3\nand 2.0.\n\n\nUsage of version 0.3.5 and older (with support for JSON-stat 1.3)\n=================================================================\n\nThis syntax is deprecated and therefore not recommended anymore.\n\nFrom JSON-stat to pandas DataFrame\n-----------------------------------\n\nTypical usage often looks like this::\n\n from pyjstat import pyjstat\n import requests\n from collections import OrderedDict\n\n EXAMPLE_URL = 'http://json-stat.org/samples/us-labor.json'\n\n data = requests.get(EXAMPLE_URL)\n results = pyjstat.from_json_stat(data.json(object_pairs_hook=OrderedDict))\n print (results)\n\nFrom pandas DataFrame to JSON-stat\n----------------------------------\n\nThe same data can be converted into JSON-stat, with some unavoidable metadata\nloss::\n\n from pyjstat import pyjstat\n import requests\n from collections import OrderedDict\n import json\n\n EXAMPLE_URL = 'http://json-stat.org/samples/us-labor.json'\n\n data = requests.get(EXAMPLE_URL)\n results = pyjstat.from_json_stat(data.json(object_pairs_hook=OrderedDict))\n print (results)\n print (json.dumps(json.loads(pyjstat.to_json_stat(results))))\n\nChanges\n-------\n\nFor a changes, fixes, improvements and new features reference, see CHANGES.txt.\n",
"bugtrack_url": null,
"license": "Apache License 2.0",
"summary": "Library to handle JSON-stat data in python using pandas DataFrames.",
"version": "2.4.0",
"split_keywords": [
"json-stat",
"json",
"statistics",
"dataframe",
"converter"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6225a78cb7492a5482f0aa627189d2a58aa030ef419c36568cd8eb8581ab3451",
"md5": "eb799e2a8da8616045f1d89a21590b58",
"sha256": "dd7fc7b4ed0892fb949ff87eeea3e2c838754eef43922b40ba3c38fadfc30795"
},
"downloads": -1,
"filename": "pyjstat-2.4.0.tar.gz",
"has_sig": false,
"md5_digest": "eb799e2a8da8616045f1d89a21590b58",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 798030,
"upload_time": "2023-03-31T12:29:47",
"upload_time_iso_8601": "2023-03-31T12:29:47.997131Z",
"url": "https://files.pythonhosted.org/packages/62/25/a78cb7492a5482f0aa627189d2a58aa030ef419c36568cd8eb8581ab3451/pyjstat-2.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-03-31 12:29:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "predicador37",
"github_project": "pyjstat",
"travis_ci": true,
"coveralls": true,
"github_actions": false,
"requirements": [],
"lcname": "pyjstat"
}
JSON
