📚 API Documentation
Auto-generated documentation from model and function docstrings.
Updated in real-time from the source code.
🏗️ Models
Interview
Interview model.
This contains the interview step data for the simulation.
It records the interview status between each student and school in the simulation.
This includes the student's interview rank of the school and the school's interview rank of the student
Fields:
| Name | Type | Description |
|---|---|---|
| id | BigAutoField | - |
| status | CharField | - |
| student_applied | BooleanField | Whether the student has been applied to the school. |
| student_signal | IntegerField | Signal value from the student to the school |
| student_accepted | BooleanField | Whether the student has been accepted to the school invitation to interview. |
| student_true_score_of_school | FloatField | True score of school with respect to student |
| school_invited | BooleanField | Whether the school has been invited to the interview. Must have applied to school first |
| student_pre_observed_score_of_school | FloatField | Pre interview "total" score of student |
| school_pre_observed_score_of_student | FloatField | Pre interview "total" score of school |
| school_true_score_of_student | FloatField | True score of student with respect to school |
| students_pre_rank_of_school | IntegerField | Pre interview rank of student |
| schools_pre_rank_of_student | IntegerField | Pre interview rank of school |
| student_post_observed_score_of_school | FloatField | Post interview "total score" of student |
| school_post_observed_score_of_student | FloatField | Post interview "total" score of school |
| students_post_rank_of_school | IntegerField | Post interview rank of student |
| schools_post_rank_of_student | IntegerField | Post interview rank of school |
Match
Match model.
This contains the match step data for the simulation.
It records the match status between each student and school in the simulation
This includes the student's match rank of the school and the school's match rank of the student
Fields:
| Name | Type | Description |
|---|---|---|
| id | BigAutoField | - |
| students_rank_of_school | IntegerField | - |
| schools_rank_of_student | IntegerField | - |
School
School model.
This contains each school in a simulation. The school "population".
Fields:
| Name | Type | Description |
|---|---|---|
| interviews | ManyToOneRel | - |
| matches | ManyToOneRel | - |
| id | BigAutoField | - |
| name | CharField | Name of the school. |
| capacity | IntegerField | Capacity of the school. |
| score | FloatField | Score of the school. |
| meta_stddev | FloatField | Standard deviation of the score. |
| score_meta | JSONField | Meta score names and value {"Research":5, "Reputation": 10} for the score. |
| meta_stddev_preference | FloatField | Standard deviation of the preference. |
| meta_preference | JSONField | Meta score names and value {"USMLE Setp 2":5, "Grades": 10} for the preference. |
Simulation
Simulation model.
This contains the very basic simulations setup and links to the others parts of a simulation
method: create_students() -> builds the population of students
method: create_schools() -> builds the population of schools
method: upload_students() -> uploads students from a CSV file
method: upload_schools() -> uploads schools from a CSV file
Fields:
| Name | Type | Description |
|---|---|---|
| configs | ManyToOneRel | - |
| students | ManyToOneRel | - |
| schools | ManyToOneRel | - |
| interviews | ManyToOneRel | - |
| matches | ManyToOneRel | - |
| id | BigAutoField | - |
| name | CharField | - |
| public | BooleanField | - |
| description | TextField | - |
| iterations | IntegerField | - |
| created_at | DateTimeField | - |
| status | CharField | - |
Methods:
create_schools(self) -> int
Create the school population for this simulation using its latest SimulationConfig.
Behavior:
- Uses the most recent SimulationConfig linked to this Simulation (by id desc).
- Clears existing schools for this simulation before creation.
- Generates `number_of_schools` schools named "School {i}" with scores drawn from a
beta distribution using school_score_mean and school_score_stddev, ensuring scores stay between 0-1.
Capacities use Gaussian distribution. Capacity is coerced to an int >= 0.
- Uses school_meta_scores_stddev from config when generating score_meta values based on
config.applicant_meta_preference: each meta gets beta-distributed scores with base_score as mean.
- Also generates meta_preference weights per school using config.school_meta_preference and
config.school_meta_preference_stddev, storing the stddev into meta_stddev_preference.
- Returns the number of schools created.
create_students(self) -> int
Create the student population for this simulation using its latest SimulationConfig.
Behavior:
- Uses the most recent SimulationConfig linked to this Simulation (by id desc).
- Clears existing students for this simulation before creation.
- Generates `number_of_applicants` students named "Student {i}" with scores drawn from a
beta distribution using applicants_score_mean and applicant_score_stddev, ensuring scores stay between 0-1.
- Uses applicant_meta_scores_stddev from config when generating score_meta values based on
config.school_meta_preference: each meta gets beta-distributed scores with base_score as mean.
- Also generates meta_preference weights per student using config.applicant_meta_preference and
config.applicant_meta_preference_stddev, storing the stddev into meta_stddev_preference.
- Returns the number of students created.
delete_schools(self) -> int
Delete the school population for this simulation.
delete_students(self) -> int
Delete the student population for this simulation.
get_next_by_created_at(self, *, field=<django.db.models.fields.DateTimeField: created_at>, is_next=True, **kwargs)
get_previous_by_created_at(self, *, field=<django.db.models.fields.DateTimeField: created_at>, is_next=False, **kwargs)
upload_schools(self) -> int
Upload schools from a CSV file located in BASE_DIR/data.
Expected CSV format (with header): name,capacity,score[,score_meta]
- score_meta: JSON object string mapping meta names to values.
File path convention: data/simulation_{self.id}_schools.csv
- Replaces existing schools for this simulation.
- Returns the number of schools created. Returns 0 if the file does not exist.
upload_students(self) -> int
Upload students from a CSV file located in BASE_DIR/data.
Expected CSV format (with header): name,score[,score_meta]
- score_meta: JSON object string mapping meta names to values.
File path convention: data/simulation_{self.id}_students.csv
- Replaces existing students for this simulation.
- Returns the number of students created. Returns 0 if the file does not exist.
SimulationConfig
Simulation configuration model.
This contains the configuration of the simulation
Fields:
| Name | Type | Description |
|---|---|---|
| id | BigAutoField | - |
| number_of_applicants | IntegerField | Total number of applicants to generate. |
| number_of_schools | IntegerField | Total number of schools to generate. |
| applicant_score_mean | FloatField | Mean of the applicants' base scores. |
| applicant_score_stddev | FloatField | Std. dev. of the applicants' base scores (>= 0). |
| applicant_interview_limit | IntegerField | Max number of interviews each applicant can attend. |
| applicant_meta_preference | JSONField | List of applicant preference meta fields (e.g., program_size, prestige). |
| applicant_meta_preference_stddev | FloatField | Std. dev. of meta preference scores (>= 0). |
| applicant_meta_scores_stddev | FloatField | Std. dev. of meta scores per applicant (>= 0). |
| applicant_pre_interview_rating_error | FloatField | Pre-interview rating error stddev |
| applicant_post_interview_rating_error | FloatField | Pre-interview rating error stddev |
| school_score_mean | FloatField | Mean of the schools' base scores. |
| school_score_stddev | FloatField | Std. dev. of the schools' base scores (>= 0). |
| school_capacity_mean | FloatField | Mean capacity per school. |
| school_capacity_stddev | FloatField | Std. dev. of capacity per school (>= 0). |
| school_interview_limit | FloatField | Max number of interviews each school can conduct In percent of capacity. |
| school_meta_preference | JSONField | List of school preference meta fields (e.g., board_scores, research). |
| school_meta_preference_stddev | FloatField | - |
| school_meta_scores_stddev | FloatField | Std. dev. of meta scores per school (>= 0). |
| school_pre_interview_rating_error | FloatField | The stddev scoreing error used to calculate the observed score for each student |
| school_post_interview_rating_error | FloatField | The stddev scoreing error used to calculate the observed score for each student |
Student
Student model.
This contains each student in a simulation. The student "population".
Fields:
| Name | Type | Description |
|---|---|---|
| interviews | ManyToOneRel | - |
| matches | ManyToOneRel | - |
| id | BigAutoField | - |
| name | CharField | Name of the student. |
| score | FloatField | Score of the student. |
| meta_stddev | FloatField | Standard deviation of the score. |
| score_meta | JSONField | Meta score names and value {"USMLE Setp 2":5, "Grades": 10} for the score. |
| meta_stddev_preference | FloatField | Standard deviation of the preference. |
| meta_preference | JSONField | Meta score names and value {"School size":5, "Reputation": 10} for the preference. |
User
Custom user model extending Django's AbstractUser.
Note: Django's AbstractUser already includes username, password, email fields
Fields:
| Name | Type | Description |
|---|---|---|
| logentry | ManyToOneRel | - |
| simulations | ManyToOneRel | - |
| id | BigAutoField | - |
| password | CharField | - |
| last_login | DateTimeField | - |
| is_superuser | BooleanField | Designates that this user has all permissions without explicitly assigning them. |
| username | CharField | Required. 150 characters or fewer. Letters, digits and @/./+/-/_ only. |
| first_name | CharField | - |
| last_name | CharField | - |
| EmailField | - | |
| is_staff | BooleanField | Designates whether the user can log into this admin site. |
| is_active | BooleanField | Designates whether this user should be treated as active. Unselect this instead of deleting accounts. |
| date_joined | DateTimeField | - |
| full_name | CharField | - |
| disabled | BooleanField | - |
| status | CharField | - |
| created_at | DateTimeField | - |
| updated_at | DateTimeField | - |
| groups | ManyToManyField | The groups this user belongs to. A user will get all permissions granted to each of their groups. |
| user_permissions | ManyToManyField | Specific permissions for this user. |
Methods:
acheck_password(self, raw_password)
See check_password().
aget_all_permissions(self, obj=None)
aget_group_permissions(self, obj=None)
See get_group_permissions()
aget_user_permissions(self, obj=None)
See get_user_permissions()
ahas_module_perms(self, app_label)
See has_module_perms()
ahas_perm(self, perm, obj=None)
See has_perm()
ahas_perms(self, perm_list, obj=None)
See has_perms()
check_password(self, raw_password)
Return a boolean of whether the raw_password was correct. Handles hashing formats behind the scenes.
email_user(self, subject, message, from_email=None, **kwargs)
Send an email to this user.
get_all_permissions(self, obj=None)
get_full_name(self)
Return the first_name plus the last_name, with a space in between.
get_group_permissions(self, obj=None)
Return a list of permission strings that this user has through their groups. Query all available auth backends. If an object is passed in, return only permissions matching this object.
get_next_by_created_at(self, *, field=<django.db.models.fields.DateTimeField: created_at>, is_next=True, **kwargs)
get_next_by_date_joined(self, *, field=<django.db.models.fields.DateTimeField: date_joined>, is_next=True, **kwargs)
get_next_by_updated_at(self, *, field=<django.db.models.fields.DateTimeField: updated_at>, is_next=True, **kwargs)
get_previous_by_created_at(self, *, field=<django.db.models.fields.DateTimeField: created_at>, is_next=False, **kwargs)
get_previous_by_date_joined(self, *, field=<django.db.models.fields.DateTimeField: date_joined>, is_next=False, **kwargs)
get_previous_by_updated_at(self, *, field=<django.db.models.fields.DateTimeField: updated_at>, is_next=False, **kwargs)
get_session_auth_fallback_hash(self)
get_session_auth_hash(self)
Return an HMAC of the password field.
get_short_name(self)
Return the short name for the user.
get_user_permissions(self, obj=None)
Return a list of permission strings that this user has directly. Query all available auth backends. If an object is passed in, return only permissions matching this object.
get_username(self)
Return the username for this User.
has_module_perms(self, app_label)
Return True if the user has any permissions in the given app label. Use similar logic as has_perm(), above.
has_perm(self, perm, obj=None)
Return True if the user has the specified permission. Query all available auth backends, but return immediately if any backend returns True. Thus, a user who has permission from a single auth backend is assumed to have permission in general. If an object is provided, check permissions for that object.
has_perms(self, perm_list, obj=None)
Return True if the user has each of the specified permissions. If object is passed, check if the user has all required perms for it.
has_usable_password(self)
Return False if set_unusable_password() has been called for this user.
natural_key(self)
set_password(self, raw_password)
set_unusable_password(self)
⚙️ Utility Functions
default_applicant_meta_preference()
default_school_meta_preference()
generate_beta_score(mean: float, stddev: float) -> float
Generate a score from beta distribution with given mean and stddev.
get_beta_parameters(mean: float, desired_stddev: float) -> tuple[float, float]
Convert mean and desired standard deviation to beta distribution parameters.
For a beta distribution, if stddev is too large for the given mean,
it will be automatically reduced to the maximum possible value.
Returns:
tuple: (alpha, beta) parameters for beta distribution
This documentation is generated in real-time from Python docstrings. To update the documentation, modify the docstrings in your source code.
NRMP Simulations