C# Client Library
A C# Client Library for the AnalyzeRe REST API
BaseAPIResourceView.cs
Go to the documentation of this file.
1 using System;
2 using System.Collections.Generic;
3 using System.Linq;
4 using System.Runtime.Serialization;
5 
6 using AnalyzeRe.APITypes;
8 using AnalyzeRe.Metrics;
9 using AnalyzeRe.Rest;
10 using AnalyzeRe.Utilities;
11 
12 // Disable warnings about snake_case function names in this method. While it goes against
13 // C# best-practice, it's done intentionally to follow the API conventions closely.
14 #pragma warning disable IDE1006
15 
16 namespace AnalyzeRe.APIResourceView
17 {
20  {
21  #region Private Fields
22  private YLTSimulationResult _ylt;
24 
26  private YELTSimulationResult _yelt;
27  #endregion Private Fields
28 
29  #region Public Properties
30  [DataMember(Order = 11)]
32  [NotNull]
33  public IReference<AnalysisProfile> analysis_profile { get; set; }
34 
36  [DataMember(Order = 12)]
38  public string ylt_id { get; set; }
39 
43  [DataMember(Order = 13)]
45  public string target_currency { get; set; }
46 
49  [IgnoreDataMember]
50  public YLTSimulationResult ylt => _ylt ?? (_ylt = new YLTSimulationResult(this));
51 
54  [IgnoreDataMember]
55  public YELTSimulationResult yelt => _yelt ?? (_yelt = new YELTSimulationResult(this));
56  #endregion Public Properties
57 
58  #region Public Metrics Requests
59  #region Tail Metrics
60  public TailMetrics tail_metrics(
67  double probability, MetricsOptions options)
68  {
69  return this.GetSubResource<TailMetrics>(new WindowMetricsRequest(
70  ProbabilityWindow.Tail(probability)), options?.GetParameters());
71  }
72 
80  public List<TailMetrics> tail_metrics(IEnumerable<double> probabilities, MetricsOptions options)
81  {
82  IList<ProbabilityWindow> converted = probabilities.Select(ProbabilityWindow.Tail).ToList();
83  return VectorizedRequest<TailMetrics>(converted,
84  new WindowMetricsRequest(converted), options?.GetParameters());
85  }
86  #endregion Tail Metrics
87 
88  #region Window Metrics
89  public WindowMetrics window_metrics(ProbabilityWindow range, MetricsOptions options)
96  {
97  return this.GetSubResource<WindowMetrics>(new WindowMetricsRequest(range),
98  options?.GetParameters());
99  }
100 
108  public List<WindowMetrics> window_metrics(IEnumerable<ProbabilityWindow> ranges, MetricsOptions options)
109  {
110  IList<ProbabilityWindow> asList = ranges as IList<ProbabilityWindow> ?? ranges.ToList();
111  return VectorizedRequest<WindowMetrics>(asList,
112  new WindowMetricsRequest(asList), options?.GetParameters());
113  }
114  #endregion Window Metrics
115 
116  #region Co-Metrics
117  public CoMetrics co_metrics<T>(
127  ProbabilityWindow range, IReference<T> component, CoMetricsOptions options)
128  where T : IAPIResourceView
129  {
130  return this.GetSubResource<CoMetrics>(new CoMetricsRequest(range),
131  GetCoMetricsParameters(component, options));
132  }
133 
143  public List<CoMetrics> co_metrics<T>(
144  IEnumerable<ProbabilityWindow> ranges, IReference<T> component, CoMetricsOptions options)
145  where T : IAPIResourceView
146  {
147  IList<ProbabilityWindow> asList = ranges as IList<ProbabilityWindow> ?? ranges.ToList();
148  return new List<CoMetrics>(VectorizedRequest<CoMetrics>(asList,
149  new CoMetricsRequest(asList), GetCoMetricsParameters(component, options)));
150  }
151 
152  #region Private Helper Methods
153  private RequestParameters GetCoMetricsParameters<T>(
160  IReference<T> component, CoMetricsOptions options)
161  where T : IAPIResourceView
162  {
163  return (options?.GetParameters() ?? new RequestParameters())
164  .AddQueryParameter("component_id", component.ref_id)
165  .AddQueryParameter("component_type", GetComponentTypeFromReference(component));
166  }
167 
171  private string GetComponentTypeFromReference<T>(IReference<T> component)
172  where T : IAPIResourceView
173  {
174  // Get the most accurate type we can for the referenced component.
175  Type referenceType = component.resolved ? component.GetValue().GetType() : typeof(T);
176  // Convert the reference type to the string the server expects.
177  string type = typeof(ILayerView).IsAssignableFrom(referenceType) ? "LayerView" :
178  typeof(PortfolioView).IsAssignableFrom(referenceType) ? "PortfolioView" : null;
179  // If the correct type can't be determined from the type argument, see if
180  // the run-time type of the referenced component has more information.
181  if (type == null && typeof(IReference<T>) != component.GetType()
182  && component.GetType().IsGenericType)
183  {
184  referenceType = component.GetType().GetGenericArguments().First();
185  type = typeof(ILayerView).IsAssignableFrom(referenceType) ? "LayerView" :
186  typeof(PortfolioView).IsAssignableFrom(referenceType) ? "PortfolioView" : null;
187  }
188  // Throw an exception if the type could not be resolved.
189  if (type == null)
190  throw new ArgumentException("The component must be a reference to either a " +
191  "LayerView or PortfolioView type. Supplied reference was of type: " +
192  referenceType.NiceTypeName());
193  return type;
194  }
195  #endregion Private Helper Methods
196  #endregion Co-Metrics
197 
198  #region Exceedance Probability
199  public ExceedanceProbability exceedance_probability(
208  double threshold, ExceedanceProbabilityOptions options)
209  {
210  return this.GetSubResource<ExceedanceProbability>(
211  new ExceedanceProbRequest(threshold), options?.GetParameters());
212  }
213 
222  public List<ExceedanceProbability> exceedance_probability(
223  IEnumerable<double> thresholds, ExceedanceProbabilityOptions options)
224  {
225  IList<double> asList = thresholds as IList<double> ?? thresholds.ToList();
226  return VectorizedRequest<ExceedanceProbability>(asList,
227  new ExceedanceProbRequest(asList), options?.GetParameters());
228  }
229  #endregion Exceedance Probability
230 
231  #region Back Allocation
232  [Obsolete("POST a BackAllocatedLayer structure instead.")]
245  public BackAllocations back_allocations(string source_id)
246  {
247  // Make the request from the server.
248  return this.GetSubResource<BackAllocations>(
249  new BackAllocationsRequest(),
250  new RequestParameters().AddQueryParameter(nameof(source_id), source_id));
251  }
252  #endregion Back Allocation
253  #endregion Public Metrics Requests
254 
256  protected override void AfterMembersCloned(APIType _)
257  {
258  base.AfterMembersCloned(_);
259  _ylt = null;
260  _yelt = null;
261  }
262 
263  #region Helper Methods
264  private List<T> VectorizedRequest<T>(IList<double> values,
267  string resource, RequestParameters parameters)
268  {
269  if (values == null || values.Count == 0)
270  throw new ArgumentException("The list of values cannot be null or empty.");
271  // If the user has supplied a list of exactly one probability, the server will
272  // return a single value rather than a list, so we must convert the result to a list.
273  // Otherwise, submit as a normal vectorized request and expect a list of results back.
274  return values.Count == 1 ?
275  new List<T> { this.GetSubResource<T>(resource, parameters) } :
276  this.GetSubResource<List<T>>(resource, parameters);
277  }
278 
281  private List<T> VectorizedRequest<T>(IList<ProbabilityWindow> values,
282  string resource, RequestParameters parameters)
283  {
284  if (values == null || values.Count == 0)
285  throw new ArgumentException("The list of values cannot be null or empty.");
286  // If the user has supplied a list of exactly one probability, the server will
287  // return a single value rather than a list, so we must convert the result to a list.
288  // Otherwise, submit as a normal vectorized request and expect a list of results back.
289  return values.Count == 1 ?
290  new List<T> { this.GetSubResource<T>(resource, parameters) } :
291  this.GetSubResource<List<T>>(resource, parameters);
292  }
293  #endregion Helper Methods
294 
295  #region Request SubResources
296  internal class WindowMetricsRequest : ResourcePathBuilder
299  {
300  private const string SERVER_ENDPOINT_NAME = "window_metrics";
301  protected override string base_path => SERVER_ENDPOINT_NAME;
303  public WindowMetricsRequest(ProbabilityWindow range) : base(range) { }
305  public WindowMetricsRequest(IEnumerable<ProbabilityWindow> ranges) : base(ranges) { }
306  }
307 
310  internal class CoMetricsRequest : ResourcePathBuilder
311  {
312  private const string SERVER_ENDPOINT_NAME = "window_co_metrics";
313  protected override string base_path => SERVER_ENDPOINT_NAME;
315  public CoMetricsRequest(ProbabilityWindow range) : base(range) { }
317  public CoMetricsRequest(IEnumerable<ProbabilityWindow> ranges) : base(ranges) { }
318  }
319 
322  internal class ExceedanceProbRequest : ResourcePathBuilder
323  {
324  private const string SERVER_ENDPOINT_NAME = "exceedance_probabilities";
325  protected override string base_path => SERVER_ENDPOINT_NAME;
327  public ExceedanceProbRequest(double threshold) : base(threshold) { }
329  public ExceedanceProbRequest(IEnumerable<double> thresholds) : base(thresholds) { }
330  }
331 
334  internal class BackAllocationsRequest : ResourcePathBuilder
335  {
336  private const string SERVER_ENDPOINT_NAME = "back_allocations";
337  protected override string base_path => SERVER_ENDPOINT_NAME;
338  }
339  #endregion Request SubResources
340 
341  // TODO: Delete Deprecated Methods after phase-out period.
342  #region Deprecated Public Methods
343  #region Tail Metrics
344  [Obsolete("This method has been replaced with an overload that uses a MetricsOptions object")]
365  double probability,
366  string filter = null,
367  Perspective perspective = null,
368  string currency = null,
369  AggregationMethod? aggregation_method = null,
370  bool? secondary_uncertainty = null)
371  {
372  return tail_metrics(probability, new MetricsOptions(
373  currency, aggregation_method, perspective, filter, secondary_uncertainty));
374  }
375 
395  [Obsolete("This method has been replaced with an overload that uses a MetricsOptions object")]
396  public List<TailMetrics> tail_metrics(
397  List<double> probabilities,
398  string filter = null,
399  Perspective perspective = null,
400  string currency = null,
401  AggregationMethod? aggregation_method = null,
402  bool? secondary_uncertainty = null)
403  {
404  return tail_metrics(probabilities, new MetricsOptions(
405  currency, aggregation_method, perspective, filter, secondary_uncertainty));
406  }
407  #endregion Tail Metrics
408 
409  #region Co-Metrics
410  [Obsolete("This method has been replaced with an overload that uses a CoMetricsOptions object. " +
437  "This legacy method was less flexible and only returned the co-tail-metrics.")]
438  public CoMetrics co_metrics<T>(
439  double probability,
440  IReference<T> component,
441  string filter = null,
442  Perspective perspective = null,
443  string currency = null,
444  string component_filter = null,
445  Perspective component_perspective = null,
446  bool? include_primary_metrics = null,
447  AggregationMethod? aggregation_method = null,
448  bool? secondary_uncertainty = null)
449  where T : IAPIResourceView
450  {
451  return co_metrics(probability, component, new CoMetricsOptions(
452  component_filter, component_perspective, null, include_primary_metrics,
453  currency, aggregation_method, perspective, filter, secondary_uncertainty));
454  }
455 
482  [Obsolete("This method has been replaced with an overload that uses a CoMetricsOptions object. " +
483  "This legacy method was less flexible and only returned the co-tail-metrics.")]
484  public List<CoMetrics> co_metrics<T>(
485  List<double> probabilities,
486  IReference<T> component,
487  string filter = null,
488  Perspective perspective = null,
489  string currency = null,
490  string component_filter = null,
491  Perspective component_perspective = null,
492  bool? include_primary_metrics = null,
493  AggregationMethod? aggregation_method = null,
494  bool? secondary_uncertainty = null)
495  where T : IAPIResourceView
496  {
497  return co_metrics(probabilities, component, new CoMetricsOptions(
498  component_filter, component_perspective, null, include_primary_metrics,
499  currency, aggregation_method, perspective, filter, secondary_uncertainty));
500  }
501 
511  [Obsolete("Please provide a ProbabilityWindow rather than a double tail-probability. " +
512  "This legacy method was less flexible and only returned the co-tail-metrics.")]
513  public CoMetrics co_metrics<T>(
514  double probability, IReference<T> component, CoMetricsOptions options)
515  where T : IAPIResourceView
516  {
517  return co_metrics(ProbabilityWindow.Tail(probability), component, options);
518  }
519 
529  [Obsolete("Please provide a list of ProbabilityWindows rather than doubles. " +
530  "This legacy method was less flexible and only returned the co-tail-metrics.")]
531  public List<CoMetrics> co_metrics<T>(
532  List<double> probabilities, IReference<T> component, CoMetricsOptions options)
533  where T : IAPIResourceView
534  {
535  return co_metrics(probabilities.Select(ProbabilityWindow.Tail), component, options);
536  }
537  #endregion Co-Metrics
538 
539  #region Exceedance Probability
540  [Obsolete("This method has been replaced with an overload that uses an ExceedanceProbabilityOptions object")]
562  double threshold,
563  string filter = null,
564  Perspective perspective = null,
565  bool? inclusive_threshold = null,
566  string threshold_currency = null,
567  AggregationMethod? aggregation_method = null,
568  bool? secondary_uncertainty = null)
569  {
570  return exceedance_probability(threshold, new ExceedanceProbabilityOptions(
571  inclusive_threshold, threshold_currency,
572  aggregation_method, perspective, filter, secondary_uncertainty));
573  }
574 
595  [Obsolete("This method has been replaced with an overload that uses an ExceedanceProbabilityOptions object")]
596  public List<ExceedanceProbability> exceedance_probability(
597  List<double> thresholds,
598  string filter = null,
599  Perspective perspective = null,
600  bool? inclusive_threshold = null,
601  string threshold_currency = null,
602  AggregationMethod? aggregation_method = null,
603  bool? secondary_uncertainty = null)
604  {
605  return exceedance_probability(thresholds, new ExceedanceProbabilityOptions(
606  inclusive_threshold, threshold_currency,
607  aggregation_method, perspective, filter, secondary_uncertainty));
608  }
609  #endregion Exceedance Probability
610  #endregion Deprecated Public Methods
611  }
612 }
static ProbabilityWindow Tail(double tail_probability)
Returns a window representing the tail probability range [0, tail_probability], such that all losses ...
Helper class which makes it easier to build a set of request parameters.
AggregationMethod
Specifies the method of aggregating event occurrences in a trial year for computing different types o...
List< WindowMetrics > window_metrics(IEnumerable< ProbabilityWindow > ranges, MetricsOptions options)
Returns the window metrics of this view for multiple probability ranges.
List< ExceedanceProbability > exceedance_probability(List< double > thresholds, string filter=null, Perspective perspective=null, bool?inclusive_threshold=null, string threshold_currency=null, AggregationMethod?aggregation_method=null, bool?secondary_uncertainty=null)
Obsolete. exceedance_probability(IEnumerable<Double>,ExceedanceProbabilityOptions)Returns the exceeda...
The structure returned when requesting Window Metrics for a view, containing the core window distribu...
PortfolioView and LayerView abstract base class.
The structure returned when requesting Tail Metrics for a view.
PortfolioView and LayerView interface.
A pass-through to the yelt endpoint for configuring and downloading a per-trial simulation result fro...
The structure returned when requesting back-allocated metrics for a view.
List< TailMetrics > tail_metrics(IEnumerable< double > probabilities, MetricsOptions options)
Returns the tail metrics of this view at multiple probabilities.
List< ExceedanceProbability > exceedance_probability(IEnumerable< double > thresholds, ExceedanceProbabilityOptions options)
Returns the exceedance probability for this view for the given losses. That is, the probability the s...
Optional parameters which can be specified for exceedance probability requests.
Represents the Analysis of a Layer
Definition: ILayerView.cs:5
ExceedanceProbability exceedance_probability(double threshold, string filter=null, Perspective perspective=null, bool?inclusive_threshold=null, string threshold_currency=null, AggregationMethod?aggregation_method=null, bool?secondary_uncertainty=null)
Obsolete. exceedance_probability(Double,ExceedanceProbabilityOptions)Returns the exceedance probabili...
override void AfterMembersCloned(APIType _)
Invoked following construction if the current instance has been created using a member-wise clone of ...
The loss perspective determines what factors to include when computing a distribution.
Definition: Perspective.cs:9
Base class used by all resources.
Definition: APIResource.cs:9
Specifies that a property is generated by the server and should not be specified on the client side d...
override RequestParameters GetParameters()
Get the REST request parameters corresponding to this configuration.
List< TailMetrics > tail_metrics(List< double > probabilities, string filter=null, Perspective perspective=null, string currency=null, AggregationMethod?aggregation_method=null, bool?secondary_uncertainty=null)
Obsolete. tail_metrics(IEnumerable<Double>,MetricsOptions)Returns the tail metrics of this view for a...
A probability range used to dictate the set of ordered trial losses in a loss distribution that shoul...
Represents the Analysis of a Portfolio
A pass-through to the ylt endpoint for configuring and downloading a per-trial simulation result from...
Base interface for all reference entities.
Definition: IReference.cs:7
Optional parameters which can be specified for co-metrics requests.
Base class used by all types and resources.
Definition: APIType.cs:7
The structure returned when requesting Co-Metrics for a view.
BackAllocations back_allocations(string source_id)
Returns a URL to the YELT of this view back-allocated to some component loss source.
The structure returned when requesting Exceedance Probability for a view.
RequestParameters AddQueryParameter(string name, string value)
Adds the specified name/value pair as a new request parameter with the type ParameterType.QueryString if the value is not null.
Optional parameters which can be specified for all metrics requests.
override RequestParameters GetParameters()
Get the REST request parameters corresponding to this configuration.
Attribute used to define the default value assigned to the target_currency property by the server whe...
TailMetrics tail_metrics(double probability, string filter=null, Perspective perspective=null, string currency=null, AggregationMethod?aggregation_method=null, bool?secondary_uncertainty=null)
Obsolete. tail_metrics(Double,MetricsOptions)Returns the tail metrics of this view for a given probab...