Information collection

Collecting information for an entire specialty - or even an entire faculty - can be challenging. There are often dozens of study groups and teachers involved. Moreover, some information, such as the number of students enrolled in elective courses, is usually not publicly available and can only be provided by students from the corresponding study groups.

To address this, the project uses a distributed information collection approach. The required information is split by study group, making it easy to divide the work among multiple contributors. The collected data then serves as the input for the remaining stages of the survey pipeline.

Overall, the information collection process consists of two mandatory and one optional step.

Step 1. Collect Group-Level Information

The first step is to collect information about each study group. Since the project follows a distributed approach, the information is organized per study group, making it easy to divide the work among multiple contributors.

For each study group, the following information is required:

• Study group name (in Ukrainian).
• List of teachers who teach this group.

Notice: If your survey does not cover all teachers, clearly specify the inclusion criteria before starting the data collection. Contributors should know exactly which teachers should be included (for example, only teachers from a particular department, only lecturers of a specific educational program, etc.). Precise instructions at this stage help avoid missing teachers and collecting unnecessary data.

For each teacher, provide:

• Full name (in Ukrainian).
• Number of unique students from this study group taught by the teacher (students should not be counted more than once, even if the teacher teaches multiple courses).
• List of courses taught by the teacher in this group.

For each course, provide:

• Course name (in Ukrainian).

• Teacher's role. The value must be exactly one of the following:

  • Практик
  • Лектор
  • Лектор і практик

  Use Практик for all teachers who conduct practical classes, including foreign language teachers and teachers who only supervise or grade laboratory work.

• Whether the course is elective for this study group.

A JSON file describing a single study group should have the following structure:

{
    "group": "ФІ-81",
    "teachers": [
        {
            "name": "Прізвище Ім'я По-батькові",
            "courses": [
                {
                    "name": "Повна назва дисципліни",
                    "is_elective": true,
                    "role": "Практик"
                },
                {
                    "name": "Повна назва дисципліни 2",
                    "is_elective": true,
                    "role": "Лектор"
                }
            ],
            "num_students": 9
        },
        {
            "name": "Прізвище2 Ім'я2 По-батькові2",
            "courses": [
                {
                    "name": "Повна назва дисципліни 3",
                    "is_elective": false,
                    "role": "Лектор і практик"
                }
            ],
            "num_students": 23
        }
    ]
}

You may place information for multiple study groups in the same file. In this case, the top-level JSON object should simply be a list:

[
    {
        "group": "ФІ-81",
        "teachers": [
            ...
        ]
    },
    {
        "group": "ФІ-82",
        "teachers": [
            ...
        ]
    }
]

Verification

After all JSON files have been collected, manually review the data before proceeding to the next stage. While the repository validates the JSON structure, it cannot detect incorrect or inconsistent information.

The most common issues are:

• A teacher is missing from one or more study groups.
• The same teacher's name is spelled differently in different files.
• Copy-paste mistakes in course names or the is_elective field.
• Incorrect values of num_students.

Verifying these issues requires domain knowledge and, in some cases, access to information that is not publicly available. It is therefore recommended that someone familiar with the educational program performs a final review of the collected data before generating the survey forms.

Step 2. Gather Teachers' Photos

The generated visualizations include a photograph of each teacher. Since these images cannot be obtained automatically, they must be collected separately after the teacher list has been finalized in the previous step.

Once you have the complete list of teachers, the work can easily be divided among several contributors by assigning each person a subset of teachers.

All scripts in this repository expect teacher photos to satisfy the following requirements:

• Resolution: 400 × 400 pixels
• Format: PNG
• Filename: Прізвище Ім’я По-батькові.png

If this is not your first survey, consider reusing the photos collected during previous years. Keeping a shared archive of teacher photos can significantly reduce the amount of work required for future surveys.

If a teacher's photo is not available, the pipeline will still work correctly. In this case, the visualization will use a default placeholder image instead.

Teacher photos can typically be found on:

• department websites;
• faculty websites;
• previous survey publications.

Step 3 (Optional, IPT/KPI Only). Gather Links to Previous Surveys

When publishing survey results, it is often useful to include links to previous surveys for the same teacher. This allows readers to compare results over time and observe long-term trends.

This repository includes a script that can automatically extract these links from previously exported Telegram channels. The script expects a specific post format, so it is primarily intended for surveys that have already been published using this project.

The workflow is as follows:

1. Export each previous Telegram channel as Machine-readable JSON with photos included.

   • Open the channel.
   • Click ⋮ → Export chat history.
   • Enable Photos.
   • Select Machine-readable JSON as the export format.

2. Run:

   uv run scripts/gather_links_to_previous_surveys.py \
       --exported_jsons <exported_json_file_1> <exported_json_file_2> ... <exported_json_file_N> \
       --out_path <output_file>

3. Review the generated output manually.

The script can successfully extract links from correctly formatted posts, but it cannot fix inconsistencies introduced in previous surveys (for example, different spellings of a teacher's name). A manual review is therefore recommended.

Recommendations

Throughout the survey process a considerable amount of intermediate data is generated/collected, including JSON files, teacher photos, and processed survey results. It is recommended to keep these files in a shared cloud storage (for example, a shared Google Drive). This makes collaboration easier, provides backups of important data, and allows future surveys to reuse previously collected information instead of starting from scratch.