Whole Segments Tree


The Whole Segments Tree resource represents (potentially) the whole of the Segments Tree, which contains analysis results data in the form of segments, securities and measure values. (The Segments Tree Node resource, by contrast, represents only one node of the tree, where the node represents a segment. The resource can include that segment’s children, which are either child segments or securities.)

A portfolio analysis with results data always exposes a hierarchical collection of segments and securities, known as the Segments Tree. Through this resource, calling applications can obtain data for the tree’s root node (the Total segment), or all segments, or all securities, or the Total segment and all securities, or all segments and securities (i.e. the whole tree) - for one or more measures across one or more time periods.

Unlike virtually all other resources exposed by the web service, the Whole Segments Tree resource is represented by CSV (comma-separated values) only. There are no XML and JSON representations, and the request’s Accept header is ignored.

The Whole Segments Tree resource has been designed to support requests for the Multiple OCP Time Series resource, in that it exposes the segment identifiers that the latter needs. See the documentation on the multiple-ocp-time-series-query link relation for further details.

The key to understanding the Whole Segments Tree resource is knowing what data can be included in any one request, and how to formulate a query for that data. To this end, please see the documentation for the whole-segments-tree-query link relation, which contains the full details.

Media type

The Whole Segments Tree resource is exposed via a single CSV representation, which has the following media type name:- > application/vnd.statpro.revolution.api.whole-segments-tree+csv

When a response is received from the web service with status 200 (= OK), the fact that the response contains a Whole Segments Tree resource representation is indicated by the presence of the response header:- > Content-Type: application/vnd.statpro.revolution.api.whole-segments-tree+csv; charset=utf-8


CSV representation (example)

1,27,7,"FICTIONAL SECURITY, SE",5.2,-6.3,7.4,9.8
1,31,6,BP PLC,,,,
1,28,6,BG GROUP PLC,-0.224088956620961,-0.445544385605846,,0.119144341580659
1,15,7,AIR LIQUIDE,2.0,-3.1,,
1,18,7,ANGLO AMERICAN PLC,4.2,5.3,6.4,7.8

For this example, the query strings in the URI that requested the data were: ?timePeriods=Earliest,1D&measures=Rp,Wp&include=All

See below for an explanation of the data format.

Notes on the CSV data format

  1. Headers isSecurity, id, parentId, and name are static and are always present in every representation.
  2. Headers Rp.Earliest, Wp.Earliest, Rp.1D, and Wp.1D (in the above example) are dynamic, and reflect the requested time periods and measures.
  3. Regarding the order of headers:- static headers come before dynamic headers. Within the static headers, there is no stated order (note also that extra static fields may be introduced in the future). This means that static columns MUST be identified by header name, and not by position. Within the dynamic headers relating to measures and time periods, the order is the order in which the time periods and measures were requested in the timePeriods and measures query strings, with the measures changing more rapidly.
  4. For the isSecurity column:- 0 = a segment; 1 = a security
  5. For the id column:- the values are unique segment and security identifiers. They are guaranteed to be positive integers (greater than or equal to zero). They are scoped to the current, finished analysis only. They do not have global scope, and do not persist beyond the lifetime of the current set of analysis results. When a new set of analysis results is generated for the same portfolio, the segment and security identifiers will be new. These identifiers are opaque, i.e. they have no meaning. If the TOTAL segment has id N in one set of analysis results, it is NOT guaranteed that it will have the same id N in another set of analysis results (even for the same portfolio). The same goes for the other segments, and for securities.
  6. For a given set of analysis results, the segment and security identifiers are static - i.e. they do not change. Note that the segment identifiers are needed when requesting data from the Multiple OCP Time Series resource (for the same set of analysis results).
  7. For the parentId column:- for any one row, the value is the identifier of the segment’s or security’s parent segment. Special value -1 is reserved as the parent segment id of the TOTAL segment (aka the Total segment, which sits at the root of the tree).
  8. For the name column:- the values are the names of each segment / security. These strings are normally unquoted. A name will be surrounded by leading and trailing double-quote characters if a) it is empty or contains only whitespace (which is unlikely), or b) it contains a comma and/or a double-quote character - as in "FICTIONAL SECURITY, SE" in the example above. Genuine double-quote characters within segment / security names are encoded as two consecutive double-quote characters; e.g. name CITIGROUP INC - DPS (RE: 1/10TH PFD SER "V" FXD ADJ) will exist in the CSV as "CITIGROUP INC - DPS (RE: 1/10TH PFD SER ""V"" FXD ADJ)".
  9. For the measure + time period columns, e.g. Rp.Earliest:- the format of the header name is <measure identifier> + <dot> + <time period code>. The measure identifiers are normalized to their case-correct forms, as are the time period codes. E.g. if the requested data is ?timePeriods=earliest&measures=rp the resulting header name will be Rp.Earliest.
  10. For the measure + time period columns:- the values are measure values. The vast majority of these are real numbers; a handful are strings (see the Segments Tree measures list for details). Any measure value can be null; a null value in the CSV is represented by an empty cell. For non-null string measure values, the same encoding rules that are used for names (see point 8 above) are applied. The example above illustrates missing measure values. Note especially that for segment Materials, the last column (header Wp.1D) is missing its measure value - this is not immediately obvious when looking at the CSV data.
  11. There is no order to the rows in the returned CSV data. I.e. the rows are returned in no particular order. Even though it may seem that the rows are (often) in some kind of order, this is not to be trusted or relied upon. See the following section for instructions on processing the returned data in order to determine its tree hierarchy.

How to determine the hierarchical tree structure

Having requested the whole tree (i.e. all segments and all securities), and having parsed the CSV data into a collection of records within your application:-

  • search for the record whose parent (segment) id is -1; this record represents the TOTAL segment; store its identifier
  • search for those segment records whose parent (segment) id is equal to the id of the TOTAL segment; these records represent the TOTAL segment’s immediate child segments
  • repeat the same procedure for each child segment; note that a child segment will have either segments or securities as its immediate children
  • when searching, don’t assume any ordering of the CSV rows as supplied by the web service.

Future-proofing your application against data enhancements

To prevent your application from malfunctioning in the future, when new headers / columns are introduced to the CSV representation:-

  • pay attention to the stated order of the headers/columns (or lack thereof), given in point 3 in the Notes section above
  • don’t assume that the number of static columns is fixed; the number may increase in future releases
  • identify static columns by header name (e.g. isSecurity) rather than by position.

Update history

  • Initial Version - September 2014

Last updated: September 2014