subgrounds.dataframe_utils module#

Pandas DataFrame utility module containing functions related to the formatting of GraphQL JSON data into DataFrames.

subgrounds.dataframe_utils.gen_columns(data, prefix='')#
subgrounds.dataframe_utils.fmt_cols(df, col_map)#
class subgrounds.dataframe_utils.DataFrameColumns(key, fpaths)#

Bases: object

Helper class that holds data related to the shape of a DataFrame

key: str#
fpaths: list[str]#

Returns new DataFrameColumns containing the union of self and other's columns


other (DataFrameColumns) -- Columns to be combined to self


New DataFrameColumns containing the union of

self and other

Return type:


mk_df(data, path_map)#

Formats the JSON data data into a DataFrame containing the columns defined in self.

  • data (list[dict[str, Any]]) -- The JSON data to be formatted into a dataframe

  • path_map (dict[str, FieldPath]) -- A dictionary of (key-FieldPath) pairs


The JSON data formatted into a DataFrame

Return type:



Generates a list of DataFrame columns specifications based on a list of Selection trees.


selections (list[Selection]) -- The selection trees


The list of DataFrame columns specifications

Return type:


subgrounds.dataframe_utils.df_of_json(json_data, fpaths, columns=None, concat=False)#

Formats the JSON data json_data into Pandas DataFrames, flattening the data in the process.

Depending on the request's fieldpaths, either one or multiple dataframes will be returned based on how flattenable the response data is.

fpaths is a list of FieldPath objects corresponding to the set of fieldpaths that were used to get the response data json_data.

columns is an optional argument used to rename the dataframes(s) columns. The length of columns must be the same as the number of columns of all returned dataframes.

concat indicates whether or not the resulting dataframes should be concatenated together. The dataframes must have the same number of columns, as well as the same column names (which can be set using the columns argument).

  • json_data (list[dict[str, Any]]) -- Response data

  • fpaths (list[FieldPath]) -- Fieldpaths that yielded the response data

  • columns (Optional[list[str]], optional) -- Column names. Defaults to None.

  • concat (bool, optional) -- Flag indicating whether or not to concatenate the resulting dataframes, if there are more than one. Defaults to False.


The resulting dataframe(s)

Return type:

pd.DataFrame | list[pd.DataFrame]