Finance

Finance-specific data cleaning functions.

convert_currency(df, api_key, column_name=None, from_currency=None, to_currency=None, historical_date=None, make_new_column=False)

Deprecated function.

Source code in janitor/finance.py

@pf.register_dataframe_method
@deprecated_alias(colname="column_name")
def convert_currency(
    df: pd.DataFrame,
    api_key: str,
    column_name: str = None,
    from_currency: str = None,
    to_currency: str = None,
    historical_date: date = None,
    make_new_column: bool = False,
) -> pd.DataFrame:
    """Deprecated function.

    <!--
    # noqa: DAR101
    # noqa: DAR401
    -->
    """
    raise JanitorError(
        "The `convert_currency` function has been temporarily disabled due to "
        "exchangeratesapi.io disallowing free pinging of its API. "
        "(Our tests started to fail due to this issue.) "
        "There is no easy way around this problem "
        "except to find a new API to call on."
        "Please comment on issue #829 "
        "(https://github.com/pyjanitor-devs/pyjanitor/issues/829) "
        "if you know of an alternative API that we can call on, "
        "otherwise the function will be removed in pyjanitor's 1.0 release."
    )

convert_stock(stock_symbol)

This function takes in a stock symbol as a parameter, queries an API for the companies full name and returns it

Examples:

```python
import janitor.finance
janitor.finance.convert_stock("aapl")
```

Parameters:

Name	Type	Description	Default
stock_symbol	str	Stock ticker Symbol	required

Raises:

Type	Description
ConnectionError	Internet connection is not available

Returns:

Type	Description
str	Full company name

Source code in janitor/finance.py

def convert_stock(stock_symbol: str) -> str:
    """
    This function takes in a stock symbol as a parameter,
    queries an API for the companies full name and returns
    it

    Examples:

        ```python
        import janitor.finance
        janitor.finance.convert_stock("aapl")
        ```

    Args:
        stock_symbol: Stock ticker Symbol

    Raises:
        ConnectionError: Internet connection is not available

    Returns:
        Full company name
    """
    if is_connected("www.google.com"):
        stock_symbol = stock_symbol.upper()
        return get_symbol(stock_symbol)
    else:
        raise ConnectionError(
            "Connection Error: Client Not Connected to Internet"
        )

get_symbol(symbol)

This is a helper function to get a companies full name based on the stock symbol.

Examples:

```python
import janitor.finance
janitor.finance.get_symbol("aapl")
```

Parameters:

Name	Type	Description	Default
symbol	str	This is our stock symbol that we use to query the api for the companies full name.	required

Returns:

Type	Description
Optional[str]	Company full name

Source code in janitor/finance.py

def get_symbol(symbol: str) -> Optional[str]:
    """
    This is a helper function to get a companies full
    name based on the stock symbol.

    Examples:

        ```python
        import janitor.finance
        janitor.finance.get_symbol("aapl")
        ```

    Args:
        symbol: This is our stock symbol that we use
            to query the api for the companies full name.

    Returns:
        Company full name
    """
    result = requests.get(
        "http://d.yimg.com/autoc."
        + "finance.yahoo.com/autoc?query={}&region=1&lang=en".format(symbol)
    ).json()

    for x in result["ResultSet"]["Result"]:
        if x["symbol"] == symbol:
            return x["name"]
        else:
            return None

inflate_currency(df, column_name=None, country=None, currency_year=None, to_year=None, make_new_column=False)

Inflates a column of monetary values from one year to another, based on the currency's country.

The provided country can be any economy name or code from the World Bank list of economies.

Note: This method mutates the original DataFrame.

Examples:

>>> import pandas as pd
>>> import janitor.finance
>>> df = pd.DataFrame({"profit":[100.10, 200.20, 300.30, 400.40, 500.50]})
>>> df
   profit
0   100.1
1   200.2
2   300.3
3   400.4
4   500.5
>>> df.inflate_currency(
...    column_name='profit',
...    country='USA',
...    currency_year=2015,
...    to_year=2018,
...    make_new_column=True
... )
   profit  profit_2018
0   100.1   106.050596
1   200.2   212.101191
2   300.3   318.151787
3   400.4   424.202382
4   500.5   530.252978

Parameters:

Name	Type	Description	Default
df	DataFrame	A pandas DataFrame.	required
column_name	str	Name of the column containing monetary values to inflate.	None
country	str	The country associated with the currency being inflated. May be any economy or code from the World Bank List of economies.	None
currency_year	int	The currency year to inflate from. The year should be 1960 or later.	None
to_year	int	The currency year to inflate to. The year should be 1960 or later.	None
make_new_column	bool	Generates new column for inflated currency if True, otherwise, inflates currency in place.	False

Returns:

Type	Description
DataFrame	The DataFrame with inflated currency column.

Source code in janitor/finance.py

@pf.register_dataframe_method
def inflate_currency(
    df: pd.DataFrame,
    column_name: str = None,
    country: str = None,
    currency_year: int = None,
    to_year: int = None,
    make_new_column: bool = False,
) -> pd.DataFrame:
    """
    Inflates a column of monetary values from one year to another, based on
    the currency's country.

    The provided country can be any economy name or code from the World Bank
    [list of economies](https://databank.worldbank.org/data/download/site-content/CLASS.xls).

    **Note**: This method mutates the original DataFrame.

    Examples:

        >>> import pandas as pd
        >>> import janitor.finance
        >>> df = pd.DataFrame({"profit":[100.10, 200.20, 300.30, 400.40, 500.50]})
        >>> df
           profit
        0   100.1
        1   200.2
        2   300.3
        3   400.4
        4   500.5
        >>> df.inflate_currency(
        ...    column_name='profit',
        ...    country='USA',
        ...    currency_year=2015,
        ...    to_year=2018,
        ...    make_new_column=True
        ... )
           profit  profit_2018
        0   100.1   106.050596
        1   200.2   212.101191
        2   300.3   318.151787
        3   400.4   424.202382
        4   500.5   530.252978

    Args:
        df: A pandas DataFrame.
        column_name: Name of the column containing monetary
            values to inflate.
        country: The country associated with the currency being inflated.
            May be any economy or code from the World Bank
            [List of economies](https://databank.worldbank.org/data/download/site-content/CLASS.xls).
        currency_year: The currency year to inflate from.
            The year should be 1960 or later.
        to_year: The currency year to inflate to.
            The year should be 1960 or later.
        make_new_column: Generates new column for inflated currency if
            True, otherwise, inflates currency in place.

    Returns:
        The DataFrame with inflated currency column.
    """  # noqa: E501

    inflator = _inflate_currency(country, currency_year, to_year)

    if make_new_column:
        new_column_name = column_name + "_" + str(to_year)
        df[new_column_name] = df[column_name] * inflator

    else:
        df[column_name] = df[column_name] * inflator

    return df