README

   1 MedScript
   2 =========
   3
   4 MedScript is a medical prescription writing software. It is primarily for
   5 medical practitioners for writing prescriptions.
   6
   7 The purpose of the program is to enable medical practitioners to prepare
   8 computerized prescriptions. The program has been designed after the commonly
   9 used prescription format among the medical practitioners in India.
  10 Inclusion of prescription style of other regions will hopefully be implemented
  11 in future updates.
  12
  13 File
  14 ----
  15
  16 The program uses a custom file format mpaz (Medical Prescription Archive -
  17 Zipped). It is a zip file in a specific format which includes:
  18
  19 1. A meta.json file containing file type and mpaz version.
  20 2. A prescription.zip file containing the actual prescription.
  21 3. An attachment folder containing attached files.
  22 4. A template folder containing the bundled prescription template.
  23
  24 Optionally the mpaz archive may also include an S/MIME signature and
  25 certificate for authentication.
  26
  27 The structure of the mpaz file is as follows:
  28
  29     <filename>.mpaz (zipped file)
  30     |-- meta.json (e.g. {"type": "MedScript", "version": "<mpaz version>"})
  31     |-- prescription.json (Prescription object in JSON format)
  32     |-- template (included template for rendering)
  33     |   |-- index.html (Jinja2 template)
  34     |   |-- <other template files e.g. CSS>
  35     |-- attachment (directory containing attachments)
  36     |   |-- <attached files>
  37     |-- signature (optional: S/MIME signature)
  38     |-- certificate.pem (optional: full certificate chain including end-user, intermediates and root certificate)
  39
  40 Directory
  41 ---------
  42
  43 MedScript uses a directory structure to store user files. It is highly
  44 configurable. An example directory structure is given below:
  45
  46     <medscript data directory> (configurable)
  47     |-- document (for storing prescription files)
  48     |   |-- <document files>
  49     |-- plugin (for installing plugins)
  50     |   |-- <installed plugins>
  51     |-- prescriber (for storing prescriber information)
  52     |   |-- <prescriber files in JSON format>
  53     |-- preset (for storing preset files)
  54     |   |-- additional.csv
  55     |   |-- advice.csv
  56     |   |-- certify.csv
  57     |   |-- investigation.csv
  58     |   |-- medication.csv
  59     |   |-- note.csv
  60     |   |-- report.csv
  61     |-- template
  62     |   |-- <installed templates>
  63     |-- config.json (the configuration file)
  64
  65 Install
  66 -------
  67
  68 MedScript can be used by simply downloading it from the repository and running
  69 it with the Python 3 interpreter. The necessary python libraries need to
  70 be installed. Alternatively the release versions can be
  71 downloaded and used directly.
  72
  73 The required Python libraries are as follows:
  74
  75 1. PyQt6
  76 2. PyQt6_sip
  77 3. python_dateutil
  78 4. Jinja2
  79 5. lxml
  80 6. Markdown
  81 7. cryptography
  82 8. packaging
  83
  84 Usage
  85 -----
  86
  87 The common functionalities of the program can be used within the graphical
  88 interface. Editing of some configuration files are needed only for the
  89 advanced features such as custom presets.
  90
  91 When starting the program, the main window of is shown.The menu bar at the top
  92 can be used to access most of the functions. The toolbar below it contains the
  93 most commonly used functions for quick access.
  94
  95 ### Creating a prescription
  96
  97 A new prescription can be created right from the starting window.
  98 Alternatively the "New" menu option can be used to create a new
  99 prescription.
 100
 101 There are eight tabs in the tab bar containing important parts of a
 102 prescription.
 103
 104 1. Patient tab: It contains the demographical data of the patient, diagnosis
 105 and a few extra parameters of the prescription. The diagnosis can be entered
 106 here. To enter multiple diagnosis semicolon (;) may be used to separate them.
 107
 108 2. Clinical tab: It contains the clinical note regarding the patient. The
 109 presets can be selected from the preset box at the top and inserted into the
 110 note by clicking the insert button.
 111
 112 3. Report tab: It contains the reports shown by the patient. It also has the
 113 preset option.
 114
 115 4. Advice tab: It contains the primary advices given to the patient. It is
 116 usually printed at the top of the advice section of the prescription. It also
 117 has the preset option.
 118
 119 5. Investigation tab: It contains the investigations suggested to the
 120 patient. It also has the preset option.
 121
 122 6. Medication tab: It contains the medications advised to the patient. It has
 123 the preset option. It can contain both the generic and brand names of a
 124 medicine. To insert an alternative name (generic/brand) write it on the same
 125 line and surround it with square brackets i.e []. It also has the preset
 126 option.
 127
 128 7. Additional tab: It contains additional advice given to the patient. It is
 129 commonly printed at the bottom of the prescription.
 130
 131 8. Attachment tab: Files e.g. PDF, images may be attached to the prescription
 132 file from the attachment tab. These attachments can be viewed later when
 133 opening the prescription file with the program. However, this attachments are
 134 not printed with the prescription.
 135
 136 ### Saving a prescription
 137
 138 The "Save" or the "Save As" option from the "File" menu can be used to save a
 139 file created or edited in the program.
 140
 141 ### Opening a prescription
 142
 143 The prescriptions are saved in mpaz files and can be shared easily. To open a
 144 prescription file, the "Open" option from the file menu can be used.
 145 Alternatively the file name can be supplied to the program as command line
 146 argument when starting from the command line.
 147
 148 ### Rendering a prescription
 149
 150 The prescriptions can be rendered and subsequently printed from the "Prepare"
 151 menu by selecting the "Render" option. Note that the files must be saved
 152 before rendering. The rendered prescription is opened in a separate window. It
 153 can be saved as PDF or printed directly.
 154
 155 ### Data
 156
 157 The prescription files in the default document folder are incorporated into an
 158 index which can be used to quickly find a particular prescription. To use this
 159 feature, select the "Index" option in the "Data" menu.
 160
 161 Data from the the prescription files can be combined into a table and
 162 exported to a CSV file for analysis from the "Tabular" option in the "Data"
 163 menu.
 164
 165 ### Template
 166
 167 The program uses Jinja2 template for rendering the prescription. A default
 168 template is provided with the program. However, other templates (see default
 169 template for reference) can be created and placed in the template folder to be
 170 used for rendering the prescriptions. The drop down option in the toolbar can
 171 be used to switch between available templates.
 172
 173 Note that the templates are packaged with the mpaz file which can be used for
 174 rendering. However, modifying/saving the file overwrites it.
 175
 176 It is easy to develop templates for the program. How to develop templates is
 177 mentioned below.
 178
 179 ### Markdown
 180
 181 This program supports markdown formatting. Markdown can be used to format the
 182 prescriptions and certificates. It can be turned on from the
 183 "Configuration" dialog under the "Settings" menu.
 184
 185 ### Medical Certificate
 186
 187 The Certify/Extra area can be used to write a medical prescription. Preset
 188 system is available for this as well. Certification requires different
 189 templates designed for it. A template named medcert is included with the
 190 program.
 191
 192 Prescriber
 193 ----------
 194
 195 The program is primarily targeted towards individual practitioners. However,
 196 it can be easily adapted for multiple practitioners.
 197
 198 The data of the practitioner is stored in json files in the prescriber
 199 directory. The default file to be loaded is configured in the config file. A
 200 command line option can be used to specify which alternative prescriber file
 201 to load in the program, e.g. `<program> --prescriber <prescriber file>`.
 202
 203 The data of the currently selected prescriber can be edited using the
 204 "Prescriber" option under the "Prepare" menu.
 205
 206 If multiple prescribers have been configured (e.g. by copying the prescriber
 207 file and editing them individually), the prescribers can easily by switched by
 208 using the "Switch" option in the "Settings" menu and selecting the desired
 209 prescriber file.
 210
 211 Preset
 212 ------
 213
 214 The program uses a preset system to insert repeatedly used text without the
 215 need to type them. To use this feature the text must be entered beforehand to
 216 the respective files. These files are in the CSV format and can be edited
 217 with any spreadsheet editing software.
 218
 219 There is a preset editor included with this software as well. This editor can
 220 be accessed by going to the "Settings" menu and selecting the "Preset" option.
 221
 222 The preset editor contains a drop down input at the top which can be used to
 223 select the respective file to edit. There is also a "Save" button at the top
 224 which can be used to save the changes to the selected file.
 225
 226 The data is presented in an editable table which can be used to edit the data
 227 in the selected file. While editing, the KEY/VALUE format is to be used as
 228 shown in the top row. The "Add Row" button at the bottom can be used to add a
 229 new row for entry of new data.
 230
 231 The preset files are kept in the preset directory. The files associated with
 232 medical certificate, clinical note, report, advice, investigation, medication
 233 and additional are certify.csv, note.csv, report.csv, advice.csv,
 234 investigation.csv, medication.csv and additional.csv. Each file contains a top
 235 row indicating the variables in the columns. The data is entered in two
 236 columns with each row containing a KEY and a TEXT. The TEXT can be entered in
 237 the edit area by selecting the KEY from the preset input. Blank files with
 238 only the top row are included with the program.
 239
 240 Configuration
 241 -------------
 242
 243 The default configuration file contains sane defaults and the program can be
 244 used without editing it. However, the json formatted configuration file can be
 245 edited to further tune the program to the users preference.
 246
 247 The default configuration is the config.json located in the config directory.
 248 However, a different config file may be provided by using the
 249 `<program> --config <filename>` command line argument.
 250
 251 It is recommended to use the default config file as base while creating
 252 another customized config file.
 253
 254 A graphical configuration editor is also included with the program. It can be
 255 accessed by going to the "Settings" menu and selecting the "Configuration"
 256 option. The configurable options are as follows:
 257
 258 1. Data directory: where the user data of the program is stored.
 259
 260 2. Prescriber: the default prescriber which is loaded when the program
 261 starts.
 262
 263 3. Preset newline: whether a newline / line break to be inserted after a preset
 264 is inserted.
 265
 266 4. Preset delimiter: CSV files may have different delimiters. By default
 267 this program uses "," as delimiter, however this can be changed to ";" from
 268 here.
 269
 270 5. Markdown: The markdown formatting can be enabled from here.
 271
 272 6. Check update: Whether updates are available can be checked at program start
 273 up by enabling this option.
 274
 275 7. Plugin: The plugin system can be enabled from here.
 276
 277 8. S/MIME: This is an experimental feature and is disabled by default. To use
 278 it, it has to be enabled first from the settings. The Private key, X509
 279 certificate and Root bundle can be selected from the options that follow this.
 280
 281 Prescription Object
 282 -------------------
 283
 284 The program uses a Prescription object to store the prescription data. The
 285 structure of the Prescription object is as follows:
 286
 287     prescription (Prescription object)
 288     |-- date (string: date-time in the %Y-%m-%d %H:%M:%S format)
 289     |-- id (string: the id of the prescription)
 290     |-- name (string: the name of the patient)
 291     |-- age (string: the age of the patient, may contain unit)
 292     |-- sex (string: sex of the patient)
 293     |-- address (string: address of the patient)
 294     |-- contact (string: contact number / email of the patient)
 295     |-- extra (string: extra data related to the prescription, may also be used for writing certificates)
 296     |-- mode (string: the mode of consultation e.g. tele-consultation)
 297     |-- daw (boolean: dispense as written)
 298     |-- diagnosis (string: diagnosis of the patient's condition)
 299     |-- note (string: clinical note e.g. history, physical examination)
 300     |-- report (string: available reports)
 301     |-- advice (string: advice given to the patient, not the medications)
 302     |-- investigation (string: investigations suggested for the patient)
 303     |-- medication (string: the list of medications prescribed)
 304     |-- additional (string: any additional advice/instructions)
 305     |-- prescriber (Prescriber object)
 306     |   |-- name (string: the name of the prescriber)
 307     |   |-- qualification (string: the qualification of the prescriber)
 308     |   |-- registration (string: the registration number of the prescriber)
 309     |   |-- address (string: the address of the prescriber)
 310     |   |-- contact (string: contact number / email of the prescriber)
 311     |   |-- extra (string: any extra data about the prescriber)
 312
 313 Plugin
 314 ------
 315
 316 MedScript has a plugin system which can be used to incorporate customized
 317 plugins written in python. To use the plugins, the plugins must be saved in
 318 the configured plugin directory and plugin must be enabled in the
 319 configuration.
 320
 321 Enabling arbitrary plugin is dangerous and may cause catastrophic damage. Only
 322 install plugins from trusted sources and review the code.
 323
 324 Plugin Development
 325 ------------------
 326
 327 Developing MedScript plugin is very simple. All you need is to create a python
 328 file and implement a few functions.
 329
 330 The plugin is kept in its own directory. The name of the directory is the name
 331 of the plugin. A plugin directory must contain a file called main.py which
 332 contains the functions needed by MedScript plugin system. The directory tree
 333 is as follows:
 334
 335     <medscript data directory (e.g. ~/MedScript)>
 336     |-- plugin
 337     |   |-- <plugin directory (e.g. the name of the plugin)
 338     |   |   |-- main.py
 339     |   |   |-- <other files needed by the plugin>
 340
 341 The main.py file may implement the following functions which will be called by
 342 the program as needed:
 343
 344     def new(prescription)
 345         Called when creating a new document. It is also called during program startup.
 346     def open(prescription)
 347         Called when opening a document.
 348     def save(prescription)
 349         Called when saving a document.
 350     def refresh(prescription)
 351         Called when the refresh option is selected.
 352     def run(prescription)
 353         Called when the option associated with the plugin is selected from the plugin menu.
 354
 355 The `prescription` parameter passed to the functions is a Prescription object.
 356 The structure of this object is mentioned above. The `prescription` object can
 357 be modified directly by the plugins.
 358
 359 Please note that an option associated with the plugin is added to the "Plugin"
 360 menu if the plugin implements a `run` function. By default the name of the
 361 option is the name of the plugin. However, this can be overridden by setting a
 362 global variable called `name` with the desired name.
 363
 364 Each function mentioned above may return a string which will be displayed to
 365 the user by the program.
 366
 367 Plugins may get input from the user by implementing one or more of the
 368 following functions:
 369
 370     def input(string text)
 371         Get text input from the user.
 372     def fileopen(string path)
 373         Get file to open. Only called before "run" function.
 374     def filesave(string path)
 375         Get file to save. Only called before "run" function.
 376
 377 Plugin may run in the background by defining a global variable `background`
 378 with the value `True`. This may be useful for long running tasks without
 379 freezing the program. This is only available for the "run" function. However,
 380 plugins running in the background can not modify the prescription object.
 381
 382 The plugin may implement one or more functions mentioned above, it is not
 383 necessary to implement all.
 384
 385 An example plugin, that modifies the name of the patient, may be as follows:
 386
 387     name="Change Name"
 388     background=False
 389     text=""
 390
 391     def run(prescription):
 392         global text
 393         prescription.name=text
 394         return("Name change")
 395
 396     def input(data):
 397         global text
 398         text=data.strip()
 399
 400 Template Development
 401 --------------------
 402
 403 Templates are used to render the prescriptions to HTML. A template contains a
 404 directory with the name of the template. This directory contains a file called
 405 index.html and any other additional files needed.
 406
 407     <medscript data directory (e.g. ~/MedScript)>
 408     |-- template
 409     |   |-- <template directory e.g. the name of the template>
 410     |   |   |-- index.html (the Jinja2 template)
 411     |   |   |-- <additional files e.g. CSS>
 412
 413 The index.html file is the Jinja2 template. The attributes of the Prescription
 414 object is available to the template. For example the name of the patient can
 415 be accessed by `{{name}}` while the name of the prescriber can be accessed by
 416 `{{prescriber.name}}`.
 417
 418
 419 Website
 420 -------
 421
 422 <https://code.agnibho.com/medscript/>
 423
 424 License
 425 -------
 426
 427 MedScript
 428
 429 Copyright (C) 2023 Dr. Agnibho Mondal
 430
 431 MedScript is free software: you can redistribute it and/or modify it under the
 432 terms of the GNU General Public License as published by the Free Software
 433 Foundation, either version 3 of the License, or (at your option) any later
 434 version.
 435
 436 MedScript is distributed in the hope that it will be useful, but WITHOUT ANY
 437 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
 438 A PARTICULAR PURPOSE. See the GNU General Public License for more details.
 439
 440 You should have received a copy of the GNU General Public License along with
 441 MedScript. If not, see <https://www.gnu.org/licenses/>.
 442
 443 Contact
 444 -------
 445
 446 Dr. Agnibho Mondal
 447
 448 mondal@agnibho.com
 449
 450 www.agnibho.com