### Install jsonstat.py

Source: https://github.com/26fe/jsonstat.py/blob/master/README.rst

Install the jsonstat.py library using pip. This command will also install any necessary dependencies.

```bash
pip install jsonstat.py
```

--------------------------------

### Basic Python Doctest Example

Source: https://github.com/26fe/jsonstat.py/blob/master/docs/tutorial.rst

A simple doctest example in Python demonstrating basic arithmetic operations. This is a standard way to test Python code snippets directly within documentation.

```python
>>> 2 + 2
4
```

--------------------------------

### Python jsonstat Module Test Output Example

Source: https://github.com/26fe/jsonstat.py/blob/master/docs/tutorial.rst

This example demonstrates how to use the jsonstat.py module by printing a JSON string and performing a simple arithmetic operation. It shows a basic test case for the module.

```python
json_string = '''
{
    "label" : "concepts",
    "category" : {
        "index" : {
            "POP" : 0,
            "PERCENT" : 1
        },
        "label" : {
            "POP" : "population",
            "PERCENT" : "weight of age group in the population"
        },
        "unit" : {
            "POP" : {
                "label": "thousands of persons",
                "decimals": 1,
                "type" : "count",
                "base" : "people",
                "multiplier" : 3
            },
            "PERCENT" : {
                "label" : "%",
                "decimals": 1,
                "type" : "ratio",
                "base" : "per cent",
                "multiplier" : 0
            }
        }
    }
}
'''
print(2 + 2)
```

--------------------------------

### Command-line: Parse JSON-stat Dataset

Source: https://github.com/26fe/jsonstat.py/blob/master/README.rst

Example of using the jsonstat.py command-line interface to parse a specific JSON-stat dataset from a URL, showing its metadata and dimensions.

```bash
# parsing dataset
$ jsonstat info --cache_dir /tmp  "http://ec.europa.eu/eurostat/wdds/rest/data/v2.1/json/en/tesem120?sex=T&precision=1&age=TOTAL&s_adj=NSA"
downloaded file(s) are stored into '/tmp'
download 'http://ec.europa.eu/eurostat/wdds/rest/data/v2.1/json/en/tesem120?sex=T&precision=1&age=TOTAL&s_adj=NSA'
name:   'Unemployment rate'
label:  'Unemployment rate'
size: 467
+-----+-------+-------+------+------+
| pos | id    | label | size | role |
+-----+-------+-------+------+------+
| 0   | s_adj | s_adj | 1    |      |
| 1   | age   | age   | 1    |      |
| 2   | sex   | sex   | 1    |      |
| 3   | geo   | geo   | 39   |      |
| 4   | time  | time  | 12   |      |
+-----+-------+-------+------+------+
```

--------------------------------

### Command-line: Parse JSON-stat Collection

Source: https://github.com/26fe/jsonstat.py/blob/master/README.rst

Example of using the jsonstat.py command-line interface to parse a JSON-stat collection from a URL and store downloaded files in a specified cache directory.

```bash
# parsing collection
$ jsonstat info --cache_dir /tmp http://json-stat.org/samples/oecd-canada.json
downloaded file(s) are stored into '/tmp'
download 'http://json-stat.org/samples/oecd-canada.json'
JsonstatCollection contains the following JsonStatDataSet:
+-----+----------+
| pos | dataset  |
+-----+----------+
| 0   | 'oecd'   |
| 1   | 'canada' |
+-----+----------+
```

--------------------------------

### Explore CSO.ie Datasets with jsonstat.py (Python)

Source: https://github.com/26fe/jsonstat.py/blob/master/examples-notebooks/cso_ie.ipynb

This snippet demonstrates how to use the jsonstat.py library in Python to fetch and explore data from the CSO.ie data provider. It requires the jsonstat.py library to be installed. The output will be a JSONStat object representing the dataset, which can then be further analyzed.

```python
from jsonstat import JsonStat

# Example: Fetching a dataset from cso.ie
# Replace with an actual dataset URL if available
dataset_url = "http://www.cso.ie/StatbankServices/StatbankWriter/GetJSONStat.ashx?dataarea=SS01&HDMX=true"
data = JsonStat(dataset_url)

# Explore the dataset (e.g., print dimensions)
print(data.dimensions)

# Access specific parts of the data (example)
# print(data.value(region='Dublin', year=2022))

```

--------------------------------

### Explore OECD Canada Data with jsonstat.py

Source: https://github.com/26fe/jsonstat.py/blob/master/examples-notebooks/oecd-canada-jsonstat_v1.ipynb

This snippet demonstrates how to use the jsonstat.py library to load and explore a sample JSON-stat dataset (oecd-canada.json). It requires the jsonstat.py library to be installed. The output will be the dataset object, allowing for further programmatic access to its contents.

```python
from jsonstat import JsonStat

# Load the dataset from a URL
data = JsonStat('http://json-stat.org/samples/oecd-canada.json')

# Print the dataset object to explore its structure
print(data)
```

--------------------------------

### Retrieve Data Value by Criteria in Python

Source: https://github.com/26fe/jsonstat.py/blob/master/examples-notebooks/cso_ie.ipynb

This example demonstrates how to retrieve a specific data value from a JSON-stat dataset based on multiple criteria such as 'Sector', 'Quarter', and 'Statistic'. It utilizes the 'data' method of the dataset object.

```python
dataset.data(Sector='03', Quarter='1997Q4', Statistic='NQQ25S1')
```

--------------------------------

### Access Dataset from JsonstatCollection

Source: https://github.com/26fe/jsonstat.py/blob/master/examples-notebooks/cso_ie.ipynb

This example demonstrates how to access a specific dataset within a JsonstatCollection. It retrieves the dataset at index 0 and assigns it to the 'dataset' variable. This allows further exploration and manipulation of the dataset's contents and structure.

```python
dataset = collection_1.dataset(0)
dataset
```

--------------------------------

### Load JSON-STAT Data with jsonstat.py

Source: https://github.com/26fe/jsonstat.py/blob/master/examples-notebooks/oecd-canada-jsonstat_v2.ipynb

This snippet demonstrates how to load and parse a JSON-STAT formatted data file using the jsonstat.py Python library. It assumes the 'jsonstat' library is installed and a valid JSON-STAT file path is provided. The output is a JSONStat object representing the dataset.

```python
from jsonstat import JSONStat

# Load data from a JSON-STAT compliant file
data = JSONStat('oecd-canada-col.json')

# You can now access and manipulate the data using the JSONStat object
print(data.to_dict())
```

--------------------------------

### Retrieving Specific Values from Eurostat Data

Source: https://github.com/26fe/jsonstat.py/blob/master/docs/notebooks/eurostat.rst

This Python snippet demonstrates how to retrieve a specific data value from the 'nama_gdp_c' Eurostat dataset based on 'time' and 'geo' dimensions. It shows how to get the GDP per inhabitant for Italy in 2012 and for France in 2012. This is fundamental for targeted data extraction.

```python
nama_gdp_c_2.value(time='2012',geo='IT')
```

```python
nama_gdp_c_2.value(time='2012',geo='FR')
```

--------------------------------

### Transforming jsonstat Dataset to Pandas DataFrame

Source: https://github.com/26fe/jsonstat.py/blob/master/examples-notebooks/oecd-canada-jsonstat_v1.ipynb

Shows how to convert a jsonstat dataset into a pandas DataFrame for further analysis. It includes examples of converting the entire dataset and creating a subset by freezing specific dimensions like 'area' to a particular country.

```python
df_oecd = oecd.to_data_frame('year', content='id')
df_oecd.head()
```

```python
df_oecd['area'].describe()
```

```python
df_oecd_ca = oecd.to_data_frame('year', content='id', blocked_dims={'area':'CA'})
df_oecd_ca.tail()
```

```python
df_oecd_ca['area'].describe()
```

```python
df_oecd_ca.plot(grid=True)
```

--------------------------------

### Describe Pandas DataFrame Column (Python)

Source: https://github.com/26fe/jsonstat.py/blob/master/docs/notebooks/oecd-canada-jsonstat_v1.rst

This snippet shows how to use the .describe() method on a pandas DataFrame column to get summary statistics. It's useful for understanding the distribution of data within a column.

```python
df_oecd['area'].describe() # area contains 36 values
```

```python
df_oecd_ca['area'].describe()  # area contains only one value (CA)
```

--------------------------------

### Retrieve Specific Data Value in Python

Source: https://github.com/26fe/jsonstat.py/blob/master/examples-notebooks/eurostat.ipynb

Fetches a specific data value from a JsonStatDataSet based on dimension criteria. In this example, it retrieves the GDP value for the year '2012'.

```python
# Assuming nama_gdp_c_1 is already defined from the previous step

value_2012 = nama_gdp_c_1.value(time='2012')
print(value_2012)
```

--------------------------------

### Describe DataFrame Column (Python)

Source: https://github.com/26fe/jsonstat.py/blob/master/docs/notebooks/oecd-canada-jsonstat_v2.rst

This snippet shows how to use the `.describe()` method on a pandas DataFrame column to get summary statistics. It's useful for understanding the distribution of values within a specific column, such as the 'area' column in the 'df_oecd' DataFrame.

```python
df_oecd['area'].describe() # area contains 36 values
```

--------------------------------

### Convert JSONStat to Table with Custom Order (Python)

Source: https://github.com/26fe/jsonstat.py/blob/master/docs/notebooks/oecd-canada-jsonstat_v2.rst

This example demonstrates how to convert a JSONStat dataset to a table with a custom column order. The `order` variable is generated by reversing the list of dimension identifiers obtained from `oecd.dimensions()`. This allows for flexible arrangement of data columns in the output table. The first five rows of the reordered table are then displayed.

```python
order = [i.did() for i in oecd.dimensions()]
order = order[::-1]  # reverse list
table = oecd.to_table(order=order)
table[:5]
```

--------------------------------

### Plot DataFrame (Python)

Source: https://github.com/26fe/jsonstat.py/blob/master/docs/notebooks/oecd-canada-jsonstat_v2.rst

This snippet shows how to generate a plot from a pandas DataFrame. The `.plot(grid=True)` method creates a line plot with a grid, which is useful for visualizing trends in the data. This requires matplotlib to be installed.

```python
df_oecd_ca.plot(grid=True)
```

--------------------------------

### Retrieve Specific Data Value

Source: https://github.com/26fe/jsonstat.py/blob/master/docs/notebooks/oecd-canada-jsonstat_v1.rst

Retrieves the specific numerical value from the 'oecd' dataset for a given 'area' and 'year'. This method provides a direct way to get the data point.

```python
oecd.value(area='IT', year='2012')
```

--------------------------------

### Accessing Specific Data Values in jsonstat Python

Source: https://github.com/26fe/jsonstat.py/blob/master/examples-notebooks/oecd-canada-jsonstat_v1.ipynb

Demonstrates how to retrieve individual data points from a jsonstat dataset using various access methods like 'data()' and 'value()'. It shows how to filter by concepts, areas, and years. The 'value()' method is a direct way to get a numerical result.

```python
oecd.data(area='IT', year='2012')
```

```python
oecd.value(area='IT', year='2012')
```

```python
oecd.value(concept='unemployment rate',area='Australia',year='2004')
```

```python
oecd.value(concept='UNR',area='AU',year='2004')
```

--------------------------------

### Describe Subset DataFrame Column (Python)

Source: https://github.com/26fe/jsonstat.py/blob/master/docs/notebooks/oecd-canada-jsonstat_v2.rst

This example illustrates how to use the `.describe()` method on a column of a subsetted pandas DataFrame. Since the subset was created by filtering the 'area' dimension to 'CA', this description will show that the 'area' column contains only one unique value ('CA').

```python
df_oecd_ca['area'].describe()  # area contains only one value (CA)
```

--------------------------------

### Git Branching and Committing in jsonstat.py

Source: https://github.com/26fe/jsonstat.py/blob/master/README.rst

Demonstrates standard Git commands for creating a feature branch, writing code with tests, committing changes, and pushing to a remote repository within the jsonstat.py project workflow. Assumes a basic understanding of Git.

```shell
git checkout -b my-new-feature
# Write your code and add unit tests
git commit -am "Added some feature"
git push origin my-new-feature
```

--------------------------------

### Load and Inspect Eurostat Dataset with jsonstat.py

Source: https://github.com/26fe/jsonstat.py/blob/master/examples-notebooks/eurostat.ipynb

This code snippet demonstrates loading a JSON Stat dataset from a local file using `jsonstat.from_file()`. It then accesses a specific dataset ('nama_gdp_c') and displays its basic information, including dimensions, size, and roles. This is useful for understanding the structure of the data before further analysis.

```python
import jsonstat
import pandas as pd

# Assuming file_path_2 is defined from the previous snippet
collection_2 = jsonstat.from_file(file_path_2)
nama_gdp_c_2 = collection_2.dataset('nama_gdp_c')
print(nama_gdp_c_2)
```

--------------------------------

### Initialize JsonStatCollection from File

Source: https://github.com/26fe/jsonstat.py/blob/master/docs/notebooks/eurostat.rst

Initializes a `JsonStatCollection` object from a downloaded JSON file using `jsonstat.from_file`. This object represents the entire dataset structure. The function takes the file path as input and returns a `JsonStatCollection` instance, which can then be used to access individual datasets.

```python
collection_1 = jsonstat.from_file(file_path_1)
collection_1
```

--------------------------------

### Initialize JsonStatDimension

Source: https://github.com/26fe/jsonstat.py/blob/master/docs/api_jsonstat_dimension.rst

The `__init__` method is the constructor for the JsonStatDimension class. It likely initializes the dimension object with its associated data and metadata. Specific parameters and return types are not detailed here but would typically involve data structures representing the dimension's attributes.

```python
def __init__(self, ...):
    """Constructor for JsonStatDimension."""
    pass
```

--------------------------------

### Initialize JsonStatCollection and Explore Dataset in Python

Source: https://github.com/26fe/jsonstat.py/blob/master/examples-notebooks/eurostat.ipynb

Initializes a JsonStatCollection object from a local file and then accesses a specific dataset within the collection. It prints information about the collection and the selected dataset, including its dimensions and size.

```python
import jsonstat

# Assuming file_path_1 is already defined from the previous step
# file_path_1 = "path/to/your/eurostat-name_gpd_c-geo_IT.json"

collection_1 = jsonstat.from_file(file_path_1)
print("JsonstatCollection contains the following JsonStatDataSet:")
print(collection_1)

nama_gdp_c_1 = collection_1.dataset('nama_gdp_c')
print(nama_gdp_c_1)
```

--------------------------------

### Initialize JsonStatCollection from File

Source: https://github.com/26fe/jsonstat.py/blob/master/examples-notebooks/oecd-canada-jsonstat_v2.ipynb

This code initializes a JsonStatCollection object from a local file path. The collection then holds multiple JsonStatDataSet objects, which can be iterated through or accessed by index. The output displays a summary of the datasets contained within the collection.

```python
import jsonstat

# Assuming file_path is already defined from the previous snippet
collection = jsonstat.from_file(file_path)
collection
```

--------------------------------

### Download Eurostat Dataset with jsonstat.py

Source: https://github.com/26fe/jsonstat.py/blob/master/docs/notebooks/eurostat.rst

Downloads a Eurostat dataset using the `jsonstat.download` function. It checks if the file already exists locally to leverage caching, which speeds up development and ensures consistent results. The function requires a URL and a filename for saving the dataset.

```python
url_1 = 'http://ec.europa.eu/eurostat/wdds/rest/data/v1.1/json/en/nama_gdp_c?precision=1&geo=IT&unit=EUR_HAB&indic_na=B1GM'
file_name_1 = "eurostat-name_gpd_c-geo_IT.json"

file_path_1 = os.path.abspath(os.path.join("..", "tests", "fixtures", "www.ec.europa.eu_eurostat", file_name_1))
if os.path.exists(file_path_1):
    print("using already donwloaded file {}".format(file_path_1))
else:
    print("download file")
    jsonstat.download(url_1, file_name_1)
    file_path_1 = file_name_1
```

--------------------------------

### Download and Cache Eurostat Data with jsonstat.py

Source: https://github.com/26fe/jsonstat.py/blob/master/examples-notebooks/eurostat.ipynb

This snippet shows how to download a JSON Stat dataset from a given URL and cache it locally. It checks if the file already exists to avoid redundant downloads, improving development speed. It requires the 'os' and 'jsonstat' libraries.

```python
import os
import jsonstat

url_2 = 'http://ec.europa.eu/eurostat/wdds/rest/data/v1.1/json/en/nama_gdp_c?precision=1&geo=IT&geo=FR&unit=EUR_HAB&indic_na=B1GM'
file_name_2 = "eurostat-name_gpd_c-geo_IT_FR.json"

file_path_2 = os.path.abspath(os.path.join("..", "tests", "fixtures", "www.ec.europa.eu_eurostat", file_name_2))
if os.path.exists(file_path_2):
    print("using alredy donwloaded file {}".format(file_path_2))
else:
    print("download file and storing on disk")
    jsonstat.download(url_2, file_name_2)
    file_path_2 = file_name_2
```

--------------------------------

### Transforming jsonstat Dataset to Python List

Source: https://github.com/26fe/jsonstat.py/blob/master/examples-notebooks/oecd-canada-jsonstat_v1.ipynb

Illustrates how to transform a jsonstat dataset into a Python list. It demonstrates a basic conversion and how to customize the order of columns in the resulting table by manipulating the dimension order.

```python
oecd.to_table()[:5]
```

```python
order = [i.did for i in oecd.dimensions()]
order = order[::-1]  # reverse list
table = oecd.to_table(order=order)
table[:5]
```

--------------------------------

### Download Eurostat Data with Caching in Python

Source: https://github.com/26fe/jsonstat.py/blob/master/examples-notebooks/eurostat.ipynb

Downloads a Eurostat dataset to a local file, utilizing caching to avoid repeated downloads. It checks for an existing file before initiating the download, ensuring efficient development and consistent results.

```python
import os
import jsonstat

url_1 = 'http://ec.europa.eu/eurostat/wdds/rest/data/v1.1/json/en/nama_gdp_c?precision=1&geo=IT&unit=EUR_HAB&indic_na=B1GM'
file_name_1 = "eurostat-name_gpd_c-geo_IT.json"

file_path_1 = os.path.abspath(os.path.join("..", "tests", "fixtures", "www.ec.europa.eu_eurostat", file_name_1))
if os.path.exists(file_path_1):
    print("using already donwloaded file {}".format(file_path_1))
else:
    print("download file")
    jsonstat.download(url_1, file_name_1)
    file_path_1 = file_name_1
```

--------------------------------

### Set Cache Directory for jsonstat

Source: https://github.com/26fe/jsonstat.py/blob/master/examples-notebooks/cso_ie.ipynb

This code snippet demonstrates how to set a cache directory for the jsonstat library. This allows for faster data retrieval and consistent results during development by storing retrieved datasets locally. It uses the os module to create an absolute path to the cache directory.

```python
cache_dir = os.path.abspath(os.path.join("..", "tests", "fixtures", "www.cso.ie"))
jsonstat.cache_dir(cache_dir)
```

--------------------------------

### Load JSON-Stat Collection from File

Source: https://github.com/26fe/jsonstat.py/blob/master/examples-notebooks/oecd-canada-jsonstat_v1.ipynb

Initializes a JsonStatCollection object from a local JSON-Stat file. This allows for easy access to multiple datasets within the file. Dependencies: jsonstat.

```python
import jsonstat

# Assuming file_path is already defined from the download step
# file_path = "oecd-canada.json"
collection = jsonstat.from_file(file_path)
collection
```

--------------------------------

### Initialize JsonStatCollection from a File in Python

Source: https://github.com/26fe/jsonstat.py/blob/master/docs/notebooks/oecd-canada-jsonstat_v2.rst

Initializes a `JsonStatCollection` object from a local JSON-stat data file using the `jsonstat.from_file` method. It then prints the list of datasets contained within the collection. This step is crucial for accessing and processing the data.

```python
collection = jsonstat.from_file(file_path)
collection
```

--------------------------------

### Downloading and Caching Eurostat JSON Data

Source: https://github.com/26fe/jsonstat.py/blob/master/docs/notebooks/eurostat.rst

This Python code demonstrates how to download a JSONstat file from a given URL and cache it locally. It checks if the file already exists and uses it if available, otherwise, it downloads and saves the file. This approach speeds up development by avoiding repeated internet requests.

```python
url_2 = 'http://ec.europa.eu/eurostat/wdds/rest/data/v1.1/json/en/nama_gdp_c?precision=1&geo=IT&geo=FR&unit=EUR_HAB&indic_na=B1GM'
file_name_2 = "eurostat-name_gpd_c-geo_IT_FR.json"

file_path_2 = os.path.abspath(os.path.join("..", "tests", "fixtures", "www.ec.europa.eu_eurostat", file_name_2))
if os.path.exists(file_path_2):
    print("using alredy donwloaded file {}".format(file_path_2))
else:
    print("download file and storing on disk")
    jsonstat.download(url, file_name_2)
    file_path_2 = file_name_2
```

--------------------------------

### Loading Eurostat Data from a Cached File

Source: https://github.com/26fe/jsonstat.py/blob/master/docs/notebooks/eurostat.rst

This Python snippet shows how to load Eurostat data from a locally cached JSONstat file using the jsonstat.from_file() function. It then accesses a specific dataset ('nama_gdp_c') from the collection. This is a common step after downloading and caching data for further analysis.

```python
collection_2 = jsonstat.from_file(file_path_2)
nama_gdp_c_2 = collection_2.dataset('nama_gdp_c')
```

--------------------------------

### Parse JSON-stat collection from URL

Source: https://github.com/26fe/jsonstat.py/blob/master/README.rst

Demonstrates how to fetch and parse a JSON-stat collection from a given URL using the jsonstat.from_url() function. It also shows how to print the collection and access individual datasets within it.

```python
import jsonstat

url = 'http://json-stat.org/samples/oecd-canada.json'
collection = jsonstat.from_url(url)

# print list of dataset contained into the collection
print(collection)

# select the first dataset of the collection and print a short description
oecd = collection.dataset(0)
print(oecd)
```

--------------------------------

### Download JSON-Stat Data

Source: https://github.com/26fe/jsonstat.py/blob/master/examples-notebooks/oecd-canada-jsonstat_v1.ipynb

Downloads a JSON-Stat dataset from a given URL and saves it to a local file. It checks for an existing file to avoid re-downloading. Dependencies: os, jsonstat.

```python
import os
import jsonstat

url = 'http://json-stat.org/samples/oecd-canada.json'
file_name = "oecd-canada.json"

file_path = os.path.abspath(os.path.join("..", "tests", "fixtures", "www.json-stat.org", file_name))
if os.path.exists(file_path):
    print("using already downloaded file {}".format(file_path))
else:
    print("download file and storing on disk")
    jsonstat.download(url, file_name)
    file_path = file_name
```

--------------------------------

### Retrieve JsonstatCollection from URL

Source: https://github.com/26fe/jsonstat.py/blob/master/examples-notebooks/cso_ie.ipynb

This snippet shows how to retrieve a JsonstatCollection object from a URL using the jsonstat library. It defines a base URI and a specific endpoint, then uses jsonstat.from_url to fetch the data and store it in a JsonstatCollection object. A filename is also specified for local caching.

```python
base_uri = 'http://www.cso.ie/StatbankServices/StatbankServices.svc/jsonservice/responseinstance/'
uri = base_uri + "NQQ25"
filename = "cso_ie-NQQ25.json"
collection_1 = jsonstat.from_url(uri, filename)
collection_1
```

--------------------------------

### Import Libraries for jsonstat.py

Source: https://github.com/26fe/jsonstat.py/blob/master/docs/notebooks/eurostat.rst

Imports necessary libraries for using the jsonstat.py library, including os for file operations, pandas for data manipulation, and matplotlib for plotting. The `from __future__ import print_function` ensures compatibility with Python 2 and 3.

```python
# all import here
from __future__ import print_function
import os
import pandas as pd
import jsonstat

import matplotlib as plt
%matplotlib inline
```

--------------------------------

### Download and Cache JSON-stat Data File using Python

Source: https://github.com/26fe/jsonstat.py/blob/master/docs/notebooks/oecd-canada-jsonstat_v2.rst

This Python code snippet downloads a JSON-stat data file from a specified URL and saves it locally. It checks if the file already exists in a predefined cache path and uses the cached version if available to speed up subsequent operations and allow offline work. The `jsonstat.download` function handles the download process.

```python
url = 'http://json-stat.org/samples/oecd-canada-col.json'
file_name = "oecd-canada-col.json"

file_path = os.path.abspath(os.path.join("..", "tests", "fixtures", "www.json-stat.org", file_name))
if os.path.exists(file_path):
    print("using already downloaded file {}".format(file_path))
else:
    print("download file and storing on disk")
    jsonstat.download(url, file_name)
    file_path = file_name
```

--------------------------------

### Transforming JsonStat Dataset to Python List/Table

Source: https://github.com/26fe/jsonstat.py/blob/master/examples-notebooks/oecd-canada-jsonstat_v2.ipynb

Shows how to convert a JsonStat dataset into a Python list representation, essentially a table. The `to_table()` method provides this functionality. The order of columns in the resulting table can be customized by providing a specific order list derived from the dataset's dimensions. The output is a list of lists, where each inner list represents a row.

```python
oecd.to_table()[:5]
```

```python
order = [i.did for i in oecd.dimensions()]
order = order[::-1]
table = oecd.to_table(order=order)
table[:5]
```

--------------------------------

### Access and Inspect a JsonStatDataSet

Source: https://github.com/26fe/jsonstat.py/blob/master/examples-notebooks/oecd-canada-jsonstat_v2.ipynb

This snippet demonstrates how to select a specific JsonStatDataSet from a collection using its index. It then prints the metadata of the selected dataset, including its name, label, size, and the dimensions it contains. This is useful for understanding the structure of the data before detailed analysis.

```python
import jsonstat

# Assuming 'collection' is already initialized
oecd = collection.dataset(0)
oecd
```

--------------------------------

### Download or Use Cached JSON-stat Data

Source: https://github.com/26fe/jsonstat.py/blob/master/docs/notebooks/oecd-canada-jsonstat_v1.rst

Handles the downloading of the 'oecd-canada.json' file from a specified URL or uses a locally cached version if available. Caching improves performance and enables offline work.

```python
url = 'http://json-stat.org/samples/oecd-canada.json'
file_name = "oecd-canada.json"

file_path = os.path.abspath(os.path.join("..", "tests", "fixtures", "www.json-stat.org", file_name))
if os.path.exists(file_path):
    print("using already downloaded file {}".format(file_path))
else:
    print("download file and storing on disk")
    jsonstat.download(url, file_name)
    file_path = file_name
```

--------------------------------

### Converting Eurostat Data to a Pandas DataFrame

Source: https://github.com/26fe/jsonstat.py/blob/master/docs/notebooks/eurostat.rst

This Python code converts the 'nama_gdp_c' Eurostat dataset into a pandas DataFrame, specifying the content to be the 'id' and the return type as DataFrame. It then displays the tail of the DataFrame, showing the structure and last few rows of the data, which is useful for inspecting the raw tabular data.

```python
df_2 = nama_gdp_c_2.to_table(content='id',rtype=pd.DataFrame)
df_2.tail()
```

--------------------------------

### Jsonstat Dataset Data Structure

Source: https://github.com/26fe/jsonstat.py/blob/master/docs/api_jsonstat.rst

Outlines the schema for a json-stat dataset, encompassing version, class, href, label, identifier, size, role, value, status, dimensions, and links. This is a core component for representing statistical data.

```json
dataset :=
{
    "version"   :
    <version>
    "class"     :
    "dataset",
    "href"      :
    <url>
    "label"     :
    <string>
    "id"        :
    [ <string>+]           # ex. "id" : ["metric", "time", "geo", "sex"],
    "size"      :
    [ <int>,
<int>,
... ]
    "role"      :
    roles of dimension
    "value"     :
    [<int>,
<int> ]
    "status"    :
    status
    "dimension" :
    { <dimension_id> :
 dimension,
 ...}
    "link"      :
}
```

--------------------------------

### Convert Eurostat Data to Pandas DataFrame with jsonstat.py

Source: https://github.com/26fe/jsonstat.py/blob/master/examples-notebooks/eurostat.ipynb

This snippet illustrates converting a loaded Eurostat dataset into a pandas DataFrame. The `to_table()` method is used with `content='id'` and `rtype=pd.DataFrame`. It then displays the tail of the resulting DataFrame, showing how the data is structured for further manipulation and analysis.

```python
import jsonstat
import pandas as pd

# Assuming nama_gdp_c_2 is loaded from the previous snippet
df_2 = nama_gdp_c_2.to_table(content='id',rtype=pd.DataFrame)
print(df_2.tail())
```

--------------------------------

### Select and Inspect a Specific JsonStatDataSet in Python

Source: https://github.com/26fe/jsonstat.py/blob/master/docs/notebooks/oecd-canada-jsonstat_v2.rst

Selects the first dataset (index 0) from a `JsonStatCollection` object. It then displays detailed information about the selected dataset, including its name, label, size, and the dimensions it contains (concept, area, year) along with their respective sizes and roles. This allows for understanding the structure of the data.

```python
oecd = collection.dataset(0)
oecd
```

--------------------------------

### Download and Cache JSON-Stat Data

Source: https://github.com/26fe/jsonstat.py/blob/master/examples-notebooks/oecd-canada-jsonstat_v2.ipynb

This snippet downloads a JSON-Stat dataset from a given URL and caches it locally. It checks for an existing cached file to avoid redundant downloads, improving efficiency and enabling offline work. The function requires the URL of the data and a local file name.

```python
import os
import jsonstat

url = 'http://json-stat.org/samples/oecd-canada-col.json'
file_name = "oecd-canada-col.json"

file_path = os.path.abspath(os.path.join("..", "tests", "fixtures", "www.json-stat.org", file_name))
if os.path.exists(file_path):
    print("using already downloaded file {}".format(file_path))
else:
    print("download file and storing on disk")
    jsonstat.download(url, file_name)
    file_path = file_name
```

--------------------------------

### Select and Inspect 'oecd' Dataset

Source: https://github.com/26fe/jsonstat.py/blob/master/docs/notebooks/oecd-canada-jsonstat_v1.rst

Selects a specific dataset named 'oecd' from the JsonStatCollection. It then displays summary information about the selected dataset, including its dimensions (concept, area, year) and size.

```python
oecd = collection.dataset('oecd')
oecd
```

--------------------------------

### Display Details of 'concept' Dimension

Source: https://github.com/26fe/jsonstat.py/blob/master/docs/notebooks/oecd-canada-jsonstat_v1.rst

Retrieves and displays detailed information about the 'concept' dimension within the 'oecd' dataset. This includes the position, ID, and label for each concept in the dataset.

```python
oecd.dimension('concept')
```

--------------------------------

### Convert JSONStat to Table (Python)

Source: https://github.com/26fe/jsonstat.py/blob/master/docs/notebooks/oecd-canada-jsonstat_v2.rst

This code converts a JSONStat dataset into a Python list representing a table. The `.to_table()` method extracts the data in a structured format. The output is a list of lists, where each inner list represents a row in the table. The first few rows are displayed.

```python
oecd.to_table()[:5]
```

--------------------------------

### Plotting Time-Series Data for Italy (excluding France) with jsonstat.py

Source: https://github.com/26fe/jsonstat.py/blob/master/examples-notebooks/eurostat.ipynb

This snippet demonstrates how to generate a time-series plot for Italy by excluding data for France from the dataset. It uses the `to_data_frame()` method with `blocked_dims={'geo':'FR'}` and then plots the resulting DataFrame. This allows for focused analysis on Italy's economic trends.

```python
import jsonstat
import pandas as pd
import matplotlib.pyplot as plt

# Assuming nama_gdp_c_2 is loaded from the previous snippet
df_3 = nama_gdp_c_2.to_data_frame('time', content='id', blocked_dims={'geo':'FR'})
df_3 = df_3.dropna()
df_3.plot(grid=True,figsize=(20,5))
plt.show()
```

--------------------------------

### Display Details of 'year' Dimension

Source: https://github.com/26fe/jsonstat.py/blob/master/docs/notebooks/oecd-canada-jsonstat_v1.rst

Retrieves and displays detailed information about the 'year' dimension within the 'oecd' dataset. This includes the position, index (ID), and label for each year represented in the dataset.

```python
oecd.dimension('year')
```

--------------------------------

### Creating DataFrame with Another Blocked Dimension

Source: https://github.com/26fe/jsonstat.py/blob/master/docs/notebooks/eurostat.rst

Similar to the previous snippet, this Python code creates a pandas DataFrame from the 'nama_gdp_c' Eurostat dataset but blocks the 'geo' dimension to 'IT'. It then removes NaN values and plots the time series data for Italy. This facilitates a direct comparison of analytical approaches for different countries.

```python
df_4 = nama_gdp_c_2.to_data_frame('time', content='id', blocked_dims={'geo':'IT'})
df_4 = df_4.dropna()
df_4.plot(grid=True,figsize=(20,5))
```

--------------------------------

### Explore Dataset Dimension in jsonstat

Source: https://github.com/26fe/jsonstat.py/blob/master/examples-notebooks/cso_ie.ipynb

This snippet shows how to access and explore a specific dimension of a dataset within a JsonstatCollection. It uses the 'dimension' method to retrieve the 'Sector' and 'Quarter' dimensions. This allows examination of the categories and labels associated with each dimension.

```python
dataset.dimension('Sector')

```

```python
dataset.dimension('Quarter')
```

--------------------------------

### Plotting Time-Series Data for Italy and France with jsonstat.py and Matplotlib

Source: https://github.com/26fe/jsonstat.py/blob/master/examples-notebooks/eurostat.ipynb

This code snippet processes the DataFrame obtained from the Eurostat dataset to plot time-series data for Italy and France. It cleans the data by dropping NaNs, reshapes it using `pivot` for plotting, and then uses `matplotlib` to create a line plot. This visualization helps in comparing economic indicators over time between the two countries.

```python
import jsonstat
import pandas as pd
import matplotlib.pyplot as plt

# Assuming df_2 is created from the previous snippet
df_FR_IT = df_2.dropna()[['time', 'geo', 'Value']]
df_FR_IT = df_FR_IT.pivot('time', 'geo', 'Value')
df_FR_IT.plot(grid=True, figsize=(20,5))
plt.show()
```

--------------------------------

### Retrieve Specific Value from Eurostat Dataset with jsonstat.py

Source: https://github.com/26fe/jsonstat.py/blob/master/examples-notebooks/eurostat.ipynb

This code demonstrates how to fetch a specific data value from the Eurostat dataset by providing dimension filters. It retrieves the 'B1GM' value for 'EUR_HAB' unit in '2012' for both 'IT' and 'FR' using the `value()` method. This is useful for targeted data retrieval.

```python
import jsonstat
import pandas as pd

# Assuming nama_gdp_c_2 is loaded from the previous snippet
value_it = nama_gdp_c_2.value(time='2012',geo='IT')
value_fr = nama_gdp_c_2.value(time='2012',geo='FR')

print(f"Value for IT in 2012: {value_it}")
print(f"Value for FR in 2012: {value_fr}")
```

--------------------------------

### Jsonstat Collection Data Structure

Source: https://github.com/26fe/jsonstat.py/blob/master/docs/api_jsonstat.rst

Defines the structure of a json-stat collection, including optional version, class, href, updated timestamp, and links to datasets. This structure serves as a container for multiple datasets.

```json
collection := {
  [ "version" :
 `string` ]
  [ "class" :
 "collection" ]
  [ "href" :
 `url` ]
  [ "updated":
 `date` ]
 link :
 {
     item :
     [
         ( dataset )+
     ]
 }
}
```

--------------------------------

### Accessing Dimension Information in Eurostat Data

Source: https://github.com/26fe/jsonstat.py/blob/master/docs/notebooks/eurostat.rst

This Python code uses the jsonstat.py library to access and display information about a specific dimension ('geo') within the 'nama_gdp_c' Eurostat dataset. It retrieves the positions, IDs, and labels for each entry in the dimension, which is useful for understanding the categorical variables in the dataset.

```python
nama_gdp_c_2.dimension('geo')
```

--------------------------------

### Enable Inline Plotting in Jupyter

Source: https://github.com/26fe/jsonstat.py/blob/master/docs/notebooks/oecd-canada-jsonstat_v1.rst

Configures the Jupyter Notebook environment to display plots directly within the notebook output. This is a standard practice for interactive data visualization in notebooks.

```python
%matplotlib inline
```

--------------------------------

### Display Details of 'area' Dimension

Source: https://github.com/26fe/jsonstat.py/blob/master/docs/notebooks/oecd-canada-jsonstat_v1.rst

Retrieves and displays detailed information about the 'area' dimension within the 'oecd' dataset. This shows the position, index (ID), and label for each geographical area included in the dataset.

```python
oecd.dimension('area')
```

--------------------------------

### Explore Dataset Dimensions and Datapoints

Source: https://github.com/26fe/jsonstat.py/blob/master/README.rst

This Python snippet shows how to iterate through the dimensions of a JSON-stat dataset and retrieve a specific datapoint using dimension values.

```python
import jsonstat

url = 'http://json-stat.org/samples/oecd-canada.json'
collection = jsonstat.from_url(url)
oecd = collection.dataset(0)

# print description about each dimension of the dataset
for d in oecd.dimensions():
    print(d)

# print a datapoint contained into the dataset
print(oecd.value(area='IT', year='2012'))
```

--------------------------------

### Retrieve Data Value with Concept and Area/Year

Source: https://github.com/26fe/jsonstat.py/blob/master/docs/notebooks/oecd-canada-jsonstat_v1.rst

Retrieves a specific data value from the 'oecd' dataset using 'concept', 'area', and 'year' identifiers. This demonstrates accessing data points with explicit concept labels.

```python
oecd.value(concept='unemployment rate',area='Australia',year='2004')
```

--------------------------------

### Import Libraries for JSON-stat Analysis

Source: https://github.com/26fe/jsonstat.py/blob/master/docs/notebooks/oecd-canada-jsonstat_v1.rst

Imports necessary Python libraries for data manipulation, file operations, and plotting, specifically for working with the jsonstat.py library. Includes pandas for DataFrame conversion and matplotlib for plotting.

```python
# all import here
from __future__ import print_function
import os
import pandas as ps # using panda to convert jsonstat dataset to pandas dataframe
import jsonstat     # import jsonstat.py package

import matplotlib as plt  # for plotting
```

--------------------------------

### Creating DataFrame with Blocked Dimensions

Source: https://github.com/26fe/jsonstat.py/blob/master/docs/notebooks/eurostat.rst

This Python code generates a pandas DataFrame from the 'nama_gdp_c' Eurostat dataset, focusing on the 'time' dimension while blocking the 'geo' dimension to 'FR'. It removes NaN values and plots the resulting time series data. This allows for focused analysis of a specific country's data.

```python
df_3 = nama_gdp_c_2.to_data_frame('time', content='id', blocked_dims={'geo':'FR'})
df_3 = df_3.dropna()
df_3.plot(grid=True,figsize=(20,5))
```

--------------------------------

### Jsonstat Dimension Index Representation

Source: https://github.com/26fe/jsonstat.py/blob/master/docs/api_jsonstat.rst

Illustrates the possible formats for representing a dimension index in json-stat. It can be a dictionary mapping category names to integers or a list of category values.

```json
dimension_index :=
                    {
<cat1>:int,
....}      # { "2003" : 0, "2004" : 1, "2005" : 2, "2006" : 3 }
                 |
                    [ <cat1>,
<cat2> ]   # [  2003,
2004 ]
```

--------------------------------

### Access Dataset from JsonStatCollection

Source: https://github.com/26fe/jsonstat.py/blob/master/docs/notebooks/eurostat.rst

Retrieves a specific dataset, identified by its name, from a `JsonStatCollection` object. The `dataset()` method is used for this purpose. The returned object is a `JsonStatDataSet` which contains detailed information about the data, including its dimensions and size.

```python
nama_gdp_c_1 = collection_1.dataset('nama_gdp_c')
nama_gdp_c_1
```

--------------------------------

### Access JsonStatDimension Properties (Python)

Source: https://github.com/26fe/jsonstat.py/blob/master/docs/api_jsonstat_dimension.rst

Methods like `did`, `label`, `role`, and `pos` are used to retrieve specific properties of a JsonStatDimension object. These methods provide access to the dimension's unique identifier, its human-readable label, its role within the dataset, and its positional information, respectively. No external dependencies are noted for these accessors.

```python
def did(self):
    """Get the dimension ID."""
    pass

def label(self):
    """Get the dimension label."""
    pass

def role(self):
    """Get the dimension role."""
    pass

def pos(self):
    """Get the dimension position."""
    pass
```

--------------------------------

### Jsonstat Dimension Data Structure

Source: https://github.com/26fe/jsonstat.py/blob/master/docs/api_jsonstat.rst

Describes the structure of a json-stat dimension, including its label, class, and a category object. The category object contains index, label, child, coordinates, and unit information for the dimension.

```json
dimension :=
{
    "label" :
    <string>
    "class" :
    "dimension"
    "category: {
                  "index"       :
                  dimension_index
                  "label"       :
                  dimension_label
                  "child"       :
                  dimension_child
                  "coordinates" :
                  "unit"        :
                  dimension_unit
                   }
}

```

--------------------------------

### Access Dataset Dimension in Python

Source: https://github.com/26fe/jsonstat.py/blob/master/examples-notebooks/cso_ie.ipynb

This code snippet shows how to access a specific dimension within a JSON-stat dataset using the jsonstat.py library. It assumes a 'dataset' object has already been initialized with JSON-stat data.

```python
dataset.dimension('Statistic')
```

--------------------------------

### Plotting Time-Series Data for France (excluding Italy) with jsonstat.py

Source: https://github.com/26fe/jsonstat.py/blob/master/examples-notebooks/eurostat.ipynb

This code snippet generates a time-series plot specifically for France by filtering out data pertaining to Italy. It utilizes the `to_data_frame()` method with `blocked_dims={'geo':'IT'}` and then visualizes the cleaned DataFrame. This provides a clear view of France's economic indicators over time.

```python
import jsonstat
import pandas as pd
import matplotlib.pyplot as plt

# Assuming nama_gdp_c_2 is loaded from the previous snippet
df_4 = nama_gdp_c_2.to_data_frame('time', content='id', blocked_dims={'geo':'IT'})
df_4 = df_4.dropna()
df_4.plot(grid=True,figsize=(20,5))
plt.show()
```

--------------------------------

### Inspect JSON-Stat Dataset Dimension

Source: https://github.com/26fe/jsonstat.py/blob/master/examples-notebooks/oecd-canada-jsonstat_v1.ipynb

Retrieves detailed information about a specific dimension (e.g., 'concept', 'area', 'year') within a JSON-Stat dataset. This helps understand the data's structure and available categories. Dependencies: jsonstat.

```python
import jsonstat

# Assuming oecd is already selected
# oecd = collection.dataset('oecd')

# Inspecting the 'concept' dimension
print(oecd.dimension('concept'))

# Inspecting the 'area' dimension
print(oecd.dimension('area'))

# Inspecting the 'year' dimension
print(oecd.dimension('year'))
```

--------------------------------

### Convert JSON-stat Dataset to Pandas DataFrame

Source: https://github.com/26fe/jsonstat.py/blob/master/README.rst

This Python code demonstrates how to convert a JSON-stat dataset into a pandas DataFrame, specifying a column for the time dimension.

```python
import jsonstat

url = 'http://json-stat.org/samples/oecd-canada.json'
collection = jsonstat.from_url(url)
oecd = collection.dataset(0)

# convert a dataset in pandas dataframe
df = oecd.to_data_frame('year')
```

--------------------------------

### Explore Time Dimension with jsonstat.py

Source: https://github.com/26fe/jsonstat.py/blob/master/docs/notebooks/eurostat.rst

Explores the 'time' dimension of a `JsonStatDataSet`. The `dimension()` method is used to access information about a specific dimension, including its position, index, label, and size. This is useful for understanding the temporal scope of the dataset.

```python
nama_gdp_c_1.dimension('time')
```

--------------------------------

### Accessing Dimensions in Eurostat Dataset with jsonstat.py

Source: https://github.com/26fe/jsonstat.py/blob/master/examples-notebooks/eurostat.ipynb

This snippet shows how to retrieve information about a specific dimension ('geo') within a loaded Eurostat dataset. It lists the available values and their corresponding labels for the 'geo' dimension, enabling users to filter or select data based on geographical regions. It requires the dataset to be loaded first.

```python
import jsonstat
import pandas as pd

# Assuming nama_gdp_c_2 is loaded from the previous snippet
print(nama_gdp_c_2.dimension('geo'))
```

--------------------------------

### Parse JsonStatDimension from JSON (Python)

Source: https://github.com/26fe/jsonstat.py/blob/master/docs/api_jsonstat_dimension.rst

The `from_json` method facilitates the creation of a JsonStatDimension object from a JSON data structure. This is a common way to load dimension information when working with JSON-formatted datasets. The input should be a valid JSON object or dictionary.

```python
def from_json(cls, json_data):
    """Create a JsonStatDimension from JSON data."""
    pass
```

--------------------------------

### Retrieve Data Value with Concept ID, Area ID, and Year

Source: https://github.com/26fe/jsonstat.py/blob/master/docs/notebooks/oecd-canada-jsonstat_v1.rst

Retrieves a specific data value from the 'oecd' dataset using concept ID ('UNR'), area ID ('AU'), and year ('2004'). This shows accessing data using concise identifiers.

```python
oecd.value(concept='UNR',area='AU',year='2004')
```

--------------------------------

### Import Libraries for JSON-stat Data Handling in Python

Source: https://github.com/26fe/jsonstat.py/blob/master/docs/notebooks/oecd-canada-jsonstat_v2.rst

Imports necessary Python libraries for working with JSON-stat data, including pandas for data manipulation and matplotlib for plotting. It also configures matplotlib to display plots inline within the notebook. Dependencies include pandas, jsonstat, and matplotlib.

```python
# all import here
from __future__ import print_function
import os
import pandas as ps # using panda to convert jsonstat dataset to pandas dataframe
import jsonstat     # import jsonstat.py package

import matplotlib as plt  # for plotting 
%matplotlib inline
```

--------------------------------

### Retrieve Specific Data Values from a JsonStatDataSet in Python

Source: https://github.com/26fe/jsonstat.py/blob/master/docs/notebooks/oecd-canada-jsonstat_v2.rst

Demonstrates how to access specific data values from a `JsonStatDataSet`. It shows how to retrieve a value by specifying dimension identifiers (e.g., `area='IT', year='2012'`) using both `data()` and `value()` methods. It also shows retrieving values using concept, area, and year identifiers, including direct ID usage.

```python
oecd.data(area='IT', year='2012')
```

```python
oecd.value(area='IT', year='2012')
```

```python
oecd.value(concept='unemployment rate',area='Australia',year='2004') # 5.39663128
```

```python
oecd.value(concept='UNR',area='AU',year='2004')
```