refactor flatfile columns

Author: rizac

egsim/api/forms/__init__.py

@@ -13,7 +13,7 @@
 
 from egsim.api import models
 from egsim.smtk import (validate_inputs, harmonize_input_gsims, harmonize_input_imts)
-from egsim.smtk.flatfile import FlatfileMetadata
+from egsim.smtk.flatfile import column_help
 from egsim.smtk.registry import gsim_info
 from egsim.smtk.validation import IncompatibleModelImtError, ImtError, ModelError
 
@@ -452,7 +452,7 @@ def output(self) -> dict:
         for gmm_name, gmm in self.cleaned_data['gsim'].items():
             doc, imts, gm_props, sa_limits = gsim_info(gmm)
             # ground motion properties:
-            gm_props = {p: FlatfileMetadata.get_help(p) for p in gm_props}
+            gm_props = {p: column_help(p) for p in gm_props}
             # remove unnecessary flatfile-related info (everything after 1st paragraph)
             # and also jsonify the string (replace " with ''):
             gm_props = {

egsim/api/forms/flatfile.py

@@ -10,10 +10,12 @@
 
 from egsim.smtk import (ground_motion_properties_required_by,
                         intensity_measures_defined_for, get_sa_limits)
-from egsim.smtk.flatfile import (read_flatfile, get_dtype_of, FlatfileMetadata,
+from egsim.smtk.flatfile import (read_flatfile, get_dtype_of, column_exists, column_type,
+                                 column_categorical_dtype, column_aliases,
+                                 column_dtype, column_help,
                                  query as flatfile_query, EVENT_ID_COLUMN_NAME,
                                  FlatfileError, FlatfileQueryError,
-                                 IncompatibleColumnError)
+                                 IncompatibleColumnError, column_names)
 from egsim.api import models
 from egsim.api.forms import EgsimBaseForm, APIForm, GsimForm, split_pars
 
@@ -169,7 +171,7 @@ class FlatfileMetadataInfoForm(GsimForm, APIForm):
 
     def clean(self):
         cleaned_data = super().clean()
-        unique_imts = FlatfileMetadata.get_intensity_measures()
+        unique_imts = column_names(type='intensity')
 
         for m_name, model in cleaned_data['gsim'].items():
             imts = intensity_measures_defined_for(model)
@@ -210,7 +212,7 @@ def output(self) -> dict:
 
         required_columns = (ground_motion_properties_required_by(*gsims) |
                             {EVENT_ID_COLUMN_NAME})  # <- event id always required
-        ff_columns = {FlatfileMetadata.get_aliases(c)[0] for c in required_columns}
+        ff_columns = {column_aliases(c)[0] for c in required_columns}
 
         imts = cleaned_data['imt']
 
@@ -244,16 +246,16 @@ def get_hr_flatfile_column_meta(name: str, values: Optional[pd.Series] = None) -
     c_dtype = None
     c_categories = []
 
-    if FlatfileMetadata.has(name):
-        c_dtype = FlatfileMetadata.get_dtype(name)
-        cat_dtype = FlatfileMetadata.get_categorical_dtype(name)
+    if column_exists(name):
+        c_dtype = column_dtype(name)
+        cat_dtype = column_categorical_dtype(name)
         if cat_dtype is not None:
             # c_categories is a pandas CategoricalStype. So:
             c_dtype = get_dtype_of(cat_dtype.categories)
             c_categories = cat_dtype.categories.tolist()
-        c_type = getattr(FlatfileMetadata.get_type(name), 'value', "")
-        c_help = FlatfileMetadata.get_help(name) or ""
-        c_aliases = FlatfileMetadata.get_aliases(name)
+        c_type = getattr(column_type(name), 'value', "")
+        c_help = column_help(name) or ""
+        c_aliases = column_aliases(name)
         if len(c_aliases) > 1:
             c_aliases = [n for n in c_aliases if n != name]
             c_aliases = (f"Alternative valid name{'s' if len(c_aliases) != 1 else ''}: "

egsim/api/forms/scenarios.py

@@ -10,7 +10,7 @@
 from django.forms.fields import BooleanField, FloatField, ChoiceField, Field
 
 from egsim.api.forms import APIForm, GsimImtForm
-from egsim.smtk import get_scenarios_predictions
+from egsim.smtk import get_ground_motion_from_scenarios
 from egsim.smtk.scenarios import RuptureProperties, SiteProperties, Clabel
 
 
@@ -216,13 +216,13 @@ def output(self) -> pd.DataFrame:
                                  self.site_fieldnames
                                  if p in cleaned_data})
         header_sep = None if cleaned_data.get('multi_header') else Clabel.sep
-        return get_scenarios_predictions(cleaned_data['gsim'],
-                                         cleaned_data['imt'],
-                                         cleaned_data['magnitude'],
-                                         cleaned_data['distance'],
-                                         rupture_properties=rup,
-                                         site_properties=site,
-                                         header_sep=header_sep)
+        return get_ground_motion_from_scenarios(cleaned_data['gsim'],
+                                                cleaned_data['imt'],
+                                                cleaned_data['magnitude'],
+                                                cleaned_data['distance'],
+                                                rupture_properties=rup,
+                                                site_properties=site,
+                                                header_sep=header_sep)
 
 
 PredictionsForm.rupture_fieldnames = tuple(sorted(

egsim/api/management/commands/egsim-init.py

@@ -8,7 +8,7 @@
 from django.core.management import BaseCommand, CommandError
 from egsim.smtk import (registered_gsims, gsim, intensity_measures_defined_for,
                         ground_motion_properties_required_by, get_sa_limits)
-from egsim.smtk.flatfile import FlatfileMetadata
+from egsim.smtk.flatfile import column_exists
 from ... import models
 from django.conf import settings
 
@@ -108,7 +108,7 @@ def write_model(self, name, cls):
                 self.stdout.write(f"  {prefix} {name}. No ground motion property "
                                   f"defined")
                 return False
-            invalid = sorted(c for c in gmp if not FlatfileMetadata.has(c))
+            invalid = sorted(c for c in gmp if not column_exists(c))
             if invalid:
                 self.stdout.write(f"  {prefix} {name}. Unregistered "
                                   f"ground motion properties: {invalid}")

egsim/api/views.py

@@ -40,24 +40,8 @@ class MimeType:  # noqa
 
 class EgsimView(View):
     """Base View class for serving eGSIM HttpResponse. All views should inherits from 
-    this class, implementing the abstract-like method `response`
-    
-    Example
-    =======
-    
-    1. Implementation (note: any exception will be caught and returned as 500 
-        HttpResponse, see `handle_exception`)
-    ```
-    class MyEgsimView(EgsimView):
-    
-        def response(self, request: HttpRequest, data: dict, files: Optional[dict] = None) -> HttpResponseBase:
-            content = ... # bytes or string sequence (serialized from a Python object)
-            return HttpResponse(content, content_type=MimeType.csv, ...)
-            # or, if content is a JSON dict:
-            return JsonResponse(content)
-    ```
-    
-    2. URL mapping: given an endpoint (URL string or regex pattern), in `urls.py`:
+    this class, implementing the abstract-like method `response` (**see docstring therein 
+    for details**). After that, you can map this view to a given URL as usual (in `urls.py`):
     ```
     urlpatterns = [
         ...
@@ -107,7 +91,10 @@ def response(self,
         need to be returned in try except clauses, as usual:
         ```
         try:
-            ... return response, e.g. JsonResponse, HttpResponse
+            content = ... # bytes or string sequence (serialized from a Python object)
+            return HttpResponse(content, content_type=MimeType.csv, ...)
+            # or, if content is a JSON dict:
+            return JsonResponse(content)
         except ValueError as exc:
             return self.error_response(exc, status=400)
         ```
@@ -184,17 +171,17 @@ def response(self,
 
 class APIFormView(EgsimView):
     """:class:`EgsimView` subclass serving :class:`ApiForm.output()` objects and 
-    expecting a 'format' request parameter (default if missing: 'json', see `MimeType`
-    class attributes) dictating the response type. Form validation errors will be 
-    returned as 400 HttpResponse with the form error string as reponse message.
+    expecting a 'format' request parameter (any attribute of :class:`MimeType`)
+    dictating the response type. Form validation errors will be 
+    returned as 400 HttpResponse, any uncaught exception as 500 HttpResponse.
     
     Usage
     =====
     
     Given an `APiForm` subclass named `MyApiForm`:
     
     1. If this view is supposed to return JSON data only, then `MyApiForm.output()` 
-    must also return a JSON serializable dict. After that, you only need to
+    must also return a JSON serializable dict. If this is the casse, you only need to
     implement a new endpoint in `urls.py`:
     
     ```
@@ -205,10 +192,11 @@ class attributes) dictating the response type. Form validation errors will be
     ]
     ```
 
-    2. If this view is suppoosed to return several data formats, then 
+    2. If this view is supposed to return several data formats, then 
     `MyApiForm.output()` can be any Python object, but you must serialize it here
-    depending on the requested format. For instance, if you want to support users 
-    request format to be 'hdf', this class expets the relative method `response_hdf`:
+    depending on the requested format (including overriding the existing reponse_json,
+    if needed). For instance, if you want to serve HDF data, you must implement
+    the method `response_hdf`:
     
     ```
     class MyApiFormView(APIFormView):

egsim/smtk/__init__.py

@@ -1,5 +1,5 @@
 """Root module for the strong motion modeller toolkit (smtk) package of eGSIM"""
-from .scenarios import get_scenarios_predictions
+from .scenarios import get_ground_motion_from_scenarios
 from .residuals import get_residuals
 from .ranking import get_measures_of_fit
 from .flatfile import read_flatfile, FlatfileError