.. _functions:

Functions
=========

RiskScape allows **user defined** functions to be used for risk modelling.
This let's you customize your risk analysis to suit the particular domain you are modelling.
For example, you could define your own earthquake fragility function or
flood vulnerability function.

RiskScape also provides some **built-in** functions for general-purpose maths, geometry, and
aggregation operations.
For example, to round a floating point number, you can use the `round` built-in function like `round(-34.23)`.

:ref:`RiskScape expressions <expressions>` are used in many places, 
such as in bookmark configuration, model parameters, or model pipeline code.
User-defined functions and built-in RiskScape functions can be used from *any* RiskScape expression.
This combination makes modelling in RiskScape flexible and powerful, as you
can add your own functions to customize the processing of your model data.

## User-defined functions

RiskScape provides several different ways (or 'frameworks') for defining your own risk function:

- :ref:`CSV functions <csv_functions>`, which are a simple way to use a CSV file to define a fragility or vulnerability curve.
- :ref:`python-functions`, which actually come in two different 'flavours':
  - :ref:`jython-impl`, which is a built-in Java-based Python implementation.
  Useful for simple Python functions, but becomes a bit awkward if you need to import other Python packages.
  - :ref:`cpython-impl`, which uses the Python installed on your computer.
  This requires an extra one-off step to configure RiskScape.
- :ref:`expression_functions`, which use the RiskScape expression language itself,
  and may be helpful for advanced users.

.. tip::
    To learn more about defining your own risk functions, start off by looking
    at the :ref:`functions_tutorial` tutorial.

.. _builtin_functions:

## Built-in functions

RiskScape comes with the following sets of built-in functions that are useful for doing things like mathematics
in the context of RiskScape and Risk Analysis.
Click on a link to see all the functions available in that category.

.. toctree::
   :maxdepth: 1
   :glob:

   functions/generated/*
   aggregation.md

.. tip::
    You can also see a list of built-in functions available via the CLI.
    For example, to list the maths functions available in RiskScape,
    run ``riskscape function list --category maths``

Where possible, RiskScape makes use of common Java packages that are widely used and
are proven to produce reliable mathematical results.
For example, the `square_root()` RiskScape function is just a simple 'wrapper' for the
Java `Math.sqrt()` function.

