4. Technische Beschrijving

Technische Beschrijving

Dit gedeelte van de wiki beschrijft hoe de applicatie werkt op technisch niveau. Stukjes code zullen worden bekeken en de algemene flow van de applicatie zal worden uitgelegd. Daarnaast wordt er ook kort stilgestaan bij de inhoud van de verschillende mappen.

Applicatie Ontwerp

Mappenstructuur

Het project is verdeeld over verschillende mappen, ieder met een eigen doel. Dit hoofdstuk beschrijft de verschillende mappen van het project met het doel dat ze hebben. Het is bedoeld als algemene wijzer voor de indeling van het project en de functie van de verschillende onderdelen.

Mappen

• De map data wordt gebruikt voor het bewaren van data. Hier wordt de database opgeslagen, inclusief de scripts om de database aan te maken en te updaten. De originele Excel bestanden van die data wordt ook meegeleverd. Voor meer informatie over deze map, zie de handleiding over het aanmaken en updaten van de database.
• De map database_interfaces bevat de interfaces waarmee de applicatie communiceert met de database. De interfaces hebben een algemene abstracte interface die gebruikt kan worden om verschillende soorten data uit de database te halen, bijvoorbeeld de ScenarioDatabaseInterface.
• De map data_object wordt gebruikt om classes op te slaan voor data objecten.
• De map documentation bevat de originele documentatie in Word-formaat.
• De map excel_interfaces is vergelijkbaar met de map database_interfaces, alleen dan voor communicatie met Excel bestanden.
• De map helpers bevat hulp classes die gebruikt worden om bepaalde doelen te bereiken. Deze worden bijvoorbeeld gebruikt voor het maken van een interface tussen de applicatie en zijn blibliotheken. Zo is er een GraphHelper bedoelt als brug tussen de applicatie en matplotlib.
• De map input bevat verschillende Excel bestanden. Dit zijn voorbeelden voor input, testbestanden en bestanden die mogelijk tot foutmeldingen leiden.
• De map output bevat voorbeelden van mogelijke output.
• De map request_examples bevat json bestanden die gebruikt kunnen worden voor het testen van de applicatie. Het zijn voorbeelden voor requests naar de applicatie.
• De map templates wordt gebruikt door de template-engine van Flask voor het produceren van een antwoord.
• De map validation_schemas wordt gebruikt voor het huisvesten van request validatie.

Bestanden

Naast de mappen zijn er ook nog een aantal bestanden van belang voor het project. De root bevat veel bestanden, daarom is handig om er even overheen te gaan:

• app.py is het begin van de applicatie
• Documentatie_ZE_kompas.html is de documentatie pagina van de applicatie
• exceptions.py zijn eigen foutmeldingen
• kompas.yml het omgevingsbestand voor Anaconda
• Logger.py de class die helpt met logs
• PANTEIA_TCO_model.xlsm het excel bestand dat wordt gebruikt voor alle berekeningen
• request_functions.py het bestand waar alle functies staan die direct gebruikt worden door app.py
• requirements.txt de verzameling plug-ins voor pip
• TCOModel.py de class die alle berekeningen overziet

Applicatie Flow

De flow beschrijft de external-route van de applicatie

Parameters

Vanaf het moment dat de applicatie wordt uitgevoerd worden alle aanvragen opgevangen door Flask in app.py. Eerst worden alle veriabelen uit de parameters gehaald, dit gebeurd door middel van functies gedefiniëerd in request_functions.py.

company = helper.get_company_from_parameters(request)
comparing = helper.get_comparing_from_parameters(request)
selected_scenarios = helper.get_scenarios_from_parameters(request)
selected_strategies = helper.get_strategies_from_parameters(request)
output = helper.get_output_from_parameters(request)

Voertuigen

De volgende stap is het ophalen van de voertuigen die zijn meegestuurd met de aanvraag. Vanuit app.py wordt de aanvraag overgedragen aan de functie voor het verkrijgen van de vloot informatie in request_functions.py. Die zal stap voor stap [1] het Excel bestand aanmaken van de Base64 string uit de aanvraag; [2] dit bestand wordt doorgegeven aan de FleetInterface uit FleetInterface.py in de excel_interfaces map. Dit bestand wordt na het verkrijgen van de data weer verwijderd.

# Log the beginnen of the operation
Logger.warning("Retrieving fleet data from provided Excel file")

# Get the JSON data from the body and the check the validation schema
body = get_body(request)
validate_body_with_schema("external_excel", body)

# Decode the base64 data into a temporary file and construct the fleet data
fleet_file = base64_decode_file(body["fleet_data"]).name
fleet_data = FleetInterface(company, fleet_file)

# Get the fleet data and errors
fleet = fleet_data.fleet
errors = fleet_data.errors

# Destroy the temporary file
del fleet_data
os.remove(fleet_file)

# Return the data
return (fleet, errors)

Scenarios

De applicatie vergelijkt verschillende scenarios om tot het beste advies te komen. Deze scenarios staan opgeslagen in de database. De communicatie met de database verloopt via ScenarioDatabaseInterface.py. Deze wordt aangeroepen vanuit de aanvraag in app.py via request_functions.py. De data wordt opgevraagd uit de database en omgezet naar een bruikbaar format.

# Loop through the scenario data and add it to the scenario data
for sheet_name in ScenariosInterface.valid_scenario_sheet_names:
    # Prepare scenario data
    scenario_type, vehicle_type = sheet_name.split(" ")
    years = {x['scenario'].year: x['scenario'] for x in scenarios if x['sheet_name'] == sheet_name}
    scenario = Scenario(sheet_name, scenario_type, vehicle_type, years)

    # Add the scenario to the scenario data
    if scenario_type in scenario_data.keys():
        scenario_data[scenario_type][vehicle_type] = scenario
    else:
        scenario_data[scenario_type] = { vehicle_type: scenario }

Data verwerking

De data wordt vervolgens verwerkt en doorgeven voor om te worden gepresenteerd in het aangevraagde formaat. Beide functies lopen via request_functions.py. Tijdens het verwerken van de data wordt de class uit TCOModel.py gebruikt om de berekeningen te maken. De Flask rendering engine zorgt er vervolgens voor dat het juiste formaat output wordt gepresenteerd aan de eind-gebruiker.

# Process data
Logger.warning("Predicting")
data = helper.process_data(
     fleet,
     scenarios,
     valid_scenario_names,
     output,
     comparing,
     selected_scenarios,
     selected_strategies
)

# Return output
Logger.warning("Outputting")
output_format = request.args.get("output_format")
return helper.format_output(output_format, data, fleet_errors)