Currency Exchange
=================

Graphene has support for currency exchange, letting you input and analyze data
in different currencies.


.. _base-currency:

Base Currency
-------------

The first thing to understand when working with currencies in Graphene is that
all monetary values are given a currency, even if it is not explicitly stated.
When a currency is not explicitly stated, the concept of the base currency is
used.

The **base currency** can be interpreted and used however you wish. It is
recommended that your usage of it within the system should remain consistent.
For most users of Graphene, the ideal choice will be your most common reporting
currency, such as ``USD``. This effectively means that ``USD`` will be assumed
(by both users and the system itself) any time a currency is not specified.

Exchange Rate Table
-------------------

To begin, you will need an exchange rate table uploaded to your AWS S3 bucket.
The exchange rate table should be a ``.csv`` file that looks like this:

.. code-block::

   currency,rate
   CAD,3.14159265
   XBT,2000000
   GBP,1.61803399

The first line `must` be a header that defines the order of the columns.
Currently, only ``currency`` and ``rate`` are supported.

After that, each line should define, at the least, a ``currency`` and a
``rate``.

The ``currency`` can be any string. Keep in mind, however, the name here will be
used as an identifier in any structures that reference it. A `currency code`_
is an ideal option.

The ``rate`` must be a number. ``rate`` is defined relative to a :ref:`base
currency <base-currency>`, which is used by any structures which output currency
values and do not have a currency specified. Specifically, ``rate`` defines the
number of ``currency`` that are equal to 1 unit of the `base currency`. In other
words, it is the number by which you would multiply the `base currency` to get
the equivalent value of the currency, or the exchange rate.

Define the Rate Table Used for a Request
----------------------------------------

When making the request, add the field ``rate_table_uri =
"s3://<your-bucket>/uploads/fx_tables/myratesfile.csv"`` to your request, for example, the
``NetworkAnalysisStreamRequest``.

Supported requests are:

- `NetworkAnalysisStreamRequest <api_reference.html#are-v1-analysis-NetworkAnalysisStreamRequest>`__


Reporting in an Alternative Currency
------------------------------------

To report results in an alternative currency, set the ``currency`` field as part
of your descriptor when making the request. For example, to receive a ledger
export in ``GBP``, ensure it is part of your rate table, and add the field
``currency = "GBP"`` to the ``LedgerExportDescriptor``. Make sure to provide the
S3 location for the rate table you wish to use at the top level of the request.

Supported descriptors are:

- `AggregationDescriptor <api_reference.html#are-v1-analysis-AggregationDescriptor>`__
- `LedgerExportDescriptor <api_reference.html#are-v1-analysis-LedgerExportDescriptor>`__
- `LedgerSQLQueryDescriptor <api_reference.html#are-v1-analysis-LedgerSQLQueryDescriptor>`__

Defining Structures in an Alternative Currency
----------------------------------------------

If using the Analyze Re provided :ref:`templates <Templates>`, structures that support different
currencies will have a ``currency`` field which can be set. When creating a node
that uses such a schema, setting the ``currency`` field will adjust all currency
related fields in the structure accordingly (ie. ``attachment``, ``limit``,
etc).  When creating nodes with a ``currency`` field, Graphene requires that any
requests that use such a node provide a rate table that defines an exchange rate
for the currency.

Supported templates are:

- AggXL
- CatXL
- LoadMultipleFiles
- LossSet
- OccurrenceCoverage
- QuotaShare
- ScaledLoad

.. _currency code: https://en.wikipedia.org/wiki/ISO_4217#Active_codes