Merge pull request #5 from microsoft/pub/readme-updates

docs: enhance contributing guidelines and add disclaimer to README

CONTRIBUTING.md

@@ -15,4 +15,82 @@ or contact [[email protected]](mailto:[email protected]) with any addi
 
 ## Goals
 
-This repository contains a toolkit for healthcare AI examples, providing various utilities and models to streamline the use of the examples in the Microsoft HealthcareAI ecosystem. Use the samples in this repository to explore and implement healthcare AI scenarios.
+This repository contains a toolkit for healthcare AI examples, providing various utilities and models to streamline the use of the examples in the Microsoft HealthcareAI ecosystem. Use the samples in this repository to explore and implement healthcare AI scenarios.
+
+## Code Quality Guidelines for Adding Example Code
+
+When contributing new examples please follow these guidelines:
+
+* Examples must be **clear**, **consistent**, and **modular**.
+* Examples should manage **dependencies** carefully and must **run without error**. 
+* Please provide thorough **documentation and explanations** including **diagrams** and **visualizations**. 
+* Please optimize for **performance** by handling **data** responsibly. 
+* Following **security** best practices to maintain high code quality and consistency across the repository.
+* **Use repository libraries**: Whenever possible, use the `healthcareai_toolkit` library when possible, particularly for loading and preparing images, instead of writing new code.
+
+Below are more detailed guidelines.
+
+### Guidelines
+
+#### Clarity
+- Ensure your code is easy to understand.
+- Use clear and descriptive variable and function names.
+- Include comments and docstrings explaining complex sections, functions, and classes.
+
+#### Consistency
+- Follow the existing coding style and conventions used in the repository.
+- Adhere to a consistent code style (e.g., following PEP 8 guidelines for Python).
+- Maintain consistent formatting, indentation, and organization.
+
+#### Modularity
+- Write modular code by encapsulating repetitive tasks into functions or classes.
+- Enhance code reusability and clarity through modular design.
+
+#### Executable Code
+- Ensure that notebooks run from start to finish without errors.
+- You may leave the output of cells in the notebook.
+- Implement error handling to make the code robust against invalid inputs or unexpected situations.
+- Use try-except blocks where appropriate to handle exceptions gracefully.
+
+#### Documentation
+- Provide a clear explanation of what the example does.
+- Include any assumptions, prerequisites, and setup instructions necessary to run the code.
+
+#### Diagrams
+- Diagrams are highly encouraged to explain what is happening in the notebook.
+- Use diagrams to illustrate workflows, data processing steps, model architectures, etc.
+- Ensure diagrams are clear, properly labeled, and enhance the understanding of the content.
+
+#### Visualization Standards
+- Use clear and informative visualizations.
+- Include titles, axis labels, legends, and captions to make plots self-explanatory.
+
+#### Execution Time
+- Ensure that each notebook can be completed within 20-30 minutes.
+- Optimize your code for large datasets or time-sensitive operations.
+- Use efficient algorithms and data structures appropriate for the task.
+- Consider including precomputed results or smaller datasets if necessary to meet this requirement.
+
+#### Resource Management
+- Be mindful of memory and computational resource usage, especially with large datasets.
+- Optimize code to prevent unnecessary resource consumption.
+
+#### Dependencies
+- List any external dependencies.
+- Ensure they are necessary and up-to-date.
+- Avoid including unnecessary packages.
+
+#### Reproducibility
+- Specify versions for critical dependencies and include them in your prerequisites.
+
+#### Data
+- No data can be included in the repository.
+- Provide a public location or method for obtaining the data.
+- Contact us if there are any issues.
+
+#### Security and Privacy
+- Ensure that security best practices are followed.
+- Do not hard-code credentials, API keys, or personal data.
+- Use secure methods to handle sensitive information.
+- Use environment variables or configuration files (excluded from version control) for any credentials or API keys.
+

README.md

@@ -2,6 +2,8 @@
 
 This repository contains a examples for healthcare AI, providing various examples to streamline the use of the models in the Microsoft HealthcareAI ecosystem. Use the samples in this repository to explore and implement healthcare AI scenarios.
 
+**Disclaimer**: _The Microsoft healthcare AI models, code and examples are intended for research and model development exploration. The models, code and examples are not designed or intended to be deployed in clinical settings as-is nor for use in the diagnosis or treatment of any health or medical condition, and the individual models’ performances for such purposes have not been established. You bear sole responsibility and liability for any use of the healthcare AI models, code and examples, including verification of outputs and incorporation into any product or service intended for a medical purpose or to inform clinical decision-making, compliance with applicable healthcare laws and regulations, and obtaining any necessary clearances or approvals._
+
 ## Getting Started
 
 To get started with this project, follow these steps:
@@ -12,16 +14,11 @@ To get started with this project, follow these steps:
     cd healthcareai-examples
     ```
 
-2. **Install dependencies**:
-    ```sh
-    pip install -e package
-    ```
-
-3. **Set up your environment**:
+2. **Set up your environment**:
 
     ### 1. Prerequisites
 
-    To run this notebook you will need a dataset and an endpoint.
+    To run most examples, you will need to download the data and have an appropriate endpoint deployed.
 
     #### Download data
 
@@ -52,9 +49,30 @@ To get started with this project, follow these steps:
 
     After copying, open the `.env` file and fill in the values.
 
-4. **Run examples**:
+
+    #### Sample Toolkit Installation
+
+    **Prerequisites**
+
+    - Python version: `>=3.9.0,<3.12`
+    - pip version: `>=21.3`
+
+    Many examples require the `healthcareai_toolkit` package. Install it by running the following command in the repository root:
+
+    ```sh
+    pip install package
+    ```
+
+    If you wish to edit the package easily, you can also install it in editable mode using the `-e` flag:
+
+    ```sh
+    pip install -e package
+    ``` 
+
+3. **Examples and Sample Code**:
     Explore the notebooks in the `azureml` directory to see various examples of how to use the healathcare ai models.
 
+
 ## Folder Structure
 
 - **azureml**: Contains Jupyter notebooks and scripts for deploying and using AI models with Azure Machine Learning.
@@ -86,3 +104,4 @@ trademarks or logos is subject to and must follow
 [Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).
 Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
 Any use of third-party trademarks or logos are subject to those third-party's policies.
+