The method for constructing narrative content through data primarily employs web-based visualization techniques that include data exploration, story creation, and storytelling (Garreton et al., 2025). These techniques enhance readers’ interactive exploration experiences by incorporating graphic elements and intuitive interface designs, thereby fostering deeper engagement with the material. For traditional residences, the associated data mainly includes geographic topography, architectural features, historical records, and cultural elements. Among these, natural geographical factors exert a profound influence on site selection and design decisions for residences (Mileto et al., 2019; Gomis et al., 2020), as they shape how residences adapt to environmental constraints like terrain, climate, and resource availability.

Given the objective nature of the dataset, to ensure the accuracy of the information conveyed, we first evaluate the dataset’s scientific validity and usability (Gebru et al., 2021), followed by data preprocessing to identify dataset-specific characteristics (Oreski et al., 2017). We analyze attributes such as the number of features, data sparsity, and number of instances, and then choose appropriate visualization techniques and themes accordingly.

Consequently, this paper draws on geographic and humanistic data related to Nanyin Hall—such as datasets, drawings, and photographs—as the foundation for narrative content. Key data features are extracted through visualization analysis and then used to inform the content of the story. The analyses were mainly conducted using the GeoPandas and Pandas libraries in Python (version 3.10.9, Python Software Foundation, Wilmington, DE, USA). These libraries implement efficient geospatial processing and statistical operations to validate the authenticity of the narrative.

Narrative structure is primarily used to represent the relationships among characters, events, and roles (Hullman et al., 2013) and plays a critical role in shaping both the presentation of a story and public perception. Common story structures include the three-act structure (Upton, 1748), pyramid-based structure (Freytag, 1895), anachronous narrative structures (Genette, 1983), and other variations.

Narrative structure can be quantitatively characterized; for example, linguistic patterns in text—such as the use of verbs and adverbs—can be leveraged to guide structural choices (Pustejovsky, 1991). Another study analysed official tourism promotional brochures to explore whether situational, interpersonal, and ideational meanings realized in promotional texts could facilitate smooth communication with the public (Valdeón, 2009).

This study employs both case and textual analysis to design the narrative structure, focusing on “traditional residences” from Shanghai’s immovable cultural relics as the research subject. The narrative materials are drawn from the official descriptions provided by the Shanghai Library (https://data.library.sh.cn/shnh/wkl/webapi/hsly/building/toRelicDirectory). A methodological pipeline of text segmentation, feature vectorization, and clustering analysis was applied to categorize narrative structures. The narrative texts were first cleaned and segmented using natural language processing techniques. Subsequently, automatic event extraction and conflict-turn analysis were performed to construct event sequences and emotional trajectories. The extracted results were validated through a comparison between system outputs and manually annotated data. Second, feature values such as event density, story climax position, and temporal markers were extracted to generate document semantic vectors. After standardizing the features, KMeans clustering was performed with k ranging from [2, 6] (Arbelaitz et al., 2013). Finally, a Cluster Stability Saturation test was conducted by gradually increasing the sample size and using repeated sampling to examine the consistency of clustering results (Hennink et al., 2017). As a result, widely used narrative patterns in the promotion of Shanghai traditional residences were identified, and one pattern was selected as a reference for designing the digital narrative structure in this study.

Based on historical materials such as village annals, the above content was refined to confirm key narrative timelines and story details, optimise story logic and structural integrity, and ultimately develop a digital narrative framework for the traditional residence. At the same time, this paper also designed an interactive website based on the narrative framework to demonstrate achievable forms of digital storytelling.

When transitioning from research and analysis to the narrative stage, the amount of information in the scenes was significantly reduced, while the results of data analysis helped retain the key events (Carbonell et al., 2017). As shown in Fig. 3, traditional residences contain different types of “data”, including architecture, environment, and people. The data were connected through relationships such as interpersonal, environmental, and event-based links. When these relationships interact, they form the “plot” of a story. The plot represents the turning points in the story’s development, and by arranging and combining the plots, logically connected story “scenes” were constructed (Bang, 1993).

Data symbols related to Nanyin Hall include multiple types, such as character relationships, geographical locations, items inside houses, and architectural components. Character relationships are represented by county annals, letters, contracts, land deeds, and family genealogies. Spatial symbols primarily refer to the macro-geographical environment and natural climate of the residence. Structural symbols refer to architectural components such as columns, beams, and rafters. Cultural relic symbols refer to movable decorative items and furniture within a residence, with this data primarily consisting of images, film, and photographs. Trace symbols refer to the assessment of residents’ living habits through wear and damage conditions. For example, the varying degrees of wear on each staircase segment and step indicate the primary living areas, while the material and colour of doors and windows reveal the timing and frequency of renovations. This paper focuses on natural geographical symbols that most strongly influence the development of residential buildings, such as geographical location, terrain, residence types, and building environment, as the source of narrative content.

The following five plots are used as examples to illustrate in detail how narrative plots can be constructed through the characteristics of data symbols:

Plot 1: First, DEM geographic location data were extracted to analyze how the Pang family prospered. Fig. 4 shows the topographic map of Nanyin Hall and its surrounding area, where the house was clearly located near the coastline. This site once served as a vital route for port merchants engaged in trade. The continuous flow of people generated demands for food, accommodation, and daily necessities, which fostered the development of commercial activities. This explains why the family chose to build the residence at this location in 1906. However, the shifting river channels led to its gradual decline around 1969. With governmental support, the site saw prospects for new development again in 2016. Interviews with the descendants of the Pang family further confirmed this narrative.

Plot 2: Second, architectural feature data were extracted. Fig. 5 shows that segmenting old photographs of Nanyin Hall in the village annals revealed roofs, doors, and windows. Further extraction of image features from other Jiaoquan house reveals that this type of residence shares highly consistent architectural characteristics: enclosed by high walls on all four sides, presenting an overall “回” shape, the roof structure features hinged gable roofs; most houses have a single entrance, wooden doors and windows, and some retain coin-shaped ventilation holes.

Plot 3: China’s terrain is high in the west and low in the east, distributed in a stepped pattern. Building type data were extracted, and cluster analysis was performed on building types across China. Fig. 6 shows that building types are basically similar to the national geographical regional division, reflecting the impact of natural geographical location on building appearance. For example, Cluster 5 lies in a temperate monsoon climate with concentrated but low precipitation; roofs are generally flat for drying grain. Cluster 1, where Nanyin Hall is located, has a tropical monsoon climate with sloped roofs to reduce rainwater accumulation during the rainy season.

This clustering analysis further illustrates how environmental factors shape architectural evolution, offering a data-backed perspective that enriches narratives by connecting physical forms to broader ecological and climatic stories.

Plot 4: We will continue to analyse the geographical location data. Fig. 7 shows the surface elevation information near Nanyin Hall, indicating that river course changes shifted the residence away from the confluence of the rivers, decreasing merchant traffic and contributing to the Pang family’s commercial decline.

Plot 5: The following analysis is based on architectural planning data. The country adheres to the policy of “integrated urban-rural development”, and the suburbs where Nanyin Hall is located are being continuously optimised and improved. Using the urban planning data, we take a high-grade residence in the urban area of Minhang District as an example and count the types of facilities within a 3-kilometre radius of the residence. Based on density analysis, we predict the types of facilities that need to be added to Nanyin Hall. As Fig. 8 shows, facilities within three kilometres of the downtown area include police stations, hospitals, and hotels. However, around Nanyin Hall, only police stations and hotels exist; to achieve integrated development of the urban and rural areas, banks, schools, and shopping malls should be added in the future.

The above events reflect the rise and fall of the Pang family, as well as the physical characteristics of Nanyin Hall, its natural environment, and predictions for future development.

The five narrative plots described above will be organized and expressed through the narrative structure, ultimately forming the narrative scenes, which constitute the narrative content within the framework of this study. Next, we will continue with a structural analysis to determine the order in which these events occurred.

According to Ryan’s cross-media narrative framework, users establish two types of character relations when engaging with digital narratives: those between real persons and story characters. Within the story, characters may appear through first-person, second-person, or third-person perspectives. The real person, i.e., the user, can adopt either an “internal” or an “external” position. As shown in Fig. 10, when users engage with the story from an internal perspective, they project themselves into the virtual world and become a story character; from an external perspective, they follow the story from the standpoint of the real world.

Personal pronouns can influence the narrative experience in literary reading. The first person is the narrator presenting the story as a personal experience, giving readers a sense of being in the scene, and more easily attracting readers by directly expressing their inner activities to trigger empathy (Hartung et al., 2016). Therefore, this paper uses a first-person narrative design to create a sense of immersion for participants, making them curious about the outcome of the story.

Through the above research, five narrative plots were identified and arranged according to narrative structure C. The narrative unfolds from a first-person perspective, resulting in the digital narrative script of Nanyin Hall, as shown in Fig. 11. The overall design adopts a flashback technique, embedding the protagonist’s memories within the progression of the story to create the climax, thereby presenting a narrative thread that integrates “architecture, family, and city”. The unnumbered sections are supplemented with plot elements derived from relevant literature to ensure the completeness of the narrative.

The final story text and narrative structure are as follows:

Beginning — I was born in 1960, a descendant of the Pang family, and settled abroad with my parents after the decline of the family business (around 1969). Recently, I had the opportunity to come back and revisit this ancestral home because the family house needed to be partially demolished and then newly constructed (in 2022). The old family house was situated around the Huangpu River, and it was at that time (1906) that the family thrived because it lay at the confluence of two ferry ports (Plot 1). The house was a typical Shanghai-style building with grey tiles and white walls, mortise and tenon joints, and carved beams and painted rafters. Facing south, the house had two main courtyards with seven bays each, totaling 22 rooms. During the renovation of the ancestral house, I discovered many design drawings made by the elders when building the house.

Process of memory — I gradually recalled some of my childhood memories:

At that time, I would listen to my grandpa’s stories about the past, and he once told me that this house was built by the 10th ancestor, Pang YunGong, which I remembered in my heart. I also played hide-and-seek with my grandfather in various parts of the house, and I always liked to hide by the fence outside the door (Plot 2).

I also recall that there was a patch of osmanthus trees on the south side of the house, and when they bloomed in the summer, my mother would always pick them in the morning to make food, and in the winter, she would build poles on the beams of the house to hang bacon. The land near the house was perfect for growing rice, cotton, and oilseed rape, and the harvest season was always filled with laughter.

But my favourite thing was to go everywhere with my parents, especially to the north, which was very different from my home, and I found it very strange (Plot 3).

When I grew up, my father took care of the family shop at first, but after the dredging of the Sanlin harbour a few years ago (1956), there were fewer and fewer people there, and we soon moved out of the harbour to other places (Plot 4).

Ending — Eventually, after months of hard work, the old house was given a new look. It not only retained the “Seven-Person Dragon Dance” on the square wood, the Xixiangji opera text on the furniture, and the green bricks in the heart of the court but also incorporated modern craftsmanship to repair structural problems such as settling and tilting. Later, it was designated to host cultural exhibitions and other functions, as well as to improve the surrounding residents’ living conditions (Plot 5). On the day of its reopening, I stood in front of the window looking at what was in front of me, and my heart was filled with pride and emotion. I understand that this is not only respect for the ancestors but also a new future for us.

Based on the research methods described above, the temporal, event-related, and emotional elements of the narrative content were extracted and analysed to verify their arrangement. The final story structure and content are shown in Fig. 12, which conforms to the characteristics of Structure C.

Based on the above, this study developed an interactive website to demonstrate the possible forms of digital narrative (URL: https://mhg500569.wixsite.com/my-site-1), as shown in Fig. 13. The webpage includes three parts. According to human visual habits, when seeing an interface, we do not follow a fixed reading order, but the brain receives information influenced by factors such as colour, size, and shape. Therefore, the narrative is presented with images as the primary focus and text as supplementary content to reduce redundant information, and the overall screen uses real photos of Nanyin Hall as the background to immerse readers in a real atmosphere.

The “Home” page presents the complete story of the house, based on the narrative script. The “Story source” section explains the image features, describes what they represent, and clarifies the source of the narrative content. The ultimate goal of the digital narrative is to expand understanding of cultural heritage among all social strata, including young people, the elderly, non-professionals, and cross-cultural audiences, and to attract people to visit the site. The “About” section provides location information and briefly introduces the special food and landscape around the residence to attract the public to visit the site offline.

Through the online interactive website, we aim to foster users’ understanding of residential culture through data interpretation and evoke emotional resonance with their own experiences by inviting them to follow the story’s protagonist. In this way, users may form a lasting impression of the residence, advancing the dissemination of traditional residential cultural heritage.