Class: Ledger::Sdk::Models::Container::Instance

Inherits:
Base::Instance show all
Defined in:
lib/ledger/sdk/models/container.rb

Overview

Represents an individual container instance.

Has associations to Account, Position, Fee and FeeExclusion allowing navigation to the accounts, positions, fees and fee exclusions attached to this container.

Instance Method Summary collapse

Methods inherited from Base::Instance

association, #data, #initialize

Constructor Details

This class inherits a constructor from Ledger::Sdk::Models::Base::Instance

Instance Method Details

#accounts(associated_id = nil) ⇒ Account, Account::Instance

Access the accounts associated with this container.

Parameters:

  • associated_id (String, Integer, nil) (defaults to: nil) —

    ID of a specific account, or nil to get the collection

Returns:

#balances(name) ⇒ Balance

Access the balances of this container for a given balance name.

Parameters:

  • name (String) —

    the balance name. Known names: official, official_with_updated_price, transparent, transparent_with_updated_price. Not validated by the SDK.

Returns:

  • (Balance) —

    the balance collection scoped to this container

#charge_breakdown(as_of: nil, from: nil) ⇒ Hash

Per-label ventilation of this container's charges, embedded by the container show when requested (+with_component_breakdown+): totals, monthly buckets and the underlying component lines. The window is read as of an instant: as_of is the upper bound (ledger defaults to today), from the optional lower bound (inception when nil). Read-only.

Parameters:

  • as_of (String, Date, nil) (defaults to: nil) —

    viewing date (ISO 8601)

  • from (String, Date, nil) (defaults to: nil) —

    optional lower bound (ISO 8601)

Returns:

  • (Hash) —

    the breakdown document

#external_flows(from: nil, to: nil, currency: nil) ⇒ Object

#fee_exclusions(associated_id = nil) ⇒ FeeExclusion, FeeExclusion::Instance

Access the fee-base exclusions attached to this container.

Parameters:

  • associated_id (String, Integer, nil) (defaults to: nil) —

    ID of a specific fee exclusion, or nil to get the collection

Returns:

#fees(associated_id = nil) ⇒ Fee, Fee::Instance

Access the fees attached to this container.

Parameters:

  • associated_id (String, Integer, nil) (defaults to: nil) —

    ID of a specific fee, or nil to get the collection

Returns:

  • (Fee) —

    the fee collection (if no ID)

  • (Fee::Instance) —

    a fee instance (if ID provided)

#performance(from: nil, to: nil, method: nil, name: nil, income: nil, granularity: nil, money_weighted: nil) ⇒ Hash

This container's performance over a window: the composed return of the portfolio, of each of its accounts and of each line, plus what the price and the currency each drove (+contribution+). Read-only.

Unlike #charge_breakdown the whole document is the answer, not a field of a show — this is its own endpoint.

contribution is always relative to the subject queried: a line's contribution here is its share of the portfolio's return, not of its own account's — read the same line from Account::Instance#performance for that. contribution_series, when present, likewise describes only this container, never the nested accounts.

contribution is null — the key is there, its value is not — whenever there is nothing to decompose: a cash line, or a window ledger cannot chain (a day that lost everything leaves no growth factor to take a log of, as an onboarding mandate does when it banks its cash before its holdings are priced). Null says "no answer"; a zero would have claimed the lines produced nothing.

Ledger defaults to to the container's latest revalued balance date and from to thirty days before it. An unreadable date, an unknown method, name or granularity falls back to the default rather than failing.

Parameters:

  • from (String, Date, nil) (defaults to: nil) —

    window start (ISO 8601)

  • to (String, Date, nil) (defaults to: nil) —

    window end (ISO 8601)

  • method (String, nil) (defaults to: nil) —

    twr (default), mwr or dietz (Modified Dietz)

  • name (String, nil) (defaults to: nil) —

    balance series: official, official_with_updated_price (default), transparent, transparent_with_updated_price

  • income (String, nil) (defaults to: nil) —

    net (default) or gross of withholding tax

  • granularity (String, nil) (defaults to: nil) —

    day, month, quarter, semester or year to also get contribution_series; omitted when nil

  • money_weighted (Boolean, nil) (defaults to: nil) —

    true to also get money_weighted (+mwr+ and dietz); omitted when nil, and the key is then absent

Returns:

  • (Hash) —

    the performance document

#performance_statistics(from: nil, to: nil, name: nil) ⇒ Hash

This container's risk statement over a window: fifteen measures of return, dispersion and drawdown, plus the monthly returns they are all derived from (+periodic_returns+). Read-only.

The measures are a pure function of the monthly returns of #time_series over the same window — the two documents therefore agree by construction. periodicity says which rank was chained (+monthly+) and periods_count how many months carried a return; months without one are dropped from both the count and periodic_returns.

A measure the window does not define is null — the key is there, its value is not. Percentages are in base 100 (4.75 for 4.75 %); sharpe_ratio is a bare ratio, taken against risk_free_rate, which the document carries so a reader can name it.

Parameters:

  • from (String, Date, nil) (defaults to: nil) —

    window start (ISO 8601)

  • to (String, Date, nil) (defaults to: nil) —

    window end (ISO 8601)

  • name (String, nil) (defaults to: nil) —

    balance series, as on #performance

Returns:

  • (Hash) —

    the performance statistics document

#positions ⇒ Position

Access every position of this container in one call (each account's displayable positions), via /containers/<id>/positions.

Returns:

  • (Position) —

    the container-wide position collection

#time_series(from: nil, to: nil, name: nil) ⇒ Hash

This container's chronological statement over a window: the same window read at three scales — the whole period, each of its months, each of their days — with a return, a gain and five amounts per row. Read-only.

The three ranks carry exactly the same keys; a month additionally carries days. The days travel inside the same response, under their month, so unfolding a month on screen costs no further call.

value_in_percentage and value are null — the keys are there, their values are not — on a range no daily row covers: "we do not know" is not "reported nothing". value is the money gain, and it ADDS UP where the percentage chains: a month is the sum of its days, and the period the sum of its months.

Parameters:

  • from (String, Date, nil) (defaults to: nil) —

    first day of the period (ISO 8601)

  • to (String, Date, nil) (defaults to: nil) —

    last day of the period (ISO 8601)

  • name (String, nil) (defaults to: nil) —

    balance series, as on #performance

Returns:

  • (Hash) —

    the time series document

#unrealized_gains(on: nil, name: nil) ⇒ Hash

This container's unrealized gains on a day: one line per holding — its value, its cost basis (weighted average purchase price, carrying the exchange rate of the purchases), the gain and its percentage of the cost — and the totals. Read-only.

Amounts are in the container's currency (+currency+), percentages in base 100. on is at most yesterday; ledger falls back to the latest day it has valued, and the document says which day it answered for (+on+). Each line names its position by id (+position.id+), the id #positions carries.

Parameters:

  • on (String, Date, nil) (defaults to: nil) —

    the day (ISO 8601)

  • name (String, nil) (defaults to: nil) —

    balance series, as on #performance

Returns:

  • (Hash) —

    the unrealized gains statement

#update(attributes) ⇒ Hash

Updates this container's attributes. Alongside fees and fee-exclusions management, this is one of the SDK's few write operations — most of the SDK remains read-only. Used by folio to persist the container's asset manager (+manager_id+, a mosaic bank id). Updates this container's attributes. This is the SDK's ONE write operation — everything else is read-only. Used by folio to persist the container's asset manager (+manager_id+, a mosaic bank id).

Parameters:

  • attributes (Hash) —

    attributes to update, e.g. { manager_id: 42 }

Returns:

  • (Hash) —

    the refreshed container data

#wealth_evolution(from: nil, to: nil, name: nil) ⇒ Hash

This container's wealth evolution over a window: how it goes from its opening value to its closing one, line by line. Read-only.

Parameters:

  • from (String, Date, nil) (defaults to: nil) —

    first day of the period (ISO 8601)

  • to (String, Date, nil) (defaults to: nil) —

    last day of the period (ISO 8601)

  • name (String, nil) (defaults to: nil) —

    balance series, as on #performance

Returns:

  • (Hash) —

    the wealth evolution document

#wealth_evolution_line(line, from: nil, to: nil) ⇒ Object

Raises:

  • (ArgumentError)