by

Introducing the YMARK specification

EN

The YMARK specification aims to define a simple file format that allows to store (and export) all the metadata of a given subject for a student. In particular it was designed to store the assessment so a given program can parse the file and easily compute the final mark and show all the available information of the subject.

Introduction

YMARKs files are encoded in plain YAML and include all the metadata of a subject and the marks. The main principles of the YMARK format are that it must be:

  • Simple
  • Human readable
  • Easy to modify
  • Extensible
  • Compatible

Structure

The following are the defined keys of a YMARK file. Other atributes are not only allowed but encouraged. Each YMARK file describes a unique subject for one student, so each of these properties is about that particular subject and student:

Key Required Description Type Examples
codename Required Two or more capital letters that easily identify the subject String CRYPTO
MND
SED
status Required An integer describing the state of this subject Integer More info below
name Optional Full name of the subject String Cryptography I
Micro and Nano Electronic Design
Sistemas electrónicos digitales
code Optional Code of the subject String G330923
230646
course Optional Course of the subject String Cybersecurity Course
Master in Electronic Engineering Grado en Ingeniería Electrónica
institution Optional Institution teaching the subject String Standford University
Universitat Politècnica de Cat
Universidade de Vigo
credits Optional Number of credits of the subject Float 2.5
6
type Optional Type of the subject String Online
Core
Obligatoria
year Optional Academic year String 2014
2015/16
1999/2000
term Optional Term of the subject String 2
Spring
web Optional Website of the subject String coursera.org/learn/crypto
atenea.upc.edu/31299
assessment Optional Array of dictionaries containing the assessment marks Array More info below

Status

The status key of the subject is an integer that indicates the following:

Status Code Meaning Description Color
0 Passed The subject has been passed and now is archived Green
1 Active The subject is being taught in the actual course Blue
2 Future The subject will start in the future Purple
4 Failed The subject has been passed and now is archived Red
Other Unknown The status of the subject is unknown Grey

If you want to create a new proprietary status code you should use a code over 100. The colors are recommendations for any GUI.

Assessment

The assessment key is an array that includes all the marks of the subject needed to compute the final mark and a some other important information.

Each element of the array is a dictionary with the following keys:

Key Required Description Default Example
mark Required Mark of the item 8
68
7.5
description Optional Name of the item Mid-Term Exam
Delivery
Lab 3
weight Optional Float between 0 and 1 indicating the weight of this item over the overall subject mark 1 1
0.2
0.05
fullscale Optional Float that indicates the maximum mark of this item 10 10
100
2.5

Example

Here is an example of a full YMARK file:

course: Master in Electronic Engineering (MEE)
institution: Universitat Politècnica de Catalunya (UPC)
codename: AACT
name: Advanced Analog Circuit Techniques
code: 230642
credits: 5
type: Core
year: 2015/16
term: 2
status: 1
web: http://atenea.upc.edu/moodle/course/view.php?id=31281
assessment:
    - description: Deliveries
      mark: 7
      weight: 0.2
    - description: Mid-Term Exam
      mark: 8
      weight: 0.2
    - description: Final Exam
      mark: 76
      fullscale: 100
      weight: 0.6

Program

ymark.py is a script that reads YMARK files and computes the final mark of the subjects.

Usage

ymark.py - Pedro José Pereira Vieito © 2016
  Compute marks from diferent subjects in YMARK format.

Usage:
  ymark.py [-adeghow] <file>...

Options:
  -d, --details  Show subject details
  -e, --edit     Edit mark files
  -g, --guide    Open subject guide
  -o, --open     Open subject folder
  -w, --web      Open subject web
  -h, --help     Show this help

Output

$ ./ymark.py AACT.ymark -d
AACT (Advanced Analog Circuit Techniques) ………………………………………………………………  7.6
 Course: Master in Electronic Engineering (MEE)
 Institution: Universitat Politècnica de Catalunya (UPC)
 Year: 2015/16
 Term: 2
 Type: Core
 Status: Active
 Credits: 5 ECTS
 Code: 230642
 Web: http://atenea.upc.edu/moodle/course/view.php?id=31281
 Progress: 100%
 Assessment: 3 items
 - Deliveries (20.0%) ……………………………………………………………………………………………………………………  7.0
 - Mid-Term Exam (20.0%) ……………………………………………………………………………………………………………  8.0
 - Final Exam (60.0%) ……………………………………………………………………………………………………………………  7.6