Add location types reference (#73)

* Add location types JSON

* First comparison made possible

* Update extract_location_types.ipynb

* Add the test for the french template

* Update extract_location_types.ipynb

* Clean out bullshit from co-pilot

* lint it

* Add the xlsx reference for simpler work

* Update extract_location_types.ipynb

* Small updates on documentation

* Clean up

* Update test_location_types.py

README.md

@@ -16,4 +16,4 @@ In addition to the Excel template named "Project_Location_Data_Template," we pro
 The technical specifications as well as the sample Terms of Referencecan for collecting the data can be found in this repository. The information in the table of the page "Technical Notes" is also given as comments in the Excel template if you click on the cells. Most importantly make sure to use WGS 84 as the coordinate reference system when submitting locations in lat/long format. You might also collect proper geo-data in formats such as kml oder geojson (oder shapefile). If you send this information together with the template it might help to verify the coordinates in the template. In addition it will be very usefull in cases where a project location is better represented by line or polygon geometries (e.g. protected areas or transimission lines). 
 
 ## More information on remote management methods
-This open data model is part of KfW's RMMV Digital Public Content Initiative. You can find more information on RMMV [here](https://www.kfw-entwicklungsbank.de/Service/Publications-Videos/Publications-by-topic/Digitalisation/RMMV-Guidebook/). 
+This open data model is part of KfW's RMMV Digital Public Content Initiative. You can find more information on RMMV [here](https://www.kfw-entwicklungsbank.de/Service/Publications-Videos/Publications-by-topic/Digitalisation/RMMV-Guidebook/). 

docs/location_type.md

@@ -0,0 +1,93 @@
+# Notes on location types
+
+In this section, we will detail our approach to the location types that are available in the *open project location model*. The current reference of location types can be found [here](https://github.com/openkfw/open-geodata-model/blob/main/references/kfw_location_type.xlsx). So this section is most relevant to developers and maintainers of the open project location model. If you would like to know how to select the right location type in the excel template, please see directly [here](technical_notes.md#what-is-a-location-type).
+
+## What is a Location Type?
+
+This template closely follows the International Aid Transparency Initiative (IATI) standard, but we have created additional location types to cover all Financial Cooperation project types. This enables the aggregation of information among multiple location types. Our new location type list includes the IATI location types that are useful for International Development, as well as additional location types for all sectors that were missing in the existing IATI list. We have created 197 new project location types, including "immaterial" ones like Capacity Development/Training or Voucher Schemes, that cannot be plotted according to any physical feature on a map but can be defined by the area covered by them.
+
+### IATI Location Types
+
+We have based our work on the the IATI reference for [location types](https://iatistandard.org/en/iati-standard/203/codelists/locationtype/). Within this standard each location has four attributes:
+
+- `code`: The unique identifier for the location type.
+- `name`: The name of the location type.
+- `description`: A description of the location type.
+- `category`: The category of the location type. It is equivalent to the US NGAs `feature class`.
+
+This reference is so useful that we decided to use it as the baseline for the location types that are available within the open project location model.
+
+### KfW Location Types
+
+We have extended the IATI location types to better meet the needs of FC projects. We will specify it in detail below but the main requirements were:
+
+- *Better match for FC locations.* Therefore we added numerous location types that are not available in the IATI standard and remove location types that are not relevant for FC projects.
+- *Simple translation.* We have started to provide the template itself in several languages and we want to make sure that the location types are easy to translate and to keep consistent.
+- *More details.* We found that it is important to describe the location types in more detail to make sure that the users understand the differences between them. Therefore we added new attributes to the location types.
+
+### Location Type Attributes
+
+In this section we summarize the availble attributes for the KfW location types.
+
+| **Name** |  **Mandatory**  | **Description** | **Part of IATI** |
+| --:| ---------:| ----------------:|----:|
+| code | Yes | The unique identifier for the location type. | Yes |
+| name | Yes | The name of the location type in english language. | Yes |
+| character | Yes | Describes if the location type describes a physical location, then it is to be set to `physical`, or an activity, then it is to be set to `immaterial`. | No |
+| geometry | Yes | Describes the allowed geometry of the location type. Can be only one of the three types `point`, `line` or `polygon`.  | No |
+| description | No | A description of the location type in english language. | Yes |
+| category | No | The category of the location type. It is equivalent to the US NGAs `feature class`. | Yes |
+| description_fr | No | The description of the location type in french language. | No |
+| subsector | No | The name of the subsector with which the location type is associated. Should be formulated in english.| No |
+| name_de | No | The name of the location type in german language. | No |
+| name_fr | No | The name of the location type in french language. | No |
+
+### On the link of location types and the templates
+
+We can use the location type reference to ensure consistency between different implementations of the *open project location model* and different translations. Currently, there are two implementations of the location model, namely the french and the english translation. In both cases the location types can be found in the worksheet `Location Types IATI and New`. With the reference, we can now ensure that both templates implement all the location types by checking that all the codes are within the code list of the template. 
+
+```mermaid
+
+classDiagram
+    class LocationTypes{
+        +String code
+        +String name
+        +String character
+        +String geometry
+        +String description
+        +String category
+        +String description_fr
+        +String subsector
+        +String name_de
+        +String name_fr
+    }
+
+    class EnglishTemplateLocationTypes{
+        +String subsector
+        +String code
+        +String name
+        +String character
+        +String geometry
+        +String description
+        +String category
+    }
+    class FrenchTemplateLocationTypes{
+        +String code        
+        +String name_fr
+        +String character
+        +String geometry
+    }
+    LocationTypes --|> EnglishTemplateLocationTypes
+    LocationTypes --|> FrenchTemplateLocationTypes
+```
+
+
+
+This can be automatically tested via the `test_location_types.py` script, which is contained in the tests `folder`.
+
+### Possible outlooks
+
+The following section, is meant as summary for possible new steps in the development of the location types. So it is really an invitation to discuss and to provide feedback but certain to evolve in the future.
+
+- We have currently not solved the issue of consistent translations for certain attributes as as `subsector`, `character` and `geometry`. They have only a limited number of choices. So my preferred option would be to create references with the translations for these attributes.
+- Schemas. It would be nice to have the definitions from above in a schema that can be used to validate the location types.

docs/technical_notes.md

@@ -50,10 +50,11 @@ In the case of security risks (e.g., conflict zones), we strongly recommend only
 </figure>
 
 ## What is a Location Type?
-
-This template closely follows the International Aid Transparency Initiative (IATI) standard, but we have created additional location types to cover all Financial Cooperation project types. This enables the aggregation of information among multiple location types. If you cannot find a specific location type, please use the most similar location type, such as "well" for an "extraction well". You can then add additional information on the location type, such as "extraction well", under "additional location types", if necessary.
 
-Our new location type list includes the IATI location types that are useful for International Development, as well as additional location types for all sectors that were missing in the existing IATI list. We have created 197 new project location types, including "immaterial" ones like Capacity Development/Training or Voucher Schemes, that cannot be plotted according to any physical feature on a map but can be defined by the area covered by them. Therefore, we have also adapted the definition of "location type" as "project output- or intervention-related type of physical location or immaterial output- or intervention area". Please refer to the list of Location Types in the Excel Template for more information. Definitions for the original IATI-based location types can be found [here](https://iatistandard.org/en/iati-standard/203/codelists/locationtype/). A comprehensive list of all location types can be found in the Excel Template.
+This template closely follows the International Aid Transparency Initiative (IATI) standard, but we have created additional location types to cover all Financial Cooperation project types. This enables the aggregation of information among multiple location types. If you cannot find a specific location type, please use the most similar location type, such as "well" for an "extraction well". You can then add additional information on the location type, such as "extraction well", under "additional location types", if necessary. For more detailled technical information about the location types, please refer to the [location type reference](location_type.md).
+
+Our new location type list includes the IATI location types that are useful for International Development, as well as additional location types for all sectors that were missing in the existing IATI list. We have created 197 new project location types, including "immaterial" ones like Capacity Development/Training or Voucher Schemes, that cannot be plotted according to any physical feature on a map but can be defined by the area covered by them. Therefore, we have also adapted the definition of "location type" as "project output- or intervention-related type of physical location or immaterial output- or intervention area". Please refer to the list of Location Types in the Excel Template for more information.
+
 After preselecting the KC Theme/Sub-Sector, please choose the most appropriate location type from the table sheet "Location Types". If there is no suitable option, please select "other physical" or "other immaterial" and fill out the next column "Alternative Location Type". If you need or want to mention two different location types (e.g., school and capacity development) at the same GPS coordinate, you may create two separate rows for these location types with different activity descriptions and DAC/CRS codes at the same GPS coordinates.
 **Please note that the preselection column "KC Theme/Sub-Sector" is only intended to help you quickly find the correct location type name.** It will not be saved in the system and does not replace the DAC5 Purpose Classification/CRS-Code assignment below, which effectively assigns the correct subsector to each location.
 
@@ -81,7 +82,7 @@ Table 1: The Project Location Model for Development Cooperation
 | E.| Publishing restrictions due to security reasons | Select Text (yes/no) | Yes | Indicates if this information is collected in fragile regions (e.g., areas of severe civil conflict or war) and should therefore be omitted from publicly available reports. |
 | F.| Date of data collection or latest update   | Date YYYY-MM-DD (Date format - English/US)  |No| Date of data collection or latest update (if date of data collection is unknown). In case only the year is available please choose the 1st of january e.g. 2022-01-01 |
 | G.| Project-specific location identifier  | Text     |No| If the location or activity has a project-specific identifier (e.g., a location code in the MIS of the source agency, e.g., Project Executing Agency (PEA)) or an identifier in a public database like GADM, it can be entered here.|
-| H.| Location name |Text  |Yes| Short name of the project site ideally containing a summary of the main project activity and the location name (max. 40 characters or digits) |
+| H.| Location name |Text  |Yes| Short name of the project site ideally containing a summary of the main project activity and the location name. Must be from the list of  location names in the location type sheet. |
 | I.| Location activity status  | Select Text    | No | The location activity status according to the IATI standard. If you are unaware of the current status please choose "NA". |
 | J.| Planned or actual start date of activity at the location   | Date  YYYY-MM-DD (Date format - English/US)  | Yes | Approximate planned or actual start date of implementation of activities on the ground. This can be, for example, the date when construction work is planned to begin. If there is no information available, please enter 2100-01-01. Ideally, the start of project implementation is defined in the  [project location data collection ToR](overview_templates_tor.md). |
 | K.| Planned or actual end date of activity at the location   | Date  YYYY-MM-DD (Date format - English/US)  | Yes | Approximate planned or actual end date of activities on the ground. This can be, for example, the date when the project is planned to cease implementation activities. If there is no information available, please enter 2100-01-01.|