Bugfix: Windows uninstall package permission error

[medscript.git] / README

MedScript
=========

MedScript is a medical prescription writing software. It is primarily for
medical practitioners for writing prescriptions.

The purpose of the program is to enable medical practitioners to prepare
computerized prescriptions. The program has been designed after the commonly
used prescription format among the medical practitioners in India.

File
----

The program uses a custom file format mpaz (Medical Prescription Archive -
Zipped). It is a zip file in a specific format which includes:

1. A meta.json file containing file type and mpaz version.
2. A prescription.zip file containing the actual prescription.
3. An attachment folder containing attached files.
4. A template folder containing the bundled prescription template.

Optionally the mpaz archive may also include an S/MIME signature and
certificate for authentication.

The structure of the mpaz file is as follows:

    <filename>.mpaz (zipped file)
    |-- meta.json (e.g. {"type": "MedScript", "version": "<mpaz version>"})
    |-- prescription.json (Prescription object in JSON format)
    |-- template (included template for rendering)
    |   |-- index.html (Jinja2 template)
    |   |-- <other template files e.g. CSS>
    |-- attachment (directory containing attachments)
    |   |-- <attached files>
    |-- signature (optional: S/MIME signature)
    |-- certificate.pem (optional: full certificate chain including end-user, intermediates and root certificate)

Directory
---------

MedScript uses a directory structure to store user files. It is highly
configurable. An example directory structure is given below:

    <medscript data directory> (configurable)
    |-- document (for storing prescription files)
    |   |-- <document files>
    |-- form (for custom input form files)
    |   |-- <custom forms in JSON format)
    |-- log (for storing log files)
    |   |-- <log files written by the program>
    |-- plugin (for installing plugins)
    |   |-- <installed plugins>
    |-- prescriber (for storing prescriber information)
    |   |-- <prescriber files in JSON format>
    |-- preset (for storing preset files)
    |   |-- additional.csv
    |   |-- advice.csv
    |   |-- certificate.csv
    |   |-- investigation.csv
    |   |-- medication.csv
    |   |-- note.csv
    |   |-- report.csv
    |-- template
    |   |-- <installed templates>
    |-- config.json (the configuration file)

Install
-------

MedScript can be used by simply downloading it from the repository and running
it with the Python 3 interpreter. The necessary python libraries need to
be installed. Alternatively the release versions can be
downloaded and used directly.

The required Python libraries are as follows:

1. PyQt6
2. PyQt6_sip
3. python_dateutil
4. Jinja2
5. lxml
6. Markdown
7. cryptography
8. packaging
9. watchdog

Usage
-----

When starting the program, the main window of is shown.The menu bar at the top
can be used to access most of the functions. The toolbar below it contains the
most commonly used functions for quick access.

### Creating a prescription

A new prescription can be created right from the starting window.
Alternatively the "New File" menu option can be used to create a new
prescription.

There are eight tabs in the tab bar containing important parts of a
prescription.

1. Patient tab: It contains the demographical data of the patient, diagnosis
and a few extra parameters of the prescription. The diagnosis can be entered
here. To enter multiple diagnosis semicolon (;) may be used to separate them.
Please note that date of birth and age cannot be used simultaneously. There
are radio buttons to select which field to use in the prescription.

2. Clinical tab: It contains the clinical note regarding the patient. The
presets can be selected from the preset box at the top and inserted into the
note by clicking the insert button.

3. Report tab: It contains the reports shown by the patient. It also has the
preset option.

4. Advice tab: It contains the primary advices given to the patient. It is
usually printed at the top of the advice section of the prescription. It also
has the preset option.

5. Investigation tab: It contains the investigations suggested to the
patient. It also has the preset option.

6. Medication tab: It contains the medications advised to the patient. It has
the preset option. It can contain both the generic and brand names of a
medicine. To insert an alternative name (generic/brand) write it on the same
line and surround it with square brackets i.e []. It also has the preset
option.

7. Additional tab: It contains additional advice given to the patient. It is
commonly printed at the bottom of the prescription.

8. Certificate tab: It can be used to write a medical certificate. Rendering a
medical certificate requires use of a different template. The "medcert"
template included with MedScript can be used for this purpose.

9. Attachment tab: Files e.g. PDF, images may be attached to the prescription
file from the attachment tab. These attachments can be viewed later when
opening the prescription file with the program. However, this attachments are
not printed with the prescription.

### Viewing the prescription

The prescription can be quickly viewed by using the "Quick Display" option
under the "Process" menu. Viewing the prescriptions this way only shows the
prescription data without considering the formatting. To display the
prescription in a printable format, use the rendering option instead.

### Saving a prescription

The "Save File" or the "Save As" option from the "File" menu can be used to
save a file created or edited in the program.

While saving the template can be selected from the "Template" combo box in the
toolbar. The template will be saved in the mpaz file. When opening an existing
file the "Template" combo box has the option to change the template or to keep
it unchanged.

### Opening a prescription

The prescriptions are saved in mpaz files and can be shared easily. To open a
prescription file, the "Open File" option from the file menu can be used.
Alternatively the file name can be supplied to the program as command line
argument when starting from the command line.


### Rendering a prescription

The prescriptions can be rendered and subsequently printed from the "Process"
menu by selecting the "Render Prescription" option. Note that the files must
be saved before rendering. The rendered prescription is opened in a separate
window. It can be saved as PDF or printed directly.

### Data

The prescription files in the default document folder are incorporated into an
index which can be used to quickly find a particular prescription. To use this
feature, select the "Show Index" option in the "File" menu. Any changes to the
directory including creation, modification or deletion of files is monitored
by the index and reflected accordingly.

The index can be filtered by using patient id, prescription id or patient's
name. The entries can be viewed directly, opened in the program for
editing/rendering or copied into a new prescription. This can be useful while
consulting follow up patients.

### Template

The program uses Jinja2 template for rendering the prescription. A default
template is provided with the program. However, other templates (see default
template for reference) can be created and placed in the template folder to be
used for rendering the prescriptions. The drop down option in the toolbar can
be used to switch between available templates.

Note that the templates are packaged with the mpaz file which can be used for
rendering. However, modifying/saving the file overwrites it.

It is easy to develop templates for the program. How to develop templates is
mentioned below.

### Markdown

This program supports markdown formatting. Markdown can be used to format the
prescriptions and certificates. It can be turned on from the
"Edit Configuration" dialog under the "Settings" menu.

Prescriber
----------

The program is primarily targeted towards individual practitioners. However,
it can be easily adapted for multiple practitioners.

The "Current Prescriber" option under the "Settings" menu can be used to
view/edit the current prescriber. The "Select Prescriber" option can be used
to open the prescriber selector dialog. All the prescribers are listed here. A
prescriber can be selected from here. Prescribers can also be edited, deleted
or new prescribers can be created from this dialog.

The data of the practitioner is stored in JSON files in the prescriber
directory. The default file to be loaded is configured in the config file. A
command line option can be used to specify which alternative prescriber file
to load in the program, e.g. `<program> --prescriber <prescriber file>`.

Preset
------

The program uses a preset system to insert repeatedly used text without the
need to type them. To use this feature the text must be entered beforehand to
the respective files. These files are in the CSV format and can be edited
with any spreadsheet editing software.

There is a preset editor included with this software as well. This editor can
be accessed by going to the "Settings" menu and selecting the "Edit Presets"
option.

The preset editor contains a drop down input at the top which can be used to
select the respective file to edit. There is also a "Save" button at the top
which can be used to save the changes to the selected file.

The data is presented in an editable table which can be used to edit the data
in the selected file. While editing, the KEY/VALUE format is to be used as
shown in the top row. The "Add Row" button at the bottom can be used to add a
new row for entry of new data.

The preset files are kept in the preset directory. The files associated with
medical certificate, clinical note, report, advice, investigation, medication
and additional are certificate.csv, note.csv, report.csv, advice.csv,
investigation.csv, medication.csv and additional.csv. Each file contains a top
row indicating the variables in the columns. The data is entered in two
columns with each row containing a KEY and a TEXT. The TEXT can be entered in
the edit area by selecting the KEY from the preset input. Blank files with
only the top row are included with the program.

Configuration
-------------

The default configuration file contains sane defaults and the program can be
used without editing it. However, the json formatted configuration file can be
edited to further tune the program to the users preference.

The default configuration is the config.json located in the config directory.
However, a different config file may be provided by using the
`<program> --config <filename>` command line argument.

It is recommended to use the default config file as base while creating
another customized config file.

A graphical configuration editor is also included with the program. It can be
accessed by going to the "Settings" menu and selecting the "Edit Configuration"
option. The configurable options are as follows:

1. Data directory: where the user data of the program is stored.

2. Prescriber: the default prescriber which is loaded when the program
starts.

3. Preset newline: whether a newline / line break to be inserted after a preset
is inserted.

4. Preset delimiter: CSV files may have different delimiters. By default
this program uses "," as delimiter, however this can be changed to ";" from
here.

5. Age/DOB: Checking this box makes new documents use age instead of date of
birth by default.

6. Markdown: The markdown formatting can be enabled from here.

7. Check update: Whether updates are available can be checked at program start
up by enabling this option.

8. Form: The custom input form system can be enabled from here.

9. Plugin: The plugin system can be enabled from here.

10. S/MIME: This is an experimental feature and is disabled by default. To use
it, it has to be enabled first from the settings. The Private key, X509
certificate and Root bundle can be selected from the options that follow this.

Prescription Object
-------------------

The program uses a Prescription object to store the prescription data. The
structure of the Prescription object is as follows:

    prescription (Prescription object)
    |-- date (string: date-time in the %Y-%m-%d %H:%M:%S format)
    |-- id (string: the id of the prescription)
    |-- pid (string: the patient's id)
    |-- name (string: the name of the patient)
    |-- dob (string: the date of birth)
    |-- age (string: the age of the patient, may contain unit)
    |-- sex (string: sex of the patient)
    |-- address (string: address of the patient)
    |-- contact (string: contact number / email of the patient)
    |-- extra (string: extra data related to the prescription)
    |-- mode (string: the mode of consultation e.g. tele-consultation)
    |-- daw (boolean: dispense as written)
    |-- diagnosis (string: diagnosis of the patient's condition)
    |-- note (string: clinical note e.g. history, physical examination)
    |-- report (string: available reports)
    |-- advice (string: advice given to the patient, not the medications)
    |-- investigation (string: investigations suggested for the patient)
    |-- medication (string: the list of medications prescribed)
    |-- additional (string: any additional advice/instructions)
    |-- certificate (string: content of a medical certificate)
    |-- custom (list: contents of custom input forms)
    |-- properties (dictionary: plugin data, each plugin in separate key)
    |-- prescriber (Prescriber object)
    |   |-- name (string: the name of the prescriber)
    |   |-- qualification (string: the qualification of the prescriber)
    |   |-- registration (string: the registration number of the prescriber)
    |   |-- address (string: the address of the prescriber)
    |   |-- contact (string: contact number / email of the prescriber)
    |   |-- extra (string: any extra data about the prescriber)
    |   |-- properties (dictionary: plugin data, each plugin in separate key)

Best practice for assigning plugin data to properties is to use a separate
key for each plugin and store the data as the value associated with that key.

Plugin
------

MedScript has a plugin system which can be used to incorporate customized
plugins written in python. To use the plugins, the plugins must be saved in
the configured plugin directory and plugin must be enabled in the
configuration.

Enabling arbitrary plugin is dangerous and may cause catastrophic damage. Only
install plugins from trusted sources and review the code.

Plugin Development
------------------

Developing MedScript plugin is very simple. All you need is to create a python
file and implement a few functions.

The plugin is kept in its own directory. The name of the directory is the name
of the plugin. A plugin directory must contain a file called main.py which
contains the functions needed by MedScript plugin system. The directory tree
is as follows:

    <medscript data directory (e.g. ~/MedScript)>
    |-- plugin
    |   |-- <plugin directory (e.g. the name of the plugin)
    |   |   |-- main.py
    |   |   |-- <other files needed by the plugin>

The main.py file may implement the following functions which will be called by
the program as needed:

    def new(prescription)
        Called when creating a new document. It is also called during program startup.
    def open(prescription)
        Called when opening a document.
    def save(prescription)
        Called when saving a document.
    def refresh(prescription)
        Called when the refresh interface option is selected.
    def run(prescription)
        Called when the option associated with the plugin is selected from the plugin menu.

The `prescription` parameter passed to the functions is a Prescription object.
The structure of this object is mentioned above. The `prescription` object can
be modified directly by the plugins.

Please note that an option associated with the plugin is added to the "Plugin"
menu if the plugin implements a `run` function. By default the name of the
option is the name of the plugin. However, this can be overridden by setting a
global variable called `name` with the desired name.

Plugins may ask for user confirmation before executing the `run` function by
setting a global variable called `confirm` containing the confirmation prompt.

Each function mentioned above may return a string which will be displayed to
the user by the program.

Plugins may get input from the user by implementing one or more of the
following functions:

    def input(string text)
        Get text input from the user.
    def fileopen(string path)
        Get file to open. Only called before "run" function.
    def filesave(string path)
        Get file to save. Only called before "run" function.

Plugin may run in the background by defining a global variable `background`
with the value `True`. This may be useful for long running tasks without
freezing the program. This is only available for the "run" function. However,
plugins running in the background can not modify the prescription object.

The plugin may implement one or more functions mentioned above, it is not
necessary to implement all.

An example plugin, that modifies the name of the patient, may be as follows:

    name="Change Name"
    background=False
    text=""

    def run(prescription):
        global text
        prescription.name=text
        return("Name change")

    def input(data):
        global text
        text=data.strip()

Plugins may also contain a web app written in HTML/JavaScript. To use it the
plugin must contain a function called `web` which takes the prescription object
and returns a tuple containing the URL of the web app and a json string
containing any data to be passed on to the web app. The `run` function of such
a plugin must take two arguments, the prescription and the data returned from
the web app.

The web app itself must include the `qtwebchannel.js` from PyQt6
(qrc:///qtwebchannel/qwebchannel.js). The webchannel exposes an object named
`js` to the web app. The web app may access the data from the plugin by using
the `js.get()` function. The web app may return data to the plugin by calling
the `run` function of the exposed `js` object with the return data as the
argument. The web app window may be closed by calling the `close` function of
the `js` object.

Template Development
--------------------

Templates are used to render the prescriptions to HTML. A template contains a
directory with the name of the template. This directory contains a file called
index.html and any other additional files needed.

    <medscript data directory (e.g. ~/MedScript)>
    |-- template
    |   |-- <template directory e.g. the name of the template>
    |   |   |-- index.html (the Jinja2 template)
    |   |   |-- <additional files e.g. CSS>

The index.html file is the Jinja2 template. The attributes of the Prescription
object is available to the template. For example the name of the patient can
be accessed by `{{name}}` while the name of the prescriber can be accessed by
`{{prescriber.name}}`.

Custom Input Forms
------------------

Custom input forms can be used to create customized input fields which can be
accessed from the "Custom" tab. For this, the custom input form files must be
stored in the configured form directory and the form option must be enabled in
the configuration.

A custom form file is a JSON file with contains the following:

1. **title**: the title of the form.
2. **form**: a list containing the inputs. Each input has the following:
    1. **name**: name of the input field, can be accessed from
templates/plugins.
    2. **type**: valid input types are line (single line), text (multiple line),
date (date time), check (checkbox).
    3. **description**: this is shown to the user and should briefly describe
the input.

An example form is provided below:

    {
        "title": "Example Form",
        "form": [
            {
                "name": "example",
                "type": "line",
                "description": "Example Input"
            }
        ]
    }

Package Installer
-----------------

MedScript has a package installer for convenient installation and
uninstallation of presets, templates, custom forms and plugins. It can be
accessed from the "Package Installer" option under the "Settings" menu.

The installed components are listed there. The installed components can be
uninstalled by selecting it and clicking the "Uninstall" button. New packages
can be installed by clicking the "Install" button and selecting the package
file. MedScript will ask for user's confirmation before installing each
component of the package.

Package Development
-------------------

MedScript installable packages are zip files containing preset, template,
form and plugin in respective folders. More than one of each component is
allowed in each package. The package structure is as follows:

    <package as a zip file>
    |-- preset
    |   |-- <preset files in CSV format>
    |-- template
    |   |-- <template directories each containing index.html and other files>
    |-- form
    |   |-- <custom input forms in JSON format>
    |-- plugin
    |   |-- <plugin directories each containing main.py and other files>

The following names are not allowed as component names:

1. note
2. report
3. advice
4. investigation
5. medication
6. additional
7. certificate
8. default
9. medcert
10. <unchanged>


Website
-------

<https://code.agnibho.com/medscript/>

License
-------

MedScript

Copyright (C) 2023 Dr. Agnibho Mondal

MedScript is free software: you can redistribute it and/or modify it under the
terms of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any later
version.

MedScript is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with
MedScript. If not, see <https://www.gnu.org/licenses/>.

Contact
-------

Dr. Agnibho Mondal

mondal@agnibho.com

www.agnibho.com