The flow gives a visual representation of the project. Each flow zone serves a specific purpose that will be explained in the following articles.

# Flow
![Flow.png](ewM7zAxiJ7G2)

[Input Data](flow_zone:IOCYZE5)
The first zone is where the input datasets are added to the project, and their schemas should meet expectations. Data preprocessing should be done in a separate project to match the expected input datasets format illustrated in [Data Model](article:11) article. 

[Data Consolidation](flow_zone:J2WXzHG)
This zone begins by preparing and filtering engagement data to focus on interactions from 2025, extracting relevant date components such as year and week. The flow then processes KPI metrics similarly, ensuring alignment with the same timeframe by leveraging the [time series resampling plugin](recipe:compute_dates_ts). 
First of all, the solution creates a consolidated [dataset](dataset:hcp_channel) containing all possible combinations of HCP X channel from the test dataset to predict the likelihood of engagement for each channel in the next cycle and determine the highest probability. 
Through various joins and transformations, it creates comprehensive datasets that capture weekly engagement and prescriptions written by HCPs for every week within a year (52 weeks), with an indication of whether an attempt was executed each week and whether it was successful. The final output datasets, [hcp_channel_features_past](dataset:hcp_channel_features_past) and [hcp_channel_features_with_future_channel](dataset:hcp_channel_features_with_future_channel), provide a structured view of HCP interactions across different channels and their corresponding engagement success, along with prescription data, facilitating further analysis for feature generation.

For the following two zones, you can find more details in the [Feature Engineering & Generation](article:12) article. 

[KPI Features (Rx prescriptions)](flow_zone:Bss8lmR)
This flow zone processes the data to calculate trends in prescription writing over time, identifying whether prescriptions are stable, increasing, or decreasing. Additionally, it aggregates prescription data to compute average and total prescriptions per HCP. The final outputs are two datasets: one detailing prescription trends and engagement metrics, and another summarizing total and average prescriptions per HCP. This flow helps understand HCP engagement effectiveness and prescription behavior over time.

[Rolling Window Features](flow_zone:uJKKClp)
The flow zone involves several processing steps that transform and enrich the data. These steps include calculating rolling windows for engagement attempts and successes, smoothing engagement rates across different time periods, and computing trend scores to identify changes in engagement behavior. Additionally, the flow calculates cumulative engagement metrics across channels and fills in missing data to ensure completeness.
A key aspect of the flow is the calculation of engagement success rates for 4-week and 12-week periods, which are then used to derive a trend score indicating changes in engagement success over time. The flow also considers engagement across different channels by calculating  **successes in other channels over a 12-week period**. The flow further processes the data to determine **recency features**, such as the number of weeks and days since the last engagement attempt or success. This helps in understanding the frequency and timing of interactions with HCPs. The final output dataset, [HCP_channel_features_joined](dataset:HCP_channel_features_joined), consolidates all these enriched features. This dataset provides a comprehensive view of HCP engagement, enabling better decision-making for future interactions and strategies to improve engagement success across different channels.

[Final Model Dataset](flow_zone:BFUZFqK)
This zone integrates various datasets to produce a comprehensive output dataset, [NBA_features](dataset:NBA_features). This dataset consolidates information on HCP interactions, engagement success rates, and prescription trends. It includes detailed metrics on engagement attempts and successes across different channels, as well as prescription activity over various time frames. Additionally, it incorporates HCP demographic and professional details, such as specialty and location, alongside engagement preferences and historical performance. 

[Predict the Likelihood of Successful Engagement](flow_zone:I9i7VKi)

The flow consists of the machine learning prediction bottleneck for the engagement probability of each HXP with each channel in the next outreach cycle, given their past interactions and prescription activities. 
- [Data Preparation and Splitting: ](recipe:split_HCP_channel_week_features): The initial dataset is prepared and split to facilitate model training and testing. This ensures that the data is organized in a strict time manner and ready for predictive analysis.
- [Model Training and Scoring:](saved_model:vnvaIEyx) A classification model is trained using a portion of the data. This model estimates the probability of successful engagement (or not) with HCPs across various channels. The model is then applied to a test dataset to score and predict engagement probabilities.
- The [score](recipe:score_test) generates all the engagement probabilities. To further assess the holistic impact of each of these actions on prescription activities, the [compute_scored_data_prepare](recipe:compute_scored_data_prepare) recipe computes the following metrics, which are then used for the final next-best-action optimization problem. 
  - Expected Impact: For each HCP and channel combination, the flow calculates the expected impact of engagement. This is done by multiplying the predicted probability of engagement by the average number of prescriptions over the last eight weeks and the channel's uplift factor. This calculation helps determine the potential increase in prescriptions if the engagement is successful.
  - Expected Lift Percentage: The flow also computes the expected lift percentage, which estimates the increase in weekly prescriptions if the recommended engagement succeeds. This metric provides insight into the effectiveness of different engagement strategies.
- The final output, the [engagement_value](dataset:engagement_value)  dataset, contains detailed information about each HCP, including engagement probabilities, expected impacts, and lift percentages. It retains essential columns from the original dataset, such as HCP identifiers, engagement history, and prescription trends, while adding new columns that reflect the predictive insights. Predicting engagement success and calculating potential impacts helps inform decisions on which channels to prioritize to maximize prescription outcomes.

[Next Best Action Recommendation](flow_zone:62BPUTp)
This flow zone begins by removing any potential engagement that doesn't meet the business rules, such as the number of days between actions. actionable insights are retained. It further calculates the time since the last engagement and determines whether the same channel was used previously, which helps assess the effectiveness of repeated channel use. The most critical part of this zone is the optimization problem executed in [compute_next_best_action_recommendation](recipe:compute_next_best_action_recommendation) python script as described in [NBA optimization](article:3) article. The process [outputs](dataset:nba_recommendation) a subset of HCPs, each with one recommended outreach action that maximizes the overall expected impact on prescription activities while respecting the business constraints in [Project Variables](article:27).
The [solver metadata](dataset:solver_metadata) dataset provides a strategic overview of cost allocation for each channel, including projected performance and the expected impact and cost-effectiveness of each channel. This dataset is valuable for decision-makers to evaluate the return on investment for different engagement channels and to prioritize those that offer the best balance of cost and effectiveness.

[Explainability_features](flow_zone:0dHZijV)

This flow zone supports decision explainability for each HCP action recommendation. The  [compute_model_explanations](recipe:compute_model_explanations) script combines the SHAP values for individual feature importance from the machine learning model with the individual feature definitions and the actual feature values into a single array for each record in the data. The other recipes quantify the positive or negative impact of each feature on a recommendation and its importance. The [explainability_LLM_prompt](recipe:explainability_LLM_prompt) recipe feeds all this information into an LLM model that, under user instructions, generates summaries and support notes for sales reps (see [NBA Recommendation and LLM Explainability](article:16)). 

[Agents](flow_zone:default)
This flow zone adds an agentic layer to the next-best-action recommendation described in [Agentic Framework](article:6). The embedding [recipe](recipe:compute_pharma_doc_embedded) processes compliance and product-related documents used by the main  **Sales Rep Assistant**  for interactive user conversations.

[Visualizations](flow_zone:UkVo0sE) 
Post-processing data preparation for dashboard visualizations and the what-if analysis of different budget allocation scenarios. 







