ILLGeo

Defines the public contract for the LLGeo class, exposing methods for importing, exporting, translating, and querying the geobase data that underpins geographic dropdowns and spatial analyses in the linelist. Consumers use this interface to manage the four-level administrative hierarchy (admin1 through admin4) plus health facility data, translate column headers between raw and display names, maintain historic entries, and synchronise geo labels across linelist worksheets and the dictionary. The geobase is stored on a dedicated worksheet containing ListObjects for each admin level (T_ADM1 through T_ADM4), health facilities (T_HF), translation names (T_NAMES), historic entries (T_HISTOGEO, T_HISTOHF), and metadata (T_METADATA). Three enums control scope selection. Admin-only scope selects one of the four administrative levels without including health facilities. Used by GeoLevel when geoType is GeoScopeAdmin. Extended scope that includes both admin levels and health facility. Used for operations that need to address all five geographic tiers.

Properties

GeoLevel #

List of values at a given admin level

Signature:

Public Property Get GeoLevel(ByVal adminLevel As Byte, _
                             Optional ByVal geoType As Byte = GeoScopeAdmin, _
                             Optional adminNames As Variant = vbNullString) As BetterArray

Returns a BetterArray of unique geographic names at the requested admin level, optionally filtered by parent admin selections. For admin1 the full unfiltered list is returned. For admin2 through admin4, the caller supplies parent selections so the result cascades hierarchically. The geoType parameter switches between the admin hierarchy and the health facility table.

Parameters:

  • adminLevel: Byte. Admin level index (0-3 for admin1-admin4).
  • geoType: Optional Byte. GeoScope value: GeoScopeAdmin (0) or GeoScopeHF (1). Defaults to GeoScopeAdmin.
  • adminNames: Optional Variant. Parent admin selections for filtering: String for level 2, BetterArray for levels 3-4. Defaults to vbNullString.

Returns: BetterArray. Unique values at the requested level, or an empty array when the geobase is empty.

GeoNames #

Translated display name for a raw admin column name

Signature:

Public Property Get GeoNames(ByVal admname As String) As String: End Property

Converts a raw admin column name (such as "adm1_name", "hf_name", or "geobase") to its translated display name as configured in the geobase named ranges. Returns the raw name unchanged when no translation mapping exists.

Parameters:

  • admname: String. Raw column name to translate.

Returns: String. Translated display name, or the raw name if no translation exists.

HasNoData #

Whether the geobase has no imported data

Signature:

Public Property Get HasNoData() As Boolean: End Property

Returns True when the geobase update flag reads "empty", indicating that no geo data has been imported yet or that all data has been cleared.

Returns: Boolean. True when the geobase is empty.

Translation

Translate #

Translate or revert geobase table headers

Signature:

Public Sub Translate(Optional ByVal rawNames As Boolean = False): End Sub

Applies or reverts translated display names on all geobase table headers (admin1 through admin4, health facility). When rawNames is False, headers are translated to display names. When True, headers are reverted to raw column names. Skips the operation when the geobase is already in the requested translation state.

Parameters:

  • rawNames: Optional Boolean. True to revert to raw names, False to apply translated names. Defaults to False.
Import / Export

Import #

Import geobase data from an external workbook

Signature:

Public Sub Import(ByVal fromWkb As Workbook, _
                  Optional ByVal histoOnly As Boolean = False)

Imports geographic data from the supplied workbook. Each worksheet whose name matches a known table name (ADM1 through ADM4, HF, NAMES, HISTOGEO, HISTOHF, METADATA) is imported column by column into the corresponding ListObject. When histoOnly is True, only historic tables are refreshed and the main admin/HF data is left intact.

Parameters:

  • fromWkb: Workbook. Source workbook containing geo data sheets.
  • histoOnly: Optional Boolean. True to import only historic data. Defaults to False.

ExportToFile #

Export geobase tables to a workbook as flat data

Signature:

Public Sub ExportToFile(ByVal outputWkb As Workbook, _
                        Optional ByVal onlyHistory As Boolean = False)

Exports geobase tables to the target workbook with one sheet per table and a Metadata sheet. Headers are reverted to raw names before export and restored to translated form afterwards. HiddenNames entries are exported to the Metadata sheet for round-trip import support. When onlyHistory is True, only the HISTOGEO and HISTOHF tables are exported.

Parameters:

  • outputWkb: Workbook. Target workbook to receive exported sheets.
  • onlyHistory: Optional Boolean. True to export only historic tables. Defaults to False.

ExportToWkb #

Export the geobase worksheet structure to a workbook

Signature:

Public Sub ExportToWkb(ByVal Wkb As Workbook, _
                       Optional ByVal llName As String = vbNullString, _
                       Optional ByVal setupPath As String = vbNullString)

Copies the entire geobase worksheet to the target workbook, preserving ListObjects, named ranges, formulas, pcode references, concat references, and metadata. Creates a hidden Metadata sheet with creation metadata. Raises an error when sheets with conflicting names already exist.

Parameters:

  • Wkb: Workbook. Target workbook.
  • llName: Optional String. Linelist name for metadata. Defaults to vbNullString.
  • setupPath: Optional String. Setup file path for metadata. Defaults to vbNullString.
Clear

Clear #

Clear all geobase data

Signature:

Public Sub Clear(): End Sub

Removes all data from every ListObject on the geobase worksheet except T_LevelNames and T_CONCAT, and sets the update flag to "empty". Resets the translation name cache.

ClearHistoric #

Clear historic entries

Signature:

Public Sub ClearHistoric(Optional ByVal scope As Byte = 3): End Sub

Clears the data body of historic ListObjects. The scope parameter controls which tables are cleared: 0 for geo only, 1 for HF only, 3 for both.

Parameters:

  • scope: Optional Byte. 0 = geo only, 1 = HF only, 3 = both. Defaults to 3.

UpdateHistoric #

Add a new entry to the historic data

Signature:

Public Sub UpdateHistoric(ByVal newValue As String, _
                          Optional ByVal scope As Byte = 0)

Appends a value to the appropriate historic ListObject (HISTOGEO or HISTOHF), resizes the table to include the new row, removes duplicates, and sorts alphabetically.

Parameters:

  • newValue: String. The value to add.
  • scope: Optional Byte. 0 = geo historic, 1 = HF historic. Defaults to 0.
Update

Update #

Update linelist geo column headers and dropdowns

Signature:

Public Sub Update(ByVal pass As IPasswords): End Sub

Iterates all HList worksheets, finds columns controlled by geo1 through geo4 and hf, and updates their header labels with translated geo names. Also refreshes the admin1 dropdown list on the dropdown_lists__ sheet.

Parameters:

  • pass: IPasswords. Password manager for sheet protection and unprotection.

UpdateDict #

Update dictionary labels for geo-related variables

Signature:

Public Sub UpdateDict(ByVal dict As ILLdictionary): End Sub

Scans the dictionary control column for geo1 through geo4 and hf entries and overwrites the corresponding main label cells with translated geo display names.

Parameters:

  • dict: ILLdictionary. The linelist dictionary.

UpdateShowHide #

Update show/hide tables with translated geo labels

Signature:

Public Sub UpdateShowHide(ByVal sh As Worksheet, ByVal dict As ILLdictionary): End Sub

Iterates all ListObjects on the show/hide worksheet, finds variables controlled by geo1 through geo4 and hf, and updates their main label cells to include the subsection prefix and the translated geo display name.

Parameters:

  • sh: Worksheet. The show/hide worksheet.
  • dict: ILLdictionary. The linelist dictionary.
Admin Code Resolution

AdminCode #

Resolve the admin code from a translated display name

Signature:

Public Function AdminCode(ByVal selectedAdmin As String) As String: End Function

Compares the supplied translated admin name against GeoNames for each admin level and returns the matching raw code ("adm1" through "adm4"). Falls back to "adm1" when no match is found.

Parameters:

  • selectedAdmin: String. The translated admin display name.

Returns: String. Admin code ("adm1", "adm2", "adm3", or "adm4").