Peer Group

morningstar_data.direct.get_peer_group_breakpoints(

investments: List[str] | str,

data_points: List[Dict[str, Any]] | DataFrame,

order: Order = Order.ASC,

percentiles: List[int] | None = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99, 100],

methodology: PeerGroupMethodology | None = None,

) → DataFrame

Gets peer group breakpoints for the specified list of investments and specified list of datapoints.

The investments can be provided in one of the following ways:

• Investment IDs - a list of strings, where each string is the SecId of the investment.

• List ID - a GUID that represents a saved list id.

• Search Criteria ID - a numeric string that represents a saved search criteria.

• Category ID - a string that represents the secId of the category, the format is ‘secId;universe’.

The data_points can be provided in one of the following ways. The API only support calculation data points. At the

same time, it only supports the same calculation data point with different settings within a request.

• Data Point IDs - a list of dicts, where each dict contains the property datapointId and alias. Data will be returned for this data point with its default parameters. If you would like to override some of those defaults, they can be added to the object. For instance:

  • { “datapointId”: “41”, “alias”: “Z1”} - this would return breakpoints of standard deviation for the last 3 years (the default behavior).

  • { “datapointId”: “41”, “alias”: “Z2”, “startDate”: “2015-01-01”, “endDate”: “2017-12-31”} - this would return breakpoints of standard deviation for the time period between Jan 1, 2015 and Dec 31, 2017.

• Data Point Settings - a DataFrame of data points with all defined settings. Each row represents a data point. Each column is a configurable setting and should contains datapointId and alias.

Parameters:

• investments (Investments, required) –

  An object which can be one of the following:

  • 1. A list of investment codes (list, optional): Use this for an ad hoc approach to selecting investments, rather than using a list or a search. The investment code format is secid;universe. For example: [“F00000YOOK;FO”,”FOUSA00CFV;FO”].

  • 2. A list ID (str, optional): The unique identifier of the saved investment list from the Workspace module in Morningstar Direct. The format is GUID. For example, “EBE416A3-03E0-4215-9B83-8D098D2A9C0D”.

  • 3. Search Criteria ID (str, optional): The unique identifier of a saved search criteria from Morningstar Direct. The id string is numeric. For example, “9009”.

  • 4. Category ID (str, optional): The secid of the category, the format is ‘secId;universe’. For example, “EUCA000564;FO”.

• data_points (DataPoints, required) –

  An object which can be one of the following:

  • 1. Data point IDs (list, optional): A list of unique identifiers for data points. The format is an array of data points with (optionally) associated settings. Each data point should contains datapointId and alias. For example:

    [
        {
            "datapointId": "41",
            "alias": "Z1"
        },
        {
            "datapointId": "41",
            "alias": "Z2",
            "startDate": "2021-07-01",
            "endDate": "2021-12-31",
            "windowType": "2",
            "windowSize": "3",
            "stepSize": "2"
        }
    ]
    

  • 2. Data point settings (DataFrame, optional): A DataFrame of data points and their associated setting values. Each data point should contains datapointId and alias.

• order (Order, optional) – The order of peer group breakpoint. Enumeration md.direct.Order.DESC or md.direct.Order.ASC is available. Default md.direct.Order.ASC if empty.

• percentiles (list, optional) – Default [1,2,3,…,100] if empty and its values range from 1 to 100.

• methodology (PeerGroupMethodology, optional) – The methodology to calculation breakpoints. Enumeration md.direct.PeerGroupMethodology.MORNINGSTAR or md.direct.PeerGroupMethodology.SIMPLE is available. Based on global setting Custom Peer Group Ranking if empty.

Returns:

A DataFrame object with peer group breakpoint data. The DataFrame column includes alias that user input in parameter datapoint_ids.

Return type:

DataFrame

Examples:

Get peer group breakpoint data for standard deviation datapoint.

import morningstar_data as md

df = md.direct.get_peer_group_breakpoints(
        investments='740284aa-fcd3-43f6-99d1-8f3d4a179fcc',
        data_points=[
            {"datapointId": "41", "alias": "Z1"},
            {"datapointId": "41", "alias": "Z2", "startDate": "2021-07-01", "endDate": "2021-12-31", "windowType": "2", "windowSize": "3", "stepSize": "2"}
        ],
        order=md.direct.Order.ASC,
        percentiles=[25, 50, 75, 100]
    )
df

Output:

Alias	StartDate	EndDate	25	50	75	100
Z1	2019-04-01	2022-03-31	17.301437	12.720889	7.055372	-3.460187
Z2	2021-07-01	2021-09-30	1.827371	-0.804269	-4.899745	-52.143678
Z2	2021-09-01	2021-11-30	-0.030321	-4.336051	-10.618009	-40.980480

Errors:

AccessDeniedError: Raised when user lacks permission or not authorized to access the resource.

BadRequestException: Raised due to multiple reasons including invalid/incorrect request, malformed request syntax, or deceptive request routing.

NetworkExceptionError: Raised when there is an issue with the internet connection or if the request is made from an unsecure network.

ResourceNotFoundError: Raised when the requested resource does not exist in Direct.