algorithm.json
- Rodolfo Melia
- Shrab Sahota (Unlicensed)
File Structure - algorithm.json
The algorithm file is the core component of the C4C engine. It drives the logic of the questions asked to a user, with the aim of outputting a set of recommended family planning methods in accordance with the answers given by the user. The file is written using JSON notation. To learn more about the basic notation used in JSON, click here.
C4C Algorithm contains three main elements: questions, answers (options), and method recommendations. The following example illustrates how the file is constructed:
"factor1:[Effectiveness]": {
"factor2:[EasyToStop]": {
"factors2vs1:[+]": {
"factor3:[Privacy]": ["EC", "Injectables", "IUD"],
"factor3:[EasyToForget]": {
"factors3vs12:[+]": ["Implant", "IUD"],
"factors3vs12:[=]": ["Implant", "IUD"],
"factors3vs12:[-]": ["EC", "COP", "IUD"]
},
There are 5 questions asked in this part of the flow: factor1, factor2, factors2vs1, factor, and factor3vs12. Each object has an option/response in between the square brackets indicating what would be the next question due to a specific response.
In the example, after answering Effectiveness to factor1, EasyToStop to factor2, and indicating that the factor2 is more important than factor1, the bot has two paths depending on the user's answer to factor3 (privacy or easy to forget).
If the user indicates Privacy to a factor3, then the recommended methods would be EC, Injectables, and IUD but if the user indicates that factor3 is EasyToForget, then the bot will have to ask another question to the user to determine which of the factors has more weight and depending on the answer of this fifth question, the bot will suggest other different Methods.
Representing this snip of code in a flowchart will look as follows:
As seen in the example, the final purpose of the algorithm is to give the user a list of recommended methods according to the previous answers.
To be able to add a new method to the algorithm, such a method should be defined in the questions.json file. If the method is not in the options of the corresponding question, then it won't work.
Additionally, a method will need associated translations in PO Editor.
The final output of recommended family planning methods is contained in an array, on which each method is separated by commas and written between double quotes.
The final list of contraceptive methods could be further refined by the elimination of some of the recommendations, based on the exception file - see C4C: exceptions.json to know more about this feature.
For all cases, the final response will be checked, so it only shows a maximum of three family planning methods.
Example:
"factor3:[Privacy]": ["EC", "Injectables", "IUD"]
Multilingual
The output returned to the user will be in the corresponding language, and the value will be retrieved from from the PO editor. Below sample text in english.
Keyword (PO editor term) | Sample EN full text |
|---|---|
Sterilization | Sterilization |
IUD | IUD |
IUS | Hormonal IUD (IUS) |
Implant | Implant |
Injectables | Injectables |
POP | Progesterone Pills |
COP | Combined Pills |
EC | Emergency Contraceptive Pills (ECP) |
Condoms | Condoms |
Cyclebeads | Cyclebeads |
Making changes: simple edits
How to add an existing method
To add an existing method to an array, add a comma next to the last method and write the method within double quotes. Verify that no commas are after the last method and that the whole array is between square brackets.
Example:
BEFORE
"factor3:[Privacy]": ["EC", "Injectables", "IUD"]Only methods already defined in the questions.json file should be added.
How to remove an existing method
To remove a method erase the double-quoted string. Verify that all remaining methods are separated by a comma and that the whole array is between square brackets.
Example:
Method's order
The recommended methods will be returned in the order that they are stored. To change the order just verify the methods are separated by commas, and that the array is kept within square brackets. The method can be excluded later on on the exception file. The final response will always contain a maximum of 3 contraceptive methods.
Example:
Other changes
Add a method that doesn't exist in the question.json file
Before a method can be referred in the algorithm, it needs to be added to the question.json file, as well as a translatable term. Please request the C4C technical administrator to add the new method.
Add/remove a question
Adding or removing questions can damage the logic of the algorithm. Please contact the C4C technical administrator if you need to add or remove a question.
Change the order of the questions
Changing the order of the questions can damage the logic of the algorithm. Contact the C4C technical administrator to request the change.