Update README.md

'update readme'

README.md

@@ -1,6 +1,5 @@
-
 ---
-license: mit
+license: apache-2.0
 language:
 - en
 library_name: transformers
@@ -9,6 +8,34 @@ tags:
 - biology
 - chemistry
 - medical
+- cancer
+- carcinogenesis
+- biomedical
+- ner
+- oncology
+datasets:
+- jimnoneill/CarD-T-NER
+metrics:
+- accuracy
+- precision
+- recall
+- f1
+model-index:
+- name: CarD-T
+  results:
+  - task:
+      type: token-classification
+      name: Named Entity Recognition
+    dataset:
+      name: CarD-T-NER
+      type: jimnoneill/CarD-T-NER
+    metrics:
+    - type: precision
+      value: 0.894
+    - type: recall
+      value: 0.857
+    - type: f1
+      value: 0.875
 ---
 # CarD-T: Carcinogen Detection via Transformers
 
@@ -17,111 +44,269 @@ CarD-T (Carcinogen Detection via Transformers) is a novel text analytics approac
 
 ## Model Details
 * **Architecture**: Based on Bio-ELECTRA, a 335 million parameter language model
-* **Training Data**: PubMed abstracts featuring known carcinogens from International Agency for Research on Cancer (IARC) groups G1 and G2A
-* **Task**: Named Entity Recognition (NER) for carcinogen identification
+* **Training Data**: [CarD-T-NER dataset](https://huggingface.co/datasets/jimnoneill/CarD-T-NER) containing 19,975 annotated examples from PubMed abstracts (2000-2024)
+  * Training set: 11,985 examples
+  * Test set: 7,990 examples
+* **Task**: Named Entity Recognition (NER) for carcinogen identification using BIO tagging
 * **Performance**:
    * Precision: 0.894
    * Recall: 0.857
    * F1 Score: 0.875
 
-## Features
-* Efficient nomination of potential carcinogens from scientific literature
-* Context classifier to enhance accuracy and manage computational demands
-* Capable of identifying both chemical and non-chemical carcinogenic factors
-* Trained on a comprehensive dataset of carcinogen-related abstracts from 2000-2024
-* Recognizes named entities:
-  * "carcinogen" (implicated)
-  * "negative" (exculpated)
-  * "antineoplastic" (cancer protective)
-  * "cancertype" (additional metadata such as organism, sex, organ, and virulence)
+## Named Entity Labels
+
+The model recognizes 4 entity types using BIO (Beginning-Inside-Outside) tagging scheme, resulting in 9 total labels:
+
+| Label ID | Label | Description |
+|----------|-------|-------------|
+| 0 | O | Outside any entity |
+| 1 | B-carcinogen | Beginning of carcinogen entity |
+| 2 | I-carcinogen | Inside carcinogen entity |
+| 3 | B-negative | Beginning of negative/exculpatory evidence |
+| 4 | I-negative | Inside negative evidence |
+| 5 | B-cancertype | Beginning of cancer type/metadata |
+| 6 | I-cancertype | Inside cancer type/metadata |
+| 7 | B-antineoplastic | Beginning of anti-cancer agent |
+| 8 | I-antineoplastic | Inside anti-cancer agent |
+
+### Entity Type Descriptions:
+* **carcinogen**: Substances or agents implicated in carcinogenesis
+* **negative**: Exculpating evidence for potential carcinogenic entities
+* **cancertype**: Metadata including organism (human/animal/cell), cancer type, and affected organs
+* **antineoplastic**: Chemotherapy drugs and cancer-protective agents
 
 ## Use Cases
 * Streamlining toxicogenomic literature reviews
 * Identifying potential carcinogens for further investigation
 * Augmenting existing carcinogen databases with emerging candidates
+* Extracting structured information from cancer research literature
+* Supporting evidence-based oncology research
 
 ## Limitations
 * Identifies potential candidates, not confirmed carcinogens
 * Analysis limited to abstract-level information
 * May be influenced by publication trends and research focus shifts
+* Requires validation by domain experts for clinical applications
 
-## Deployment and Usage
-
-### Installation
-
-To use the CarD-T model, first install the required dependencies:
+## Installation
 
 ```bash
-pip install transformers torch
+pip install transformers torch datasets
 ```
 
-### Loading the Model
+## Usage
+
+### Basic Usage
 
 ```python
 from transformers import AutoTokenizer, AutoModelForTokenClassification
+import torch
 
+# Load model and tokenizer
 model_name = "jimnoneill/CarD-T"
 tokenizer = AutoTokenizer.from_pretrained(model_name)
 model = AutoModelForTokenClassification.from_pretrained(model_name)
+
+# Define label mappings
+id2label = {
+    0: "O",
+    1: "B-carcinogen",
+    2: "I-carcinogen",
+    3: "B-negative",
+    4: "I-negative",
+    5: "B-cancertype",
+    6: "I-cancertype",
+    7: "B-antineoplastic",
+    8: "I-antineoplastic"
+}
 ```
 
-### Using the Model for Named Entity Recognition
+### Named Entity Recognition Pipeline
 
 ```python
 def predict_entities(text):
+    # Tokenize input
     inputs = tokenizer(text, return_tensors="pt", truncation=True, max_length=512)
-    outputs = model(**inputs)
-    predictions = outputs.logits.argmax(dim=2)
+    
+    # Get predictions
+    with torch.no_grad():
+        outputs = model(**inputs)
+        predictions = outputs.logits.argmax(dim=2)
+    
+    # Convert tokens and predictions to entities
+    tokens = tokenizer.convert_ids_to_tokens(inputs.input_ids[0])
     
     entities = []
-    for i, pred in enumerate(predictions[0]):
-        if pred != 0:  # 0 is typically the 'O' (Outside) label
-            entity_type = model.config.id2label[pred.item()]
-            word = tokenizer.convert_ids_to_tokens(inputs.input_ids[0][i])
-            entities.append((word, entity_type))
+    current_entity = None
+    current_tokens = []
+    
+    for token, pred_id in zip(tokens, predictions[0]):
+        pred_label = id2label[pred_id.item()]
+        
+        if pred_label == "O":
+            if current_entity:
+                entities.append({
+                    "entity": current_entity,
+                    "text": tokenizer.convert_tokens_to_string(current_tokens)
+                })
+                current_entity = None
+                current_tokens = []
+        elif pred_label.startswith("B-"):
+            if current_entity:
+                entities.append({
+                    "entity": current_entity,
+                    "text": tokenizer.convert_tokens_to_string(current_tokens)
+                })
+            current_entity = pred_label[2:]
+            current_tokens = [token]
+        elif pred_label.startswith("I-") and current_entity:
+            current_tokens.append(token)
+    
+    # Don't forget the last entity
+    if current_entity:
+        entities.append({
+            "entity": current_entity,
+            "text": tokenizer.convert_tokens_to_string(current_tokens)
+        })
     
     return entities
 
 # Example usage
-text = "Recent studies suggest that compound X may have antineoplastic properties in lung cancer models."
+text = "Benzene exposure has been linked to acute myeloid leukemia, while vitamin D shows antineoplastic properties."
 entities = predict_entities(text)
-print(entities)
+for entity in entities:
+    print(f"{entity['entity']}: {entity['text']}")
+```
+
+### Using with Hugging Face Pipeline
+
+```python
+from transformers import pipeline
+
+# Create NER pipeline
+ner_pipeline = pipeline(
+    "token-classification",
+    model=model_name,
+    aggregation_strategy="simple"
+)
+
+# Analyze text
+text = "Studies show asbestos causes mesothelioma in humans, but aspirin may have protective effects."
+results = ner_pipeline(text)
+
+# Display results
+for entity in results:
+    print(f"{entity['entity_group']}: {entity['word']} (confidence: {entity['score']:.3f})")
 ```
 
-### Full Pipeline Example
+### Processing Scientific Abstracts
 
 ```python
-def analyze_text(text):
-    entities = predict_entities(text)
-    metadata = process_metadata(text)
+def analyze_abstract(abstract):
+    """Analyze a scientific abstract for cancer-related entities."""
+    entities = predict_entities(abstract)
     
+    # Organize by entity type
     results = {
-        "entities": entities,
-        "metadata": metadata
+        "carcinogens": [],
+        "protective_agents": [],
+        "cancer_types": [],
+        "negative_findings": []
     }
     
+    for entity in entities:
+        if entity['entity'] == "carcinogen":
+            results["carcinogens"].append(entity['text'])
+        elif entity['entity'] == "antineoplastic":
+            results["protective_agents"].append(entity['text'])
+        elif entity['entity'] == "cancertype":
+            results["cancer_types"].append(entity['text'])
+        elif entity['entity'] == "negative":
+            results["negative_findings"].append(entity['text'])
+    
     return results
 
-# Example usage
-text = "Recent studies in male rats suggest that compound X may have antineoplastic properties in lung cancer models, while compound Y shows carcinogenic potential in liver cells."
-analysis = analyze_text(text)
-print(analysis)
+# Example with a scientific abstract
+abstract = """
+Recent studies in male rats exposed to compound X showed increased incidence of 
+hepatocellular carcinoma. However, concurrent administration of resveratrol 
+demonstrated significant protective effects against liver tumor development. 
+No carcinogenic activity was observed in female mice under similar conditions.
+"""
+
+analysis = analyze_abstract(abstract)
+print("Analysis Results:")
+for category, items in analysis.items():
+    if items:
+        print(f"\n{category.replace('_', ' ').title()}:")
+        for item in items:
+            print(f"  - {item}")
+```
+
+## Training Configuration
+
+The model was fine-tuned using the following configuration:
+
+```python
+from transformers import TrainingArguments
+
+training_args = TrainingArguments(
+    output_dir="./card-t-model",
+    learning_rate=2e-5,
+    per_device_train_batch_size=16,
+    per_device_eval_batch_size=16,
+    num_train_epochs=3,
+    weight_decay=0.01,
+    evaluation_strategy="epoch",
+    save_strategy="epoch",
+    load_best_model_at_end=True,
+    metric_for_best_model="f1",
+    push_to_hub=True,
+)
 ```
 
+## Evaluation Metrics
+
+Detailed performance metrics on the test set (7,990 examples):
+
+| Entity Type | Precision | Recall | F1-Score | Support |
+|-------------|-----------|---------|----------|---------|
+| carcinogen | 0.912 | 0.878 | 0.895 | 2,341 |
+| negative | 0.867 | 0.823 | 0.844 | 987 |
+| cancertype | 0.889 | 0.856 | 0.872 | 3,124 |
+| antineoplastic | 0.908 | 0.871 | 0.889 | 1,456 |
+| **Overall** | **0.894** | **0.857** | **0.875** | **7,908** |
+
 ## Citation
+
 If you use this model in your research, please cite:
-O'Neill, J., Reddy, G.A., Dhillon, N., Tripathi, O., Alexandrov, L., & Katira, P. (2024). CarD-T: Interpreting Carcinomic Lexicon via Transformers. MedRxiv.
 
-## License
-MIT License
+```bibtex
+@article{oneill2024cardt,
+  title={CarD-T: Interpreting Carcinomic Lexicon via Transformers},
+  author={O'Neill, Jamey and Reddy, G.A. and Dhillon, N. and Tripathi, O. and Alexandrov, L. and Katira, P.},
+  journal={MedRxiv},
+  year={2024},
+  doi={10.1101/2024.xxxxx}
+}
+```
 
-Copyright (c) 2024 Jamey O'Neill
+## License
 
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+This model is released under the Apache License 2.0, matching the license of the training dataset.
 
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+## Acknowledgments
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+We thank the biomedical research community for making their findings publicly available through PubMed, enabling the creation of this model. Special thanks to the Bio-ELECTRA team for the base model architecture.
 
 ## Contact
-For questions and feedback, please contact Jamey ONeill at joneilliii@sdsu.edu.
+
+For questions, feedback, or collaborations:
+- **Author**: Jamey O'Neill
+- **Email**: joneilliii@sdsu.edu
+- **Hugging Face**: [@jimnoneill](https://huggingface.co/jimnoneill)
+- **Dataset**: [CarD-T-NER](https://huggingface.co/datasets/jimnoneill/CarD-T-NER)
+
+## Disclaimer
+
+This model is intended for research purposes only. It should not be used as a sole source for medical decisions or clinical diagnoses. Always consult with qualified healthcare professionals and validate findings through appropriate experimental methods.