seriesbr.helpers package

Submodules

seriesbr.helpers.dates module

seriesbr.helpers.dates.api_date_format_of(date, api)

Auxiliary function to convert datetime.datetime object to string compatible with a given API.

seriesbr.helpers.dates.check_if_quarter(dates)

Check if month of a datetime object is less than 4, i.e., if it is a quarter.

seriesbr.helpers.dates.last_day_of_month(date)

Auxiliary function that returns the last day of the month, if no day is specified.

See: https://stackoverflow.com/questions/42950/get-last-day-of-the-month

seriesbr.helpers.dates.month_to_quarter(date, fmt=None)

Convert month to quarter, i.e., 12 -> 4, 6 -> 2, 7 -> 3 etc.

Parameters:date (datetime.datetime) – Returns: Return type:datetime.datetime

Examples

>>> dates.month_to_quarter(datetime.datetime(2019, 12, 1))
datetime.datetime(2019, 4, 1, 0, 0)

seriesbr.helpers.dates.parse_date(date_str, api, start=True)

Auxiliary function to convert different dates strings to the format required by an API.

Also, when it is an end date, if day is unspecificed, the day will be the last day of the month. Similarly, if month is not specified, the month must be 12.

Note that the date string is assumed to start with day or month. Otherwise, unexpected results can arise.

Parameters:

• date_str (str) – String to be parsed.
• api (str) – Name of the api. Possible values are “ibge”, “ipea” and “bcb”.
• start (bool) – If it is a start date.

Returns:

Appropriate date string for a given API.

Return type:

str

Raises:

ValueError – If the string could not be converted to a datetime.datetime object by strptime.

Examples

>>> dates.parse_date("012017", api="bcb")
'01/01/2017'
>>> dates.parse_date("01-2017", api="ipea")
'2017-01-01T00:00:00-00:00'
>>> dates.parse_date("01/2017", api="ibge")
'201701'

seriesbr.helpers.dates.parse_dates(start, end, api)

Auxiliary function to call dates functions.

Returns:Date format as required by an API. Return type:str

seriesbr.helpers.dates.today_date()

Returns today’s date.

Returns:Today’s date. Return type:datetime.datetime

seriesbr.helpers.dates.very_old_date()

Returns very old date (01/01/1900).

Returns: Return type:datetime.datetime

seriesbr.helpers.ipea_metadata_list module

seriesbr.helpers.lists module

seriesbr.helpers.lists.list_metadata_helper(resource_path)

Auxiliary function to request metadata information about a IPEA’s time series.

Parameters:resource_path (str) – Which kind of information to be requested, e.g. themes, countries. Returns:A DataFrame with the specified resource. Return type:pandas.DataFrame

seriesbr.helpers.lists.list_regions_helper(region, search, searches)

Auxiliary function to list information about a given location in IBGE’s database.

Parameters:

• region (str) – Kind of region to list (macroregion, state etc.)
• search (list) – Strings to search in names column.
• searches (dict) – Strings to search in other columns.

Returns:

A DataFrame with the regions, filtered if specified.

Return type:

pandas.DataFrame

seriesbr.helpers.metadata module

seriesbr.helpers.metadata.bcb_metadata_to_df(url)

Auxiliary function to request metadata from BCB database and turn the returned JSON into a DataFrame.

Parameters:url (str) – Url to be requested. Returns:A DataFrame with metadatas in its columns. Return type:pandas.DataFrame

seriesbr.helpers.metadata.ibge_metadata_to_df(url)

Auxiliary function to request metadata from IBGE database and turn the returned JSON into a DataFrame.

Parameters:url (str) – Url to be requested. Returns:A DataFrame with metadatas in its columns. Return type:pandas.DataFrame

seriesbr.helpers.metadata.ipea_metadata_to_df(url)

Auxiliary function to request metadata from IPEA database and turn the returned JSON into a DataFrame.

Parameters:url (str) – Url to be requested. Returns:A DataFrame with metadatas in its columns. Return type:pandas.DataFrame

seriesbr.helpers.request module

seriesbr.helpers.request.get_json

Auxiliary function to make get requests within a HTTP Session.

Parameters:

• url (str) – Url to be requested.
• **kwargs – Passed to Session().get()

Returns:

Decoded JSON.

Return type:

dict

seriesbr.helpers.response module

seriesbr.helpers.response.bcb_json_to_df(url, code, name)

Auxiliary function to convert json produced by BCB’s and IPEA’s API into a DataFrame.

Parameters:url (str) – Url to be requested. Returns:A DataFrame with time series’ values and a DateTimeIndex. Return type:pandas.DataFrame

seriesbr.helpers.response.ibge_json_to_df(url, freq='mensal')

Auxiliary function to convert json produced by IBGE’s API into a DataFrame.

Parameters:url (str) – Url to be requested. Returns:A DataFrame with time series’ values, metadatas and a DateTimeIndex. Return type:pandas.DataFrame

seriesbr.helpers.response.ipea_json_to_df(url, code, name)

Auxiliary function to convert json produced by BCB’s and IPEA’s API into a DataFrame.

Parameters:url (str) – Url to be requested. Returns:A DataFrame with time series’ values and a DateTimeIndex. Return type:pandas.DataFrame

seriesbr.helpers.searching module

seriesbr.helpers.searching.bcb_get_search_results(url)

Auxiliary function to request BCB’s search results and turn json into a DataFrame.

Parameters:url (str) – Url to be requested. Returns:A DataFrame with the search results. Return type:pandas.DataFrame Raises:AssertionError – If nothing was found.

seriesbr.helpers.searching.ipea_get_search_results(url)

Auxiliary function to request IPEA’s search results and turn json into a DataFrame.

Parameters:url (str) – Url to be requested. Returns:A DataFrame with the search results. Return type:pandas.DataFrame Raises:AssertionError – If nothing was found.

seriesbr.helpers.url module

seriesbr.helpers.url.contains_operator(metadata, values)

Auxiliary function to make string with OData’s contains logical operator.

Parameters:

• metadata (str or list of str) – Metadatas to be filtered.
• metadata – Values to filter by.

Returns:

• A valid string to perform the query
• via OData’s URL convention.

Examples

>>> url.contains_operator(["FNTNOME", "UNINOME"], ["A", "B"])
"(contains(['FNTNOME', 'UNINOME'],'A') or contains(['FNTNOME', 'UNINOME'],'B'))"

seriesbr.helpers.url.equal_operator(metadata, values)

Auxiliary function to make string with OData’s equal logical operator.

Parameters:

• metadata (str or list of str) – Metadatas to be filtered.
• metadata – Values to filter by.

Returns:

• A valid string to perform the query
• via OData’s URL convention.

Examples

>>> url.equal_operator(["SERNUMERICA", "PAICODIGO"], [1, "A"])
"(['SERNUMERICA', 'PAICODIGO'] eq 1 or ['SERNUMERICA', 'PAICODIGO'] eq 'A')"

seriesbr.helpers.url.ibge_make_classifications_query(classifications=None)

Auxiliary function to make classifications part of the URL.

Parameters:classifications (int, str, list or dict) – Dictionary of classifications (keys) and categories (values) or a set of classifcations as int, str, or list. Returns:A valid string to filter by classifications and categories. Return type:str

Examples

>>> url.ibge_make_classification_query({1: [2, 3]})
'classificacao=1[2,3]'

>>> url.ibge_make_classification_query([1, 2])
'classificacao=1[all]|2[all]'

>>> url.ibge_make_classification_query(3)
'classificacao=3[all]'

seriesbr.helpers.url.ibge_make_dates_query(start=None, end=None, last_n=None, freq=None)

Auxiliary function to filter a time series’ periods.

Parameters:

• start (str) – Initial date string.
• end (str) – Final date string.
• last_n (str or int) – Get last n observations
• freq (str) – Time series frequency.

Returns:

A valid string to filter dates in IBGE’s API.

Return type:

str

Examples

>>> url.ibge_make_dates_query(last_n=5)
'/periodos/-5'
>>> url.ibge_make_dates_query(start="012017")
'/periodos/201701-201912'
>>> url.ibge_make_dates_query(end="072017")
'/periodos/190001-201707'
>>> url.ibge_make_dates_query(start="052015", end="072017")
'/periodos/201505-201707'

seriesbr.helpers.url.ibge_make_locations_query(municipality=None, state=None, macroregion=None, microregion=None, mesoregion=None, brazil=None)

Auxiliary function to filter an IBGE’s aggregate by variables.

Parameters:

• municipality –
• state –
• macroregion –
• microregion –
• mesoregion –
• brazil –

Returns:

A string to filter locations in IBGE’s API.

Return type:

str

Examples

>>> url.ibge_make_location_query()
'&localidades=BR'
>>> url.ibge_make_location_query(city=True)
'&localidades=N6[all]'
>>> url.ibge_make_location_query(city=1)
'&localidades=N6[1]'
>>> url.ibge_make_location_query(city=[2, 3, 4])
'&localidades=N6[2,3,4]'

seriesbr.helpers.url.ibge_make_variables_query(variables=None)

Auxiliary function to filter an IBGE’s aggregate by variables.

Parameters:variables (int or list of int) – The variables’ codes. Returns:A string to filter variables in IBGE’s API. Return type:str

Examples

>>> url.ibge_make_variables_query(100)
'/variaveis/100'
>>> url.ibge_make_variables_query([1, 2, 3])
'/variaveis/1|2|3'
>>> url.ibge_make_variables_query()
'/variaveis/'

seriesbr.helpers.url.ipea_make_dates_query(start=None, end=None)

Auxiliary function to return the right string for filtering dates via IPEA api.

Parameters:

• start (str) – Start date string.
• End (str) – End date string.

Returns:

A string to filter by dates.

Return type:

str

Examples

>>> url.ipea_make_dates_query("2019-01-01T00:00:00-00:00", "2019-02-01T00:00:00-00:00")
'&$filter=VALDATA ge 2019-01-01T00:00:00-00:00 and VALDATA le 2019-02-01T00:00:00-00:00'

seriesbr.helpers.url.ipea_make_filter_query(names, metadatas)

Auxiliary function to make filter query for IBGE’s database API.

Parameters:

• names (list of str) – Strings to filter by name.
• metadatas (dict) – Dictionary whose keys are metadatas and values strings (or list of strings) to look up for.

Returns:

A string to filter metadatas.

Return type:

str

Raises:

ValueError – If not a valid metadata.

Examples

>>> url.ipea_make_filter_query("SELIC", {})
"&$filter=contains(SERNOME,'SELIC')"

>>> url.ipea_make_filter_query("SELIC", {"PERNOME": ["mensal", "trimestral"], "FNTNOME": "IBGE"})
"&$filter=contains(SERNOME,'SELIC') and (contains(PERNOME,'mensal') or contains(PERNOME,'trimestral')) and contains(FNTNOME,'IBGE')"

>>> url.ipea_make_filter_query("SELIC", {"SERSTATUS": "A", "SERNUMERICA": 1})
"&$filter=contains(SERNOME,'SELIC') and SERSTATUS eq 'A' and SERNUMERICA eq 1"

seriesbr.helpers.url.ipea_make_select_query(metadatas)

Auxiliary function to make select query for IBGE’s web API.

It loops through the keys of a dictionary and makes the string by joining them.

Parameters:metadatas (dict) – Metadatas used in the search. Returns:A string to select metadatas. Return type:str

Examples

>>> url.ipea_make_select_query("")
'?$select=SERCODIGO,SERNOME,PERNOME,UNINOME'

>>> url.ipea_make_select_query(["FNTNOME"])
'?$select=SERCODIGO,SERNOME,PERNOME,UNINOME,FNTNOME'

If a metadata is already selected by default, nothing changes:

>>> url.ipea_make_select_query(["PERNOME"])
'?$select=SERCODIGO,SERNOME,PERNOME,UNINOME'

seriesbr.helpers.url.quote_if_str(something)

Auxiliary function to put quotes around value if it is a string. Needed to make filter queries for OData’s equal logical operator in case of a string.

Parameters:something – Any object. Returns:

• A string around quote if something is a string,
• else just the object coerced to a string.

seriesbr.helpers.utils module

seriesbr.helpers.utils.build_regex(strings)

Build regex by joining strings by ‘|’ only if it is an iterable other than a str.

seriesbr.helpers.utils.cat(something, sep)

Auxiliary function to join an iterable delimited by sep, forcing the join by coercing the items to be strings.

Parameters:

• something (list) – List to be joined.
• sep (str) – Delimiter.

Returns:

String with values in something joined by sep.

Return type:

str

seriesbr.helpers.utils.clean_json(json)

Helper function to turn JSON into a DataFrame and clean its columns names.

seriesbr.helpers.utils.do_search(df, search, searches)

Auxiliary function to search for regex in a column of a DataFrame.

It builds a string to be passed to the query method of a DataFrame.

Parameters:

• df (pandas.DataFrame) –
• search (list of strings) –
• searches (dict) –

Raises:

ValueError – If the user tries to search in a non-existent column.

seriesbr.helpers.utils.isiterable(something)

Auxiliary function to test if something is an iterable (unless it’s a str).

Returns:True if an iterable other than str, False otherwise. Return type:bool

seriesbr.helpers.utils.return_codes_and_names(*args)

Auxiliary function to label columns of a DataFrame.

If it finds a dictionary, it will use its keys as labels and values as series’ codes.

Otherwise, the codes themselves will serve as columns’ labels.

Returns:First element with codes and second element with names. Return type:tuple