Merge pull request #30 from poldrack/text/workflows-Dec27

Rename Python module from BetterCodeBetterScience to bettercode

Author: poldrack

CLAUDE.md

@@ -31,7 +31,7 @@ rm -rf book/_build
 pytest
 
 # Run tests with coverage
-pytest --cov=src/BetterCodeBetterScience --cov-report term-missing
+pytest --cov=src/bettercode --cov-report term-missing
 
 # Run specific test modules
 pytest tests/textmining/
@@ -62,7 +62,7 @@ pre-commit run --all-files
 ## Project Structure
 
 - `book/` - MyST markdown chapters (configured in myst.yml)
-- `src/BetterCodeBetterScience/` - Example Python code referenced in book chapters
+- `src/bettercode/` - Example Python code referenced in book chapters
 - `tests/` - Test examples demonstrating testing concepts from the book
 - `data/` - Data files for examples
 - `scripts/` - Utility scripts

book/AI_coding_assistants.md

@@ -96,7 +96,7 @@ def linear_regression_normal_eq(X: np.ndarray, y: np.ndarray) -> np.ndarray:
 ```
 
 Unlike the previous examples, the code now includes type hints.
-It's always a bad idea to generalize from a single result, so we ran these prompts through ChatGPT 10 times each (using the Openai API to generate them programmatically; see the [notebook](../src/BetterCodeBetterScience/incontext_learning_example.ipynb)).
+It's always a bad idea to generalize from a single result, so we ran these prompts through ChatGPT 10 times each (using the Openai API to generate them programmatically; see the [notebook](../src/bettercode/incontext_learning_example.ipynb)).
 Here are the function signatures generated for each of the 10 runs without mentioning type hints:
 
 ```
@@ -272,7 +272,7 @@ In addition to the time and labor of running things by hand, it is also a recipe
 
 You might be asking at this point, "What's an API"? The acronym stands for "Application Programming Interface", which is a method by which one can programmatically send commands to and receive responses from a computer system, which could be local or remote[^1].
 To understand this better, let's see how to send a chat command and receive a response from the Claude language model.
-The full outline is in [the notebook](https://github.com/poldrack/BetterCodeBetterScience/blob/main/src/BetterCodeBetterScience/language_model_api_prompting.ipynb).
+The full outline is in [the notebook](https://github.com/poldrack/BetterCodeBetterScience/blob/main/src/bettercode/language_model_api_prompting.ipynb).
 Coding agents are very good at generating code to perform API calls, so I used Claude Sonnet 4 to generate the example code in the notebook:
 
 ```python
@@ -358,7 +358,7 @@ Let's see how we could get the previous example to return a JSON object containi
 Here we will use a function called `send_prompt_to_claude()` that wraps the call to the model object and returns the text from the result:
 
 ```python
-from BetterCodeBetterScience.llm_utils import send_prompt_to_claude
+from bettercode.llm_utils import send_prompt_to_claude
 
 json_prompt = """
 What is the capital of France? 

book/data_management.md

@@ -471,7 +471,7 @@ df_merged = pd.concat([df1, df2, df3], ignore_index=True)
 
 The most common file formats are *comma-separated value* (CSV) or *tab-separated value* (TSV) files.  Both of these have the benefit of being represented in plain text, so their contents can be easily examined without any special software.  I generally prefer to use tabs rather than commas as the separator (or *delimiter*), primarily because they can more easily naturally represent longer pieces of text that may include commas. These can also be represented using CSV, but they require additional processing in order to *escape* the commas within the text so that they are not interpreted as delimiters.  
 
-Text file formats like CSV and TSV are nice for their ease of interpretability, but they are highly inefficient for large data compared to optimized file formats, such as the *Parquet* format.  To see this in action, I loaded a brain image and saved all of the non-zero data points (857,785 to be exact) to a data frame, which I then saved to CSV and Parquet formats; see [the management notebook](src/BetterCodeBetterScience/data_management.ipynb) for details.  Looking at the resulting files, we can see that the Parquet file is only about 20% the size of the CSV file:
+Text file formats like CSV and TSV are nice for their ease of interpretability, but they are highly inefficient for large data compared to optimized file formats, such as the *Parquet* format.  To see this in action, I loaded a brain image and saved all of the non-zero data points (857,785 to be exact) to a data frame, which I then saved to CSV and Parquet formats; see [the management notebook](src/bettercode/data_management.ipynb) for details.  Looking at the resulting files, we can see that the Parquet file is only about 20% the size of the CSV file:
 
 ```bash
 ➤  du -sk /tmp/brain_tabular.*
@@ -718,7 +718,7 @@ In this section we discuss data organization. The most important principle of da
 
 ### File granularity
 
-One common decision that we need to make when managing data is to save data in more smaller files versus fewer larger files.  The right answer to this question depends in part on how we will have to access the data.  If we only need to access a small portion of the data and we can easily determine which file to open to obtain those data, then it probably makes sense to save many small files.  However, if we need to combine data across many small files, then it likely makes sense to save the data as one large file.  For example, in the [data management notebook](src/BetterCodeBetterScience/data_management.ipynb) there is an example where we create a large (10000 x 100000) matrix of random numbers, and save them either to a single file or to a separate file for each row.  When loading these data, the loading of the single file is about 5 times faster than loading the individual files.
+One common decision that we need to make when managing data is to save data in more smaller files versus fewer larger files.  The right answer to this question depends in part on how we will have to access the data.  If we only need to access a small portion of the data and we can easily determine which file to open to obtain those data, then it probably makes sense to save many small files.  However, if we need to combine data across many small files, then it likely makes sense to save the data as one large file.  For example, in the [data management notebook](src/bettercode/data_management.ipynb) there is an example where we create a large (10000 x 100000) matrix of random numbers, and save them either to a single file or to a separate file for each row.  When loading these data, the loading of the single file is about 5 times faster than loading the individual files.
 
 Another consideration about the number of files has to do with storage systems that are commonly used on high-performance computing systems.  On these systems, it is common to have separate quotas for total space used (e.g., in terabytes) as well as for the number of *inodes*, which are structures that store information about files and folders on a UNIX filesystem. Thus, generating many small files (e.g., millions) can sometimes cause problems on these systems. For this reason, we generally err on the side of generating fewer larger files versus more smaller files when working on high-performance computing systems.
 
@@ -1038,7 +1038,7 @@ unlock(ok): my_datalad_repo/data/demographics.csv (file)
 We then use a Python script to make the change, which in this case is removing some columns from the dataset:
 
 ```bash
-➤  python src/BetterCodeBetterScience/modify_data.py my_datalad_repo/data/demographics.csv
+➤  python src/bettercode/modify_data.py my_datalad_repo/data/demographics.csv
 
 ```
 
@@ -1074,15 +1074,15 @@ nothing to save, working tree clean
 Although the previous example was meant to provide background on how DataLad works, in practice there is actually a much easier way to accomplish these steps, which is by using the [`datalad run`](https://docs.datalad.org/en/stable/generated/man/datalad-run.html) command. This command will automatically take care of fetching and unlocking the relevant files, running the command, and then committing the files back in, generating a commit message that tracks the specific command that was used:
 
 ```bash
-➤  datalad run -i my_datalad_repo/data/demographics.csv -o my_datalad_repo/data/demographics.csv -- uv run src/BetterCodeBetterScience/modify_data.py my_datalad_repo/data/demographics.csv
+➤  datalad run -i my_datalad_repo/data/demographics.csv -o my_datalad_repo/data/demographics.csv -- uv run src/bettercode/modify_data.py my_datalad_repo/data/demographics.csv
 [INFO   ] Making sure inputs are available (this may take some time)
 unlock(ok): my_datalad_repo/data/demographics.csv (file)
 [INFO   ] == Command start (output follows) =====
       Built bettercodebetterscience @ file:///Users/poldrack/Dropbox/code/BetterCode
 Uninstalled 1 package in 1ms
 Installed 1 package in 1ms
 [INFO   ] == Command exit (modification check follows) =====
-run(ok): /Users/poldrack/Dropbox/code/BetterCodeBetterScience (dataset) [uv run src/BetterCodeBetterScience/modif...]
+run(ok): /Users/poldrack/Dropbox/code/BetterCodeBetterScience (dataset) [uv run src/bettercode/modif...]
 add(ok): data/demographics.csv (file)
 save(ok): my_datalad_repo (dataset)
 add(ok): my_datalad_repo (dataset)
@@ -1095,12 +1095,12 @@ commit 3ef3b94a0abffec6a8db7570a97339f48ee728ed (HEAD -> text/datamgmt-Nov3)
 Author: Russell Poldrack <poldrack@gmail.com>
 Date:   Mon Dec 15 13:28:06 2025 -0800
 
-    [DATALAD RUNCMD] uv run src/BetterCodeBetterScience/modif...
+    [DATALAD RUNCMD] uv run src/bettercode/modif...
 
     === Do not change lines below ===
     {
      "chain": [],
-     "cmd": "uv run src/BetterCodeBetterScience/modify_data.py my_datalad_repo/data/demographics.csv",
+     "cmd": "uv run src/bettercode/modify_data.py my_datalad_repo/data/demographics.csv",
      "exit": 0,
      "extra_inputs": [],
      "inputs": [
@@ -1220,7 +1220,7 @@ The question that I will ask is as follows: How well can the biological similari
 - A dataset of genome-wise association study (GWAS) results for specific traits obtained from [here](https://www.ebi.ac.uk/gwas/docs/file-downloads).
 - Abstracts that refer to each of the traits identified in the GWAS result, obtained from the [PubMed](https://pubmed.ncbi.nlm.nih.gov/) database.  
 
-I will not present all of the code for each step; this can be found [here](src/BetterCodeBetterScience/database_example_funcs.py) and [here](src/BetterCodeBetterScience/database.py). Rather, I will show portions that are particularly relevant to the databases being used. 
+I will not present all of the code for each step; this can be found [here](src/bettercode/database_example_funcs.py) and [here](src/bettercode/database.py). Rather, I will show portions that are particularly relevant to the databases being used. 
 
 ### Adding GWAS data to a document store
 
@@ -1236,7 +1236,7 @@ In this case, looking at the data we see that several columns contain multiple v
 gwas_data = get_exploded_gwas_data()
 ```
 
-We can now import the data from this data frame into a MongoDB collection, mapping each unique trait to the genes that are reported as being associated with it.  First I generated a separate function that sets up a MongoDB collection (see `setup_mongo_collection` [here](src/BetterCodeBetterScience/database.py)).  We can then use that function to set up our gene set collection:
+We can now import the data from this data frame into a MongoDB collection, mapping each unique trait to the genes that are reported as being associated with it.  First I generated a separate function that sets up a MongoDB collection (see `setup_mongo_collection` [here](src/bettercode/database.py)).  We can then use that function to set up our gene set collection:
 
 
 ```python

book/project_organization.md

@@ -237,7 +237,7 @@ A final way that one might use notebooks is as a way to create standalone progra
 
 It's very common for researchers to use different coding languages to solve different problems.  A common use case is the Python user who wishes to take advantage of the much wider range of statistical methods that are implemented in R.  There is a package called `rpy2` that allows this within pure Python code, but it can be cumbersome to work with, particularly due to the need to convert complex data types.  Fortunately, Jupyter notebooks provide a convenient solution to this problem, via [*magic* commands](https://scipy-ipython.readthedocs.io/en/latest/interactive/magics.html).  These are commands that start with either a `%` (for line commands) or `%%` for cell commands, which enable additional functionality.    
 
-An example of this can be seen in the [mixing_languages.ipynb](src/BetterCodeBetterScience/notebooks/mixing_languages.ipynb) notebook, in which we load and preprocess some data using Python and then use R magic commands to analyze the data using a package only available within R.  In this example, we will work with data from a study published by our laboratory (Eisenberg et al., 2019), in which 522 people completed a large battery of psychological tests and surveys.  We will focus here on the responses to a survey known as the "Barratt Impulsiveness Scale" which includes 30 questions related to different aspects of the psychological construct of "impulsiveness"; for example, "I say things without thinking" or "I plan tasks carefully".  Each participant rated each of these statements on a four-point scale from 'Rarely/Never' to 'Almost Always/Always'; the scores were coded so that the number 1 always represented the most impulsive choice and 4 represented the most self-controlled choice.  
+An example of this can be seen in the [mixing_languages.ipynb](src/bettercode/notebooks/mixing_languages.ipynb) notebook, in which we load and preprocess some data using Python and then use R magic commands to analyze the data using a package only available within R.  In this example, we will work with data from a study published by our laboratory (Eisenberg et al., 2019), in which 522 people completed a large battery of psychological tests and surveys.  We will focus here on the responses to a survey known as the "Barratt Impulsiveness Scale" which includes 30 questions related to different aspects of the psychological construct of "impulsiveness"; for example, "I say things without thinking" or "I plan tasks carefully".  Each participant rated each of these statements on a four-point scale from 'Rarely/Never' to 'Almost Always/Always'; the scores were coded so that the number 1 always represented the most impulsive choice and 4 represented the most self-controlled choice.  
 
 In order to enable the R magic commands, we first need to load the rpy2 extension for Jupyter:
 
@@ -526,7 +526,7 @@ test output from container
 To create a reproducible software execution environment, we will often need to create our own new Docker image that contains the necessary dependencies and application code.  AI coding tools are generally quite good at creating the required `Dockerfile` that defines the image. We use the following prompt to Claude Sonnet 4:
 
 ```
-I would like to generate a Dockerfile to define a Docker image based on the python:3.13.9 image.  The Python package wonderwords should be installed from PyPi. A local Python script should be created that creates a random sentence using wonderwords.RandomSentence() and prints it.  This script should be the entrypoint for the Docker container.  Create this within src/BetterCodeBetterScience/docker-example inside the current project.  Do not create a new workspace - use the existing workspace for this project.
+I would like to generate a Dockerfile to define a Docker image based on the python:3.13.9 image.  The Python package wonderwords should be installed from PyPi. A local Python script should be created that creates a random sentence using wonderwords.RandomSentence() and prints it.  This script should be the entrypoint for the Docker container.  Create this within src/bettercode/docker-example inside the current project.  Do not create a new workspace - use the existing workspace for this project.
 ```
 
 Here is the content of the resulting `Dockerfile`:

book/software_engineering.md

@@ -758,7 +758,7 @@ C = 299792458
 We could then import this from our module within the iPython shell:
 
 ```
-In: from BetterCodeBetterScience.constants import C
+In: from bettercode.constants import C
 
 In: C
 Out: 299792458
@@ -793,7 +793,7 @@ class Constants:
 Then within our iPython shell, we generate an instance of the Constants class, and see what happens if we try to change the value once it's instantiated:
 
 ```
-In: from BetterCodeBetterScience.constants import Constants
+In: from bettercode.constants import Constants
 
 In: constants = Constants()
 
@@ -806,7 +806,7 @@ AttributeError                            Traceback (most recent call last)
 Cell In[4], line 1
 ----> 1 constants.C = 42
 
-File ~/Dropbox/code/BetterCodeBetterScience/src/BetterCodeBetterScience/constants.py:11, in Constants.__setattr__(self, name, value)
+File ~/Dropbox/code/BetterCodeBetterScience/src/bettercode/constants.py:11, in Constants.__setattr__(self, name, value)
      10 def __setattr__(self, name, value):
 ---> 11     raise AttributeError("Constants cannot be modified")
 
@@ -847,8 +847,8 @@ We see that `ruff` detects both formatting problems (such as the lack of spaces
 We can also use `ruff` from the command line to detect and fix code problems:
 
 ```bash
-❯ ruff check src/BetterCodeBetterScience/formatting_example.py
-src/BetterCodeBetterScience/formatting_example.py:6:1: F403 `from numpy.random import *` used; unable to detect undefined names
+❯ ruff check src/bettercode/formatting_example.py
+src/bettercode/formatting_example.py:6:1: F403 `from numpy.random import *` used; unable to detect undefined names
   |
 4 | # Poorly formatted code for linting example
 5 |
@@ -858,7 +858,7 @@ src/BetterCodeBetterScience/formatting_example.py:6:1: F403 `from numpy.random i
 8 | mynum=randint(0,100)
   |
 
-src/BetterCodeBetterScience/formatting_example.py:8:7: F405 `randint` may be undefined, or defined from star imports
+src/bettercode/formatting_example.py:8:7: F405 `randint` may be undefined, or defined from star imports
   |
 6 | from numpy.random import *
 7 |
@@ -872,12 +872,12 @@ Found 2 errors.
 Most linters can also automatically fix the issues that they detect in the code. `ruff` modifies the file in place, so we will first create a copy (so that our original remains intact) and then run the formatter on that copy:
 
 ```bash
-❯ cp src/BetterCodeBetterScience/formatting_example.py src/BetterCodeBetterScience/formatting_example_ruff.py
+❯ cp src/bettercode/formatting_example.py src/bettercode/formatting_example_ruff.py
 
-❯ ruff format src/BetterCodeBetterScience/formatting_example_ruff.py
+❯ ruff format src/bettercode/formatting_example_ruff.py
 1 file reformatted
 
-❯ diff src/BetterCodeBetterScience/formatting_example.py src/BetterCodeBetterScience/formatting_example_ruff.py
+❯ diff src/bettercode/formatting_example.py src/bettercode/formatting_example_ruff.py
 1,3d0
 <
 <