DOC: Expand on reference docs for read_json

[cswarth]

• closes #xxxx
• tests added / passed
• passes git diff upstream/master | flake8 --diff
• [] whatsnew entry

Continuation of closed PR #14284
Documentation update for read_json().
expanded reference document for pandas.read_json(), especially concentrating on the orient parameter. Also added some example usage code and explicitly mention to_json() as a source of valid JSON strings.

pandas.read_json¶

pandas.read_json(path_or_buf=None, orient=None, typ='frame', dtype=True, convert_axes=True, convert_dates=True, keep_default_dates=True, numpy=False, precise_float=False, date_unit=None, encoding=None, lines=False)[source]¶

Convert a JSON string to pandas object

Parameters:

path_or_buf : a valid JSON string or file-like, default: None The string could be a URL. Valid URL schemes include http, ftp, s3, and file. For file URLs, a host is expected. For instance, a local file could be file://localhost/path/to/table.json orient : string, Indication of expected JSON string format. Compatible JSON strings can be produced by to_json() with a corresponding orient value. The set of possible orients is: 'split' : dict like {index -> [index], columns -> [columns], data -> [values]} 'records' : list like [{column -> value}, ... , {column -> value}] 'index' : dict like {index -> {column -> value}} 'columns' : dict like {column -> {index -> value}} 'values' : just the values array The allowed and default values depend on the value of the typ parameter. when typ == 'series', allowed orients are {'split','records','index'} default is 'index' The Series index must be unique for orient 'index'. when typ == 'frame', allowed orients are {'split','records','index', 'columns','values'} default is 'columns' The DataFrame index must be unique for orients 'index' and 'columns'. The DataFrame columns must be unique for orients 'index', 'columns', and 'records'. typ : type of object to recover (series or frame), default ‘frame’ dtype : boolean or dict, default True If True, infer dtypes, if a dict of column to dtype, then use those, if False, then don’t infer dtypes at all, applies only to the data. convert_axes : boolean, default True Try to convert the axes to the proper dtypes. convert_dates : boolean, default True List of columns to parse for dates; If True, then try to parse datelike columns default is True; a column label is datelike if it ends with '_at', it ends with '_time', it begins with 'timestamp', it is 'modified', or it is 'date' keep_default_dates : boolean, default True If parsing dates, then parse the default datelike columns numpy : boolean, default False Direct decoding to numpy arrays. Supports numeric data only, but non-numeric column and index labels are supported. Note also that the JSON ordering MUST be the same for each term if numpy=True. precise_float : boolean, default False Set to enable usage of higher precision (strtod) function when decoding string to double values. Default (False) is to use fast but less precise builtin functionality date_unit : string, default None The timestamp unit to detect if converting dates. The default behaviour is to try and detect the correct precision, but if this is not desired then pass one of ‘s’, ‘ms’, ‘us’ or ‘ns’ to force parsing only seconds, milliseconds, microseconds or nanoseconds respectively. lines : boolean, default False Read the file as a json object per line. New in version 0.19.0. encoding : str, default is ‘utf-8’ The encoding to use to decode py3 bytes. New in version 0.19.0.

Returns:

result : Series or DataFrame, depending on the value of typ.

Examples

>>> df = pd.DataFrame([['a', 'b'], ['c', 'd']],
...                   index=['row 1', 'row 2'],
...                   columns=['col 1', 'col 2'])

Encoding/decoding a Dataframe using 'split' formatted JSON:

>>> df.to_json(orient='split')
'{"columns":["col 1","col 2"],
  "index":["row 1","row 2"],
  "data":[["a","b"],["c","d"]]}'
>>> pd.read_json(_, orient='split')
      col 1 col 2
row 1     a     b
row 2     c     d

Encoding/decoding a Dataframe using 'index' formatted JSON:

>>> df.to_json(orient='index')
'{"row 1":{"col 1":"a","col 2":"b"},"row 2":{"col 1":"c","col 2":"d"}}'
>>> pd.read_json(_, orient='index')
      col 1 col 2
row 1     a     b
row 2     c     d

Encoding/decoding a Dataframe using 'records' formatted JSON. Note that index labels are not preserved with this encoding.

>>> df.to_json(orient='records')
'[{"col 1":"a","col 2":"b"},{"col 1":"c","col 2":"d"}]'
>>> pd.read_json(_, orient='records')
  col 1 col 2
0     a     b
1     c     d

[codecov-io]

Current coverage is 85.25% (diff: 100%)

Merging #14442 into master will decrease coverage by <.01%

@@             master     #14442   diff @@
==========================================
  Files           140        140          
  Lines         50631      50631          
  Methods           0          0          
  Messages          0          0          
  Branches          0          0          
==========================================
- Hits          43167      43166     -1   
- Misses         7464       7465     +1   
  Partials          0          0          

Powered by Codecov. Last update 7cad3f1...bdc25b7

[jreback]

does this need corresponding updates in read_json?

[jreback]

can you add a See Also section and reference read_json (and vice versa there)

[jorisvandenbossche]

@jreback This is the docstring of read_json ?

[jreback]

sorry, meant to_json for the reference in See Also

[jorisvandenbossche]

@cswarth Very minor comment about whitespace (rst .. :-))

[jorisvandenbossche]

@jreback This is the docstring of read_json ?

[jorisvandenbossche]

There is some indentation here compared to the base level of "The set of ..." (which is not needed)

[jorisvandenbossche]

@cswarth Thanks a lot!
If you want to improve the to_json docstring with some examples as well, very welcome!