Building out the citation network and making use of it

[mlissner]

I'm a {professor|journalists|person} that wants to work with the citation network of SCOTUS cases. I want to use Python and, ideally, networkx. How would I do this? Is the bulk data best or the API or replication?

Any tips/tricks?

[mlissner]

Yeah, this isn't very easy, I'm sorry to say. The data model is pretty complicated and pretty large, but here's what I would do.

I'd start by grabbing the bulk data files that indicates what Opinion objects cite what Opinion objects:

curl 'https://storage.courtlistener.com/bulk-data/citation-map-2023-12-04.csv.bz2'`

On its own, this file is useless. It's just three columns of numbers:

citing_opinion	cited_opinion	depth
11	22	1
422	79	3

In human terms:

• Opinion 11 cites opinion 22 once.
• Opinion 422 cites opinion 79 three times.

Simple enough, and you could load this up into a weighted directed graph using the networkx tools. I haven't used those in a while, but I recall they're something like:

g = Graph()
g.add_edge(11, 22, weight=1)

That'd give you a nice graph.¹

Anyhow, you only wanted opinions from SCOTUS. This should be possible,² and to do this you have to join a number of bulk data files:

• Opinion objects are grouped into OpinionCluster objects
• OpinionClusters are grouped on Docket objects
• Dockets are in particular courts

So to find only the Opinion objects in SCOTUS, you'll need to join the data together:

1. Start by finding the Dockets that are in SCOTUS (they'll have a court_id field of scotus). Let's say the IDs of those dockets are 22, 44, and 88.

2. Using those numbers, you'll have to find the OpinionClusters that have those values in their docket_id field. Let's say those are OpinionClusters 33, 55, and 99.

3. Finally, find the Opinion objects that have those those numbers in their cluster_id field. Let's say those are numbers 111, 444, and 777.

And those numbers in the citinng_id field of the citation map file we began with, and you're off to the races.

---

Footnotes

Footnotes

1. A word of warning though: When I tried this awhile back, the graph was too large to fit in memory and it didn't work. I wound up using igraph, as I recall, which is written in C, more performant and more compact, but less ergonomic. ↩

2. When we add a historical document that we were missing from a century ago, or even if we add a citation to a case from some time ago, we don't usually go back and figure out what future cases cite that new data. So, imagine that we learn we're missing a citation from 1950. We go back and add it to a case, and so now that case can be cited. But between 1950 and today lots of cases did cite that case, and we don't immediately go back and figure that out.

   We probably should re-run our citation finder across the entire collection, but we keep adding historical citations, so we want to wait until that's done to re-run the citation finder. ↩