Donation

Donation allows one Collection to make its data available through another Collection. When a Collection is donated, it becomes immutable - the donor collection is locked from modifications to ensure data consistency. A Collection can receive donations from several Collections.

Note

The donating Collection needs to contain all evaluation dates of the receiving Collection.

Note

When a Collection has been donated, a copy of the donated Collection is made. This copy is locked and may not itself be modified or donated again.

Performing Donation

The basic form of donation uses one collection as donor and another as receiver:

# Donate collection_donor to collection_receiver
collection_new = donate(collection_receiver, collection_donor)

By default, each Asset in collection_receiver receives data from the Asset with the same ticker in collection_donor. This behavior can be modified using a DonationProtocol.

DonationProtocol

A DonationProtocol specifies which Assets in collection_donor donate to which Assets in collection_receiver. For example:

# Create protocol where each receiver gets data from all donors
dp = dp_all_to_all(collection_receiver, collection_donor)

# Perform donation with custom protocol
collection_new = donate(collection_receiver, collection_donor, dp)

Accessing Donated Data

Donated data is accessed through DonatedDataViews. For example:

# Add SMA layer to collection
collection_sma = add_layer(collection, LayerSMA)

# Ensure collections share evaluation dates
collection = collection[collection_sma]

# Create collection with donated data
collection_donated = donate(collection, collection_sma)

# Access the donated data
asset = get_first_asset(collection_donated)
donated_dv = DVLayerDictKey(
    get_donated_asset_link(asset, "MMM"), 
    :ma_values, 
    26
)

Common Uses

Combining Layer Analyses

Since one Collection may only contain one chain of Layers, donation enables combining analyses from different layer chains:

# Create collections with different layer chains
collection_sma = add_layer(collection, LayerSMA)
collection_ema = add_layer(collection, LayerEMA)

# Align dates
collection = collection[collection_sma]
collection = collection[collection_ema]

# Combine analyses through donation
collection_combined = donate(collection, collection_sma)
collection_combined = donate(collection_combined, collection_ema)

Creating Layers with Dependencies

The primary use of donation is to create Layers that depend on data from multiple other Layers. Since a Collection can only contain one chain of Layers, donation allows a new Layer to access data computed in separate Layer chains.

Donation can also be useful for:

  • Trading one Asset based on signals from other Assets
  • Combining signals across Assets, such as in correlation studies

Functions

For functions related to Collection donation see Collection Donation - Functions.